# The &kdvi; Handbook

Stefan
Kebekus

    	   kebekus@kde.org

2001
Stefan Kebekus
&FDLNotice;
2001-01-09
1.0

This document describes &kdvi; version 0.9h

KDE
linux
TeX
DVI

## Introduction

&kdvi; is a plugin for the &kviewshell; program which allows &kviewshell; to display &DVI;-files (`.dvi`) which are produced by the TeX typesetting system. &kdvi; supports many extensions of the DVI standard, for instance the inclusion of &PostScript; graphics or hyperlinks. More details, examples and all the technical specifications can be found in the file `KDVI-features.dvi` (click here for the TeX-source of that file).

For up-to-date information, consult kdvi's home page.

TeX is a high-end typesetting system geared towards scientific, and in particular mathematical typesetting. More information about TeX and &DVI; can be found on the homepage of the TeX user group or the German German DANTE e.V..

## Starting &kdvi;

Most of the time, &kdvi; will be started by just clicking onto a `.dvi`-file in the file manager. For convenience there exists a command `kdvi` which calls &kviewshell; with the &kdvi; plugin preloaded. The viewer may thus be started using the command ``kdvi` `somepath/paper.dvi``. The command lines ``kdvi` `somepath/paper`` or ``kdvi` `somepath/paper.`` will also work.

The usual parameters handled by &Qt; and &kde; applications also work: ``kdvi` `-style` `windows` `-display` `:0` `-geometry` `400x400+0+0` `-caption` `"DVI"``

## Printing DVI-Files

&kdvi; can print your DVI-files using the standard KDE printing interface. Internally, &kdvi; uses the programm `dvips` to generate PostScript, which is then passed on to the printer. In particular, `dvips` must be installed if you want to print with &kdvi;. The programm `dvips` uses its own configuration files and its own settings, which are fine for most purposes. However, if you care for optimal printing results, you should configure `dvips` manually and make sure to set a default MetaFont mode which fits your printer best ---on many systems you'll find a GNU-texinfo documentation of `dvips`, and you might also want to look for a file called `dvips.dvi` or similar.

## Exporting the DVI file to other formats

If you want to save your file as in PostScript or PDF-format, it is not recommended that you use the printing function and redirect the printer output to a file. Instead, you can use the export functions which produce better-quality output that retains many of the special features of the dvi format and looks better in many of the viewing applications, such as Adobe's Acrobat Reader. You will find the export functions in the File menu.

### Exporting to PostScript

As in printing, the external program `dvips` is used to generate the PostScript file. If the DVI-file contains hyperlinks, these will also be included in the PostScript file. If you are an export, and if you would like to generate output which is optimized for a specific printer, you should probably start `dvips` manually and choose the proper MetaFont mode yourself.

### Exporting to PDF

In order to produce PDF files of high quality, &kdvi; converts DVI to PDF using the external program `dvipdfm`. If you are working on a machine where an older distribution of the TeX typesetting system is installed, it may be that the programm `dvipdfm` is not installed. In that case, you need to use the printing function to generate PDF output.

If you are viewing the generated file in Adobe's Acrobat reader, you may well find that some of the fonts look extremely poor although a printout is fine, and although the document looks ok in ghostview. This is a known issue with the Acrobat Reader and bitmap fonts. At the time of writing, the only practicable workaround seems to be to avoid bitmap fonts.

## The Preferences dialog

The Preferences dialog can be reached by choosing Settings DVI options in the Settings menu.

The dialog consists of two tabs, Fonts and Rendering.

### Fonts Options

The following picture shows the options dialog of &kdvi;.

The Fonts dialog
The Fonts dialog

Metafont mode

  These options specify the fonts which &kdvi; will use for rendering. By carefully optimizing the settings here it is possible to improve on the display. However, unless you are an expert in `MetaFont` and know what you are doing, it is not a good idea to change these options. You may want to look at the Frequently asked questions section of this manual.

  Safe values are 1200 dpi / Lexmark for good quality, or 600 dpi / LaserJet 4 for medium quality and faster display.

Generate missing fonts

  Check this if you want &kdvi; to call the `MetaFont` program in the likely case that kdvi wants to display documents which use fonts which are not yet readily made. You most certainly want to set this option.

### Rendering Options

The following picture shows the second options dialog of &kdvi;.

The Rendering dialog
The Rendering dialog

Show PostScript specials

  If this options is checked, &kdvi; will display &PostScript; graphics which are embedded into the &DVI; file. You probably want to set this option.

  If an external &PostScript; file could not be found, &kdvi; will draw a red warning box in its place. Unfortunately, rendering &PostScript; graphics is very slow in the current version of &kdvi;. We will improve on the speed in later versions. If this option is off, &kdvi; will either draw a grey box as a placeholder for the graphics, or it will leave the space blank.

  There is no standard way to embed &PostScript; graphics into a dvi file. It may therefore happen that &kdvi; cannot properly display a graphic which works fine with other programs. Older versions of `xdvi` and `dvips` support the execution of external commands. This is a bad security risk and therefore deliberately not implemented in &kdvi;. Technical information about supported ways to include &PostScript; can be found in the document `KDVI-features.dvi`.

Hyperlinks

  Check this if you want &kdvi; to display hyperlinks. The appropriate parts of the text will be underlined in blue. You probably want to set this option.

## Frequently asked questions

What happens when &kdvi; displays the message "Generating bitmap fonts", and why does the procedure take so long?

Many of the fonts which are typically used in a TeX document must be generated by the MetaFont system. Metafont is a language similar to TeX (included in most TeX distributions) which takes a description of the font outline, and produces a rasterized version (= `.pk`-file) of the font which can then be send to a printer or be used in a previewing program like &kdvi;. Metafont goes out of its way to produce the best possible output for your printer. For instance, it knows that a pixel of an inkjet printer is a roundisch blot, and that nearby pixels tend to smear into each other. In contrast, a pixel on a laser printer is rectangular, but an isolated pixel is very often not rendered at all.

Generating such highly optimized bitmap fonts is naturally rather time-consuming, in particular since typical TeX documents use a large number of different fonts. We can only ask for your patience. To ease the matter somewhat, most distributions of TeX store the `.pk`-files for a limited time, e.g. 100 days. Therefore, if you access the same document more than once, the `.pk` files will be reused.

What is a MetaFont Mode?

In order to produce bitmap fonts which are optimized for your printer (see the answer to the first question), Metafont comes with a database of printing engines --look for a file called `modes.mf`. A Metafont Mode is just the name of a database entry. For example, the name "ljfour" refers to the entry in the database that describes a Hewlett Packard LaserJet 4 printer. A MetaFont Mode is usually followed by a number, the resolution. The LaserJet, for instance canprint in both 300 and 600 dots per inch. Thus, "ljfour/600" would be a full description.

## Credits and Licenses

&kdvi;

&kdvi; is based on based on the stand-alone-program &kdvi; 0.4.3 by Markku Hihnala. That program is in turn based on xdvi version 18f which has many authors.

Documentation is copyright 2001, Stefan Kebekus kebekus@kde.org

&underGPL; &underFDL;

&documentation.index;