tdegraphics/doc/kdvi/KDVI-features.tex

\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}