Support for TEX extensions in KDVI 0.9d

Stefan Kebekus

March 12, 2001

Abstract

This document describes the extensions to the standard format of DVI files which KDVI 0.9d implements in order to support PostScript inclusion and hyperlinks.

KDVI 0.9d 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 0.9d, then you can find examples here.

Contents

1 What’s all this 1

2 Virtual fonts 2

3 PostScript support 2 3.1 Literal PostScript . . . . . . . . . . . . . . . . . . . . . . . . . . 2 3.2 Direct PostScript . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.3 Literal headers . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.4 PostScript headers . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.5 EPS inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

4 Hypertext support 6 4.1 Hyper-Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2 Hyper-References . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1 What’s all this

The DVI-previewing program KDVI 0.9d is able to display standard DVI-files as specified in [TUG0]. In order to support graphics inclusion, hyperlinks and nonstandard fonts, KDVI 0.9d implements a number of features which extend [TUG0]. In particular, KDVI 0.9d supports a number of TEX’s \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 \special commands, there is now a wealth of competing and mutually incompatible definitions.

KDVI 0.9d 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 dvips programm. KDVI 0.9d does not support a number of outdated and unsane standards, nor does it support features which impair the system security.

2 Virtual fonts

KDVI 0.9d supports “virtual fonts”. This enables TEX to use PostScript fonts. For more information, and a complete specification, consult [Rok00].

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 L^{A}TEX2ϵ by including the line

\usepackage{times}

in the header of this document.

3 PostScript support

KDVI 0.9d 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.

3.1 Literal PostScript

KDVI 0.9d supports the inclusion of PostScript into DVI-files by means of the quote-special. The syntax follows the specification of [Rok00]:

\special{" PostScript-commands}

The PostScript-commands are not directly included, in fact they are sandwiched between a save and restore pair. That way KDVI 0.9d ensures that the command cannot affect PostScript-commands which appear somewhere else in your file.

Figure 1: Graphic generated by literal PostScript inclusion

Example Figure 1 shows an example taken from [Rok00]. The generating TEXcode is

\vbox to 100bp{\vss
\special{" newpath 0 0 moveto 100 100 lineto
 300 0 lineto closepath gsave 0.8 setgray fill
 grestore stroke}}

3.2 Direct PostScript

KDVI 0.9d supports the inclusion of PostScript into DVI-files by means of the direct-special. The syntax follows the specification of [Rok00]:

\special{ps: Postscript-commands}

The PostScript-commands are directly included, and there is no protective save and 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 0.9d also supports the following syntactical variants which are explained in [Rok00]:

\special{ps: Postscript-commands}
\special{ps::[begin] Postscript-commands}
\special{ps:: Postscript-commands}
\special{ps::[end] Postscript-commands}

The variant

\special{ps: plotfile filename}

is not currently supported.

Example The command

\includegraphics[height=3cm, angle=20]{aboutkde.ps}

which is used in section 3.5 uses the direct-special internally in order to set the rotation.

3.3 Literal headers

Literal headers work as described in [Rok00].

\special{! PostScript-Header-commands}

Example The following diagram, which was generated using the XY-pic macro packages uses literal postscript inclusion which relies on literal headers.

X̃  _{∃α}  ^{η}_{normalization}_{π̃}  X_{π} X′  _{∃β}_{∃π′}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.

3.4 PostScript headers

PostScript headers work as described in [Rok00]. This command is very similar to the literal header command, but expects the name of a file which should be included.

\special{header=filename}

3.5 EPS inclusion

A popular way to include PostScript-files into TEX documents uses the PSFile \special command. Again this is explained in detail in [Rok00]. Currently KDVI 0.9d supports the syntax

\special{psfile=File keyword=value keyword=value ...}

Figure 2: Embedded PostScript graphic

Where keyword is one of the following llx lower left corner of the bounding box, x-coordinate lly lower left corner of the bounding box, y-coordinate urx upper right corner of the bounding box, x-coordinate ury upper right corner of the bounding box, y-coordinate rwi width of the bounding box. If llx−urx ≠ rwi, then the boundig box is scaled

accordingly. rhi height of the bounding box If lly − ury ≠ rhi, then the boundig box is scaled

accordingly. angle rotates the picture counterclockwise Unknown keywords are silently ignored. The keywords llx, lly, urx, ury and rwi are usually generated by the epsf macros. The keywords hoffset,

voffset, hsize, vsize, hscale, vscale, angle and clip are not cur-

rently implemented. The “uncompression” feature of dvips and xdvi which allows to execute arbitrary commands in via the syntactical variant

\special{psfile="'shell-command" keyword=value ...}

is deliberately not implemented for security reasons.

Figure 3: Reference to a non-existent PS-file

Example Figure 2 shows an embedded postscript-file. This was easily realized by including the line

\usepackage{graphicx}

into the header of this document, and the lines

\includegraphics[height=3cm]{aboutkde.ps}
\includegraphics[height=4cm]{aboutkde.ps}
\includegraphics[height=3cm, angle=20]{aboutkde.ps}

at the place where the graphic should appear. It is strongly recommended to use the graphicx macro package for this purpose. Figure 3 shows how KDVI 0.9d warns you about non-existent files.

4 Hypertext support

KDVI 0.9d 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 [Bha99] or [Rah98]. Note, however, that KDVI 0.9d does currently not allow nested hyperlinks.

4.1 Hyper-Labels

The commands

\special{html:<a name="namestring">}
\special{html:</a>}

labels the current point of the text for later reference.

4.2 Hyper-References

The commands

\special{html:<a href="hrefstring">}
Text
\special{html:</a>}

makes Text a link to hrefstring, where hrefstring is an absolute or relative URL in the standard format used on the internel. If hrefstring is of the form #label then it points to the section of the current document which is labeled using the labelling command described above:

\special{html:<a name="namestring">}

Example This document features a clickable table of contents, and also the references can be clicked on. This has been achieved by using the hyperref macro package in L^{A}TEX by including the line

\usepackage{hyperref}

into the document preamble. Everything else is automatic.

Here is an external link which points to the main website of the KDE project. For this, the command href of the hyperref macro package was used:

\href{http://www.kde.org}{main
  website of the KDE project}

References

[Rok00] T. Rokicki  DVIPS: A TEX Driver  included in the tetex

distribution. A copy can be found on KDVI’s home page at

       http://devel-home.kde.org/∼kdvi/DVI/dvips.dvi

[TUG0] The TUG DVI Driver Standards Committee The DVI Driver Standard, Level 0 included in the tetex distribution. A copy can be found on KDVI’s home page at

       http://devel-home.kde.org/∼kdvi/DVI/dvips.dvi

[Bha99] T. Bhattacharya et al. HyperTEX FAQ available on the internet site of the preprint server of the Los Alamos National Labatories at

       http://arXiv.org/hypertex

[Rah98] S. Rahts Hypertext marks in L^{A}TEX: the hyperref package included in the tetex distribution. A copy can be found on KDVI’s home page at

http://devel-home.kde.org/∼kdvi/DVI/hyperref-manual.pdf