You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
481 lines
16 KiB
481 lines
16 KiB
\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}
|