Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegraphics@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 480 insertions, 0 deletions

diff --git a/doc/kdvi/KDVI-features.tex b/doc/kdvi/KDVI-features.tex
new file mode 100644
index 00000000..66c3f9f5
--- /dev/null
+++ b/doc/kdvi/KDVI-features.tex
@@ -0,0 +1,480 @@
+\documentclass{article}
+
+\usepackage{amstext}
+\usepackage{colordvi}
+\usepackage{graphicx}
+\usepackage{times} 
+\usepackage[arrow,matrix,curve,ps]{xy}
+\xyoption{dvips}
+\usepackage[active]{srcltx}
+\usepackage[hypertex]{hyperref}
+\sloppy
+
+\newcommand{\KDVI}{{\sf KDVI 1.1}}
+
+\begin{document}
+
+\title{Support for \TeX\ extensions in \KDVI}
+
+\author{Stefan Kebekus}
+
+\maketitle
+\begin{abstract}
+  This document describes the extensions to the standard format of DVI
+  files which \KDVI\ implements in order to support PostScript
+  inclusion and hyperlinks.
+  
+  \KDVI\ is a program that displays DVI-files generated by the \TeX\ 
+  typesetting system. If you don't know what \TeX\ is then you are
+  most likely not interested in this. If you would like to know how to
+  use special features of \KDVI, then you can find examples here.
+\end{abstract}
+
+\tableofcontents
+
+\section{What's all this}
+
+The DVI-previewing program \KDVI\ is able to display standard
+DVI-files as specified in \cite{Level0Std}. In order to support
+graphics inclusion, hyperlinks and non-standard fonts, \KDVI\ 
+implements a number of features which extend \cite{Level0Std}. In
+particular, \KDVI\ supports a number of \TeX 's $\backslash${\tt
+  special} commands. The aim of this document is to describe these
+extensions and give examples of their use.
+
+Unfortunately, in spite of several attempts to find a sound standard
+for the use of $\backslash${\tt special} commands, there is now a
+wealth of competing and mutually incompatible definitions.
+
+\KDVI\ does not attempt to support all possible features. Instead, we
+tried to implement those which are most useful and used most commonly.
+In this, we have tried to be consistent with the {\sf dvips} program.
+\KDVI\ does not support a number of outdated and unsane standards, nor
+does it support features which impair the system security.
+
+
+\section{Virtual fonts}
+
+\KDVI\ supports ``virtual fonts''. This enables \TeX\ to use
+PostScript fonts. For more information, and a complete specification,
+consult \cite{dvips}.
+
+\paragraph*{Example}
+
+This text uses the ``Times'' family of fonts instead of the ``Computer
+Modern'' fonts which are usually used by \TeX. This was realized in
+\LaTeX 2$\epsilon$ by including the line
+\begin{verbatim}
+\usepackage{times} 
+\end{verbatim}
+in the header of this document.
+
+
+\section{PostScript support}
+
+\KDVI\ implements basic facilities to include PostScript graphics in a
+DVI file, which will enable the reader to conviently read most
+scientific papers which use such features. 
+
+\subsection{Literal PostScript}
+
+\KDVI\ supports the inclusion of PostScript into DVI-files by means of
+the quote-special. The syntax follows the specification of
+\cite{dvips}:
+\begin{verbatim}
+\special{" PostScript-commands}
+\end{verbatim}
+The PostScript-commands are not directly included, in fact they are
+sandwiched between a {\tt save} and {\tt restore} pair. That way
+\KDVI\ ensures that the command cannot affect PostScript-commands
+which appear somewhere else in your file.
+
+\paragraph*{Example}
+
+Figure~\ref{quote-special} shows an example taken from \cite{dvips}.
+The generating \TeX -code is
+\begin{verbatim}
+\vbox to 100bp{\vss
+\special{" newpath 0 0 moveto 100 100 lineto
+ 300 0 lineto closepath gsave 0.8 setgray fill 
+ grestore stroke}}
+\end{verbatim}
+
+\begin{figure}
+\vbox to 100bp{\vss
+\special{" newpath 0 0 moveto 100 100 lineto 300 0 lineto closepath gsave 0.8 setgray fill grestore stroke}}
+\caption{Graphic generated by literal PostScript inclusion\label{quote-special}}
+\end{figure}
+
+
+\subsection{Direct PostScript}
+
+\KDVI\ supports the inclusion of PostScript into DVI-files by means of
+the direct-special. The syntax follows the specification of
+\cite{dvips}:
+\begin{verbatim}
+\special{ps: Postscript-commands}
+\end{verbatim}
+The PostScript-commands are directly included, and there is no
+protective {\tt save} and {\tt restore} pair. The use of this command
+is not recommended, as it may have funny side effects on other
+PostScript commands which appear later in your file.
+
+\KDVI\ also supports the following syntactical variants which are
+explained in \cite{dvips}:
+\begin{verbatim}
+\special{ps: Postscript-commands}
+\special{ps::[begin] Postscript-commands}
+\special{ps:: Postscript-commands}
+\special{ps::[end] Postscript-commands}
+\end{verbatim}
+The variant
+\begin{verbatim}
+\special{ps: plotfile filename}
+\end{verbatim}
+is not currently supported.
+
+\paragraph*{Example}
+
+The command
+\begin{verbatim}
+\includegraphics[height=3cm, angle=20]{aboutkde.ps}
+\end{verbatim}
+which is used in section~\ref{chap:eps} uses the direct-special
+internally in order to set the rotation.
+
+\subsection{Literal headers}
+
+Literal headers work as described in \cite{dvips}.
+\begin{verbatim}
+\special{! PostScript-Header-commands}
+\end{verbatim}
+
+\paragraph*{Example}
+The following diagram, which was generated using the \Xy -pic macro
+packages uses literal postscript inclusion which relies on literal
+headers.
+$$
+\xymatrix{ {\tilde X}
+  \ar@{-->}[rrd]_{\exists \alpha} \ar[rrrr]^{\eta}_{\txt{\tiny
+      normalization}} \ar@/_/ [rrdd]_ {\tilde \pi} & & & & {X}
+  \ar@/^/[lldd]^{\pi}  \\ & & {X'}
+  \ar@{-->}[rru]_{\exists \beta} \ar@{-->}[d]_{\exists \pi'} & & \\ & &
+  {Y}& &}
+$$
+Note that the actual headers are defined on the first page of the
+document. This was a major source of trouble in earlier versions of
+KDVI.
+
+
+
+\subsection{PostScript headers}
+
+PostScript headers work as described in \cite{dvips}. This command is
+very similar to the literal header command, but expects the name of a
+file which should be included.
+\begin{verbatim}
+\special{header=filename}
+\end{verbatim}
+
+
+
+
+\subsection{EPS inclusion}\label{chap:eps}
+
+A popular way to include PostScript-files into \TeX\ documents uses
+the PSFile $\backslash${\tt special} command. Again this is explained
+in detail in \cite{dvips}. Currently \KDVI\ supports the syntax
+\begin{verbatim}
+\special{psfile=File keyword=value keyword=value ...}
+\end{verbatim}
+Where keyword is one of the following
+\begin{description}
+\item[llx] lower left corner of the bounding box, $x$-coordinate
+\item[lly] lower left corner of the bounding box, $y$-coordinate
+\item[urx] upper right corner of the bounding box, $x$-coordinate
+\item[ury] upper right corner of the bounding box, $y$-coordinate
+\item[rwi] width of the bounding box. If $llx-urx \not = rwi$, then
+the boundig box is scaled accordingly. 
+\item[rhi] height of the bounding box If $lly-ury \not = rhi$, then
+the boundig box is scaled accordingly.
+\item[angle] rotates the picture counterclockwise
+\end{description}
+Unknown keywords are silently ignored. The keywords {\tt llx}, {\tt
+  lly}, {\tt urx}, {\tt ury} and {\tt rwi} are usually generated by
+the {\tt epsf} macros.  The keywords {\tt hoffset}, {\tt voffset},
+{\tt hsize}, {\tt vsize}, {\tt hscale}, {\tt vscale}, {\tt angle} and
+{\tt clip} are not currently implemented. The ``uncompression''
+feature of {\sf dvips} and {\sf xdvi} which allows to execute
+arbitrary commands in via the syntactical variant
+\begin{verbatim}
+\special{psfile="'shell-command" keyword=value ...}
+\end{verbatim}
+is deliberately not implemented for security reasons.
+
+\paragraph*{Example}
+Figure~\ref{epsf-special} shows an embedded postscript-file. 
+\begin{figure}
+  \begin{center}
+    \includegraphics[height=3cm]{aboutkde.ps}
+    \includegraphics[height=4cm]{aboutkde.ps}
+    \includegraphics[height=3cm, angle=20]{aboutkde.ps}
+  \end{center}
+\caption{Embedded PostScript graphic\label{epsf-special}}
+\end{figure}
+This was easily realized by including the line
+\begin{verbatim}
+\usepackage{graphicx}
+\end{verbatim}
+into the header of this document, and the lines
+\begin{verbatim}
+\includegraphics[height=3cm]{aboutkde.ps}
+\includegraphics[height=4cm]{aboutkde.ps}
+\includegraphics[height=3cm, angle=20]{aboutkde.ps}
+\end{verbatim}
+at the place where the graphic should appear. It is strongly
+recommended to use the {\tt graphicx} macro package for this purpose.
+\begin{figure}
+  \begin{center}
+    \includegraphics[height=2cm, bb=0 0 150 50]{nonexistent.ps}
+  \end{center}
+\caption{Reference to a non-existent PS-file\label{nonex-special}}
+\end{figure}
+Figure~\ref{nonex-special} shows how \KDVI\ warns you about
+non-existent files.
+
+
+\section{Hypertext support}
+
+\KDVI\ supports commands for hyperlink support which commands
+establish links between sections of documents in a manner exactly
+analogous to the HTML of the WWW. For a detailed specification we
+refer to \cite{HFAQ99} or \cite{Rah98}. Note, however, that \KDVI\ 
+does currently not allow nested hyperlinks.
+
+\subsection{Hyper-Labels}
+
+The commands
+\begin{verbatim}
+\special{html:<a name="namestring">}
+\special{html:</a>}
+\end{verbatim}
+labels the current point of the text for later reference.
+
+\subsection{Hyper-References}
+
+The commands 
+\begin{verbatim}
+\special{html:<a href="hrefstring">}
+Text
+\special{html:</a>}
+\end{verbatim}
+makes {\tt Text} a link to {\tt hrefstring}, where {\tt hrefstring} is
+an absolute or relative URL in the standard format used on the
+internel. If {\tt hrefstring} is of the form {\tt \#label} then it
+points to the section of the current document which is labeled using
+the labeling command described above:
+\begin{verbatim}
+\special{html:<a name="namestring">}
+\end{verbatim}
+
+
+
+\paragraph*{Example}
+This document features a clickable table of contents, and also the
+references can be clicked on. This has been achieved by using the {\tt
+  hyperref} macro package in \LaTeX\ by including the line
+\begin{verbatim}
+\usepackage[hypertex]{hyperref}
+\end{verbatim}
+into the document preamble. Everything else is automatic.
+
+Here is an external link which points to the \href{http://www.kde.org}{main
+  website of the KDE project}. For this, the command {\tt href} of the
+{\tt hyperref} macro package was used:
+\begin{verbatim}
+\href{http://www.kde.org}{main
+  website of the KDE project}
+\end{verbatim}
+
+
+\paragraph{Warning.} On some installations, the {\tt
+  hyperref} macro package is configured to generate PostScript
+hyperlinks for {\tt dvips} by default. On these systems, using the
+line
+\begin{verbatim}
+\usepackage{hyperref}
+\end{verbatim}
+will generate DVI file whose hyperlinks are not visible in KDVI.
+Worse, KDVI will call the {\tt ghostview} PostScript interpreter for
+every page, which makes the display very slow.
+
+
+
+\section{Colored \Red{text} \Green{and} \Blue{background}}
+
+The DVI specials for colored text are supported as they are described
+in \cite{dvips}. 
+
+\paragraph*{Example} In this document, the following code was used to
+generate the text below.
+\begin{verbatim}
+\usepackage{colordvi}
+
+...
+
+\textGreen This text is green but here we are
+\Red{switching to red, \Blue{nesting blue}, 
+recovering the red} and back to original green.
+\textCyan The text from here on will be cyan 
+unless \Yellow{locally changed to yellow}. Now
+we are back to cyan. \textBlack
+\end{verbatim}
+
+This gave the following output:
+\begin{verse}
+ \textGreen This text is green but here
+we are \Red{switching to red, \Blue{nesting blue}, recovering the red}
+and back to original green.  \textCyan The text from here on will be
+cyan unless \Yellow{locally changed to yellow}. Now we are back to
+cyan.  \textBlack
+\end{verse}
+
+To set the background color of the page, the command
+\background{Lavender}
+\begin{verbatim}
+\background{Lavender}
+\end{verbatim}
+was used. To switch back to normal, the command
+\begin{verbatim}
+\background{White}
+\end{verbatim}
+was placed somewhere on the following page. As you see, the background
+command does not fit well into \LaTeX's philosophy and should be
+avoided.
+
+\section{Rotated Text}
+
+Rotated text can sometimes be useful, e.g. to fit large table onto a
+single page. This is used, e.g.~in the style files of journals of the
+American Astronomical Society. Here is one example.
+
+\begin{table}[h]
+  \centering
+\begin{tabular}{l|ll}
+  & \rotatebox{90}{uses \TeX} & \rotatebox{90}{uses Linux} \\ \hline
+  Stefan & $\times$ & $\times$ \\
+  Anke & & $\times$ \\
+  Thomas & $\times$ &\\
+\end{tabular}
+\end{table}
+
+This was easily realized by including the line
+\begin{verbatim}
+\usepackage{graphicx}
+\end{verbatim}
+into the header of this document. The table itself was then typeset by
+{\footnotesize
+\begin{verbatim}
+\begin{tabular}{l|ll}
+  & \rotatebox{90}{uses \TeX} & \rotatebox{90}{uses Linux} \\ \hline
+  Stefan & $\times$ & $\times$ \\
+  Anke & & $\times$ \\
+  Thomas & $\times$ &\\
+\end{tabular}
+\end{verbatim}
+}
+
+\section{Source text specials}
+
+\KDVI\ is able to make use of source file information which is included
+in the DVI file. To include source file information, a {\tt special}
+command like to following should be included at the beginning of every
+paragraph or every line:
+\begin{verbatim}
+\special{src:123text.tex}
+\end{verbatim}
+This tells \KDVI\ that the next paragraph should be associated with
+line 123 in the source file text.tex.
+
+It is of course not practical to add these commands manually to the
+beginning of every line ---see the \href{help:/kdvi}{Handbook of
+\KDVI} to learn how to add the special commands automatically to your
+DVI files.
+
+The main use of source file specials is the interaction between \KDVI\
+and your editor. Starting from version~1.0, both \emph{forward search}
+and \emph{inverse search} are supported.
+
+\subsection{Forward search}
+
+Forward search is a feature that helps you find the place in the DVI
+file that corresponds to a certain line in the source text. If source
+file information is included, you can find the place in the DVI file
+{\tt test.dvi} which corresponds to line 1234 in the source file {\tt
+text.tex} by starting \KDVI\ like this:
+\begin{verbatim}
+kdvi file:test.dvi#1234text.tex
+\end{verbatim}
+In pracitse, this command line will be generated by a script that
+communicates with your editor. Currently, scripts for Emacs and XEmacs
+exist. As usual, the \href{help:/kdvi/forward-search.html}{Handbook of
+\KDVI} explains how to set up your editor with thest scripts.
+
+
+\subsection{Inverse search}
+
+\background{White}
+Inverse search means that you can click into the document in \KDVI,
+and your editor will open, load the source file and jump to the proper
+place. \KDVI\ currently supports the editors Emacs, Kate, NEdit, VI
+and XEmacs. Users who prefer a different editor can specify shell
+commands which are to be used. Again we refer to the
+\href{help:/kdvi/inverse-search.html}{Handbook of \KDVI} for a detailed explanation.
+
+\paragraph*{Example}
+If you are viewing this document in \KDVI, you can click anywhere with
+the middle mouse button (if your mouse has only two buttons, click
+left and right simultaneously). An editor will pop up, load the
+\LaTeX\ sourcefile and jump to the appropriate line in the
+text. Source specials has been added using the {\tt srcltx} macro
+package in \LaTeX\ by including the line
+\begin{verbatim}
+\usepackage[active]{srcltx}
+\end{verbatim}
+into the document preamble. Everything else is automatic.
+
+
+\begin{thebibliography}{CM97}
+
+\bibitem[Bha99]{HFAQ99}
+T.~Bhattacharya et al.
+\newblock {\em Hyper\TeX\ FAQ}
+\newblock available on the internet site of the preprint server of the
+ Los Alamos National Labatories at 
+\href{http://arXiv.org/hypertex}{\small \tt http://arXiv.org/hypertex}
+
+\bibitem[Rah98]{Rah98}
+S.~Rahts
+\newblock {\em Hypertext marks in \LaTeX: the {\sf hyperref} package}
+\newblock included in the tetex distribution. A copy can be found on KDVI's 
+home page at \hfill \linebreak
+\href{http://devel-home.kde.org/~kdvi/DVI/hyperref-manual.pdf}{\small \tt http://devel-home.kde.org/$\sim$kdvi/DVI/hyperref-manual.pdf}
+
+\bibitem[Rok00]{dvips}
+T.~Rokicki
+\newblock {\em DVIPS: A \TeX\ Driver}
+\newblock included in the tetex distribution. A copy can be found on KDVI's 
+home page at \hfill \linebreak
+\href{http://devel-home.kde.org/~kdvi/DVI/dvips.dvi}{\small \tt http://devel-home.kde.org/$\sim$kdvi/DVI/dvips.dvi}
+
+\bibitem[TUG0]{Level0Std}
+The TUG DVI Driver Standards Committee
+\newblock {\em The DVI Driver Standard, Level 0}
+\newblock included in the tetex distribution. A copy can be found on KDVI's 
+home page at \hfill \linebreak
+\href{http://devel-home.kde.org/~kdvi/DVI/dvistd0.dvi}{\small \tt http://devel-home.kde.org/$\sim$kdvi/DVI/dvistd0.dvi}
+
+
+\end{thebibliography}
+\end{document}