\documentclass[11pt]{article}
\usepackage{amstext}
\usepackage{graphicx}
\usepackage{times}
\usepackage[arrow,matrix,curve,ps]{xy}
\xyoption{dvips}
\usepackage{hyperref}
\newcommand{\KDVI}{{\sf KDVI 0.9d}}
\begin{document}
\title{Support for \TeX\ extensions in \KDVI}
\author{Stefan Kebekus}
%\address{Stefan Kebekus, Institut für Mathematik, Universität
%Bayreuth, 95440 Bayreuth, Germany}
%\curraddr{Research Institute for Mathematical Studies, Kyoto
%University, Oiwake-cho, Kitashirakawa, Sakyo-ku, Kyoto 606-8502,
%Japan}
%\email{kebekus@kde.org}
%\urladdr{http://btm8x5.mat.uni-bayreuth.de/\~{}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} programm.
\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 labelling 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{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}
\begin{thebibliography}{CM97}
\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}{\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/dvips.dvi}{\tt http://devel-home.kde.org/$\sim$kdvi/DVI/dvips.dvi}
\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}{\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}{\tt http://devel-home.kde.org/$\sim$kdvi/DVI/hyperref-manual.pdf}
\end{thebibliography}
\end{document}
