Stefan Kebekus
Copyright © 2001 Stefan Kebekus
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
This document describes kdvi version 1.0
Table of Contents
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 (or see KDVI-features.tex 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. If you are connected to the internet, you can access files which reside on other computers by giving a URL as a parameter, like this: kdvi http://somepath/paper.dvi
If you give a URL as a parameter, you can tell kdvi to jump directly to certain place of the DVI file. For example, kdvi file:paper.dvi#43 will make kdvi to open page 43. If you have included source file information, a command like kdvi file:paper.dvi#src:43paper.tex will make kdvi search for the place in the DVI file which corresponds to line 43 in the TeX file paper.tex. You will hardly use this option yourself — read the section on forward search to learn how to set up your editor to start kdvi automatically.
Warning
The command kdvi file:paper.dvi#43 will open page 43 of the file paper.dvi. The command kdvi paper.dvi#43 will try to open the file paper.dvi#43.
There is another option which you will most likely not need to specify yourself. If you type kdvi --unique somepath/paper.dvi, kdvi will load the file if there is no other instance running which has the file already loaded. If there is, this instance of kdvi will pop to the front. A command like kdvi --unique file:paper.dvi#43 can be used in shell scripts to make a running instance of kdvi to jump to page 43.
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.
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 expert, 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.
Warning
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.
Using inverse search
Inverse search is a very useful feature when you are writing a TeX-document yourself. If everything is properly set up, you can click into kdvi's window with the middle mouse button (on some systems, when you don't have a three-button mouse, you can simultaneously use the left and the right button). After that, your favourite editor will open, load the TeX-sourcefile and jump to the proper paragraph. To use inverse search, do the following:
Procedure 5.1.
Produce a DVI file that contains inverse search information. This is explained in the section Producing TeX-files for inverse search below. If you just want to test the inverse search feature, you can also use the example file KDVI-features.dvi
Let kdvi know which editor you would like to use. Choose an editor in the Preferences dialog (this dialog can be reached by choosing Settings in the menu DVI options). The next chapter of this documentation, The preferences dialog/Rendering Options, explains this dialog in more detail.
Some editors need to be started manually, or need additional configuration. You will find a description of all supported editors in the, Setting up your editor below.
Test your setup. Open your DVI file in kdvi and use the middle mouse button to click into kdvi. The editor should pop up and display the TeX file.
There are essentially two ways to produce DVI files which contain inverse search information: you can either use a TeX/LaTeX-binary which generates and includes the necessary information automatically, or you can include an extra package which is written in TeX/LaTeX.
A TeX binary which generates and includes the necessary information automatically, is certainly the preferred method of including inverse search information. By the time of writing, a binary was not yet available for Unix. However, it is said that the next version of the TeTeX TeX-distribution will support inverse search natively.
If you do not have a TeX-binary which includes inverse search information natively, copy the files srcltx.sty and srctex.sty to the directory where your TeX-file resides (you can do that by Shift+Left the hyperlinks). If you use LaTeX, add the line
\usepackage[active]{srcltx}to the preamble of your TeX-file. If you use plain TeX, the line\include{srctex}will do the trick.
Tip
While inverse search is extremely useful when you are typing a document yourself, it might be a good idea to remove the inverse search information before sending the DVI file to someone else.
Setting up your editor
While inverse search works generally very well with most editors, some of them require a bit of extra care. This section explains how to configure your editor.
Emacs works well with kdvi. The actual behaviour of Emacs depends largely on the configuration. As usual, you can customize Emacs completely, if you are willing to fight your way through Lisp code.
kdvi uses the program emacsclient to remote control Emacs.
Important
The program emacsclient requires that Emacs is running, and that the program emacs-server is started inside Emacs. Inverse search will not work optimally unless you have started both Emacs and the emacs-server.
To start the emacs-server, you can do one of the following:
Procedure 5.2.
In Emacs, start the emacs-server by typing M x server-start
Add the line
(server-start)to your or .emacs file. Restart Emacs
Tip
Make sure that Emacs is installed. Try to start emacs from the command line.
kdvi uses the command emacsclient to remote control Emacs. Make sure that emacsclient is available on the command line by trying the command emacsclient Name of a text file. This should open a new text in the Emacs editor.
If emacsclient fails with an error message like unable to connect to local, make sure that Emacs is running. Furthermore, make sure that the emacs-server is started by typing M x server-start.
If you want the frame to be auto-raised, add the raise-frame function to “server-switch-hook” (do M x customize-variable RET server-switch-hook and enter the function name into the text field.
If you have changed the buffer since your last save, Emacs will ask you: Revert buffer from file ...? (yes or no). You will probably always want to say no here, since reverting means that the file is reread from disk, causing all your changes since the last save to be lost!
IMHO gnuclient's behaviour of silently reloading the changed buffer is preferable — add the following lines to your .emacs file to emulate gnuclient's behaviour with emacsclient:
(defadvice server-visit-files (around save-buffers last activate) "Try to emulate gnuclient behaviour with emacsclient. Works only for visiting one buffer at a time." (let* ((filen (car (car (ad-get-arg 0)))) (buf (get-file-buffer filen)) (this-buf-modified-p nil)) ;;; the following is copied from server-visit-files, with ;;; a modification for the `verify-visited-file-modtime' test (if (and buf (set-buffer buf)) (if (file-exists-p filen) ;;; if the file has changed on disk, reload it ;;; using `find-file-noselect' (if (not (verify-visited-file-modtime buf)) (progn (find-file-noselect filen) ;;; if user answered `no', reset modtime anyway ;;; so that server-visit-files doesn't realize the ;;; difference: (set-visited-file-modtime))) ;;; if file exists no longer, we let server-visit-files ;;; deal with that t) (setq buf (find-file-noselect filen))) (setq this-buf-modified-p (buffer-modified-p buf)) (set-buffer buf) (set-buffer-modified-p nil) ad-do-it (set-buffer-modified-p this-buf-modified-p)))
Unfortunately, KDE's editor Kate does not support the inverse search very well. A middle-button mouseclick into the DVI file will always open a new instance of the Kate editor, even if Kate is already running and even if the TeX-file is already loaded. Worse, Kate does not move the cursor to the beginning of the paragraph.
NEdit generally works very well indeed. Clicking into the DVI file should open a new window. If the TeX-file is already used in another window of NEdit, the newly opened window displays another view of the buffer. Otherwise, the TeX-file is loaded. After opening the window, NEdit highlights the first line of the appropriate paragraph.
Tip
Procedure 5.3.
Make sure that NEdit is installed. Try to start nedit from the command line.
kdvi uses the command ncl to remote control NEdit. Make sure that ncl is available on the command line by trying the command ncl -noask. This which should open an instance of the NEdit editor. If ncl is not available, you might be using an older version of NEdit. In that case, you should either upgrade to a more recent version, or you have to use the option User defined editor from the Options dialog.
XEmacs works well with kdvi. The actual behaviour of XEmacs depends largely on the configuration. As usual, you can customize XEmacs completely, if you are willing to fight your way through Lisp code.
kdvi uses the program gnuclient to remote control XEmacs.
Important
The program gnuclient requires that XEmacs is running, and that the program gnuserv is started inside XEmacs. Inverse search will not work unless you have started both XEmacs and gnuserv.
To start the gnuserv program, you can do one of the following:
In XEmacs, start gnuserv by typing M x gnuserv-start
Add the line
(gnuserv-start)to your or .xemacs file. If you use a more recent version of XEmacs, .xemacs will be a directory. In that case, you should append the line to the file .xemacs/init.el. Restart XEmacs
If you don't want to open a new frame for each editor call, and want the frame to be auto-raised, set ‘Gnuserv Frame’ to ‘Use selected frame’, and add the raise-frame function to ‘Visit Hook’. Do M x customize-group RET gnuserv to make these settings.
Tip
Make sure that XEmacs is installed. Try to start xemacs from the command line.
kdvi uses the command gnuserv to remote control XEmacs. Make sure that gnuclient is available on the command line by trying the command gnuclient Name of a text file. This should open a new frame in the XEmacs editor.
If gnuserv fails with an error message like unable to connect to local, make sure that XEmacs is running. Furthermore, make sure that gnuserv is started by typing M x gnuserv-start.
If you don't want to open a new frame for each editor call, and want the frame to be auto-raised, set “Gnuserv Frame” to “Use selected frame”, and add the “raise-frame” function to “Visit Hook”. Do M x customize-group RET gnuserv to make these settings.
kdvi supports vim, but the result is not thrilling. A middle button mouseclick into the DVI file will always open a new instance of the vim editor, even if vim is already running and even if the TeX-file is already loaded.
Tip
Make sure that VIM/GUI is installed. Try to start gvim from the command line.
Forward search
The forward search functions allow you to jump from your editor directly into the associated position of the DVI file. Since forward search must be supported by your editor, only Emacs and XEmacs are currently supported. Other editors will hopefully join in soon.
To use forward search, you have to do the following:
Set up your editor — this is described below.
Add source file information to your DVI file, e.g. by using the package srcltx. This has been described in the section "Producing TeX-files for inverse search".
Go! If you use Emacs and everything is properly set up, you just press Ctrl+x Ctrl+j, and kdvi pops up and jumps to the place which corresponds to the place of the TeX file which you are currently editing.
In order to use forward search in Emacs, follow these steps:
Download the following Emacs script, kdvi-search.el (press shift and click the filename to download) and store it in a place where Emacs can access it — we recommend a directory emacs-scripts.
Add the lines
(add-to-list 'load-path (expand-file-name "~/emacs-scripts/")) (require 'kdvi-search) (add-hook 'LaTeX-mode-hook (lambda () (local-set-key "\C-x\C-j" 'kdvi-jump-to-line))) (add-hook 'tex-mode-hook (lambda () (local-set-key "\C-x\C-j" 'kdvi-jump-to-line)))
to your .emacs file. Restart Emacs.Enjoy. Open Emacs, load a TeX-file, produce the corresponding DVI file, and either enter the command M+xkdvi-jump-to-line or press Ctrl-x Ctrl-j. It may happen that Emacs asks you for the name of a ‘master file’. This is useful if you use a TeX file which includes other files: the master file is the top-level file which includes the others. Emacs will perhaps also ask to save the name of the master-file ‘as a local variable’, i.e. as a comment at the very end of the file. Say either yes or no, and enjoy!
Tip
Make sure that Emacs is installed. Try to start emacs from the command line.
If Emacs fails to start kdvi, you can find its output in the Buffer kdvi-output.
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.
The following picture shows the options dialog of kdvi.
- 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.
- 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.
Note
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.
- Show 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.
- Editor for inverse search
If you intend to use inverse search, a very useful feature if you write TeX documents yourself, you have to specify which editor you are going to use, and how this editor can be started by kdvi. In the example shown, the user has opted for the NEdit editor. If you use one of the pre-configured editors from the Editor combobox, then you don't have to do anything else. If you whish to use a different editor, chose User defined Editor from the Editor combobox and enter the command line which will be used to start your editor. Use the placeholders %f and %l which will be replaced with the name of the TeX file, and the line of the TeX file, respectively.
If you use an editor which is not supported, please send us an email at <kebekus@kde.org> and tell us about the command line you use and how you have configured your editor.
Frequently asked questions
- 8.1. What happens when kdvi displays the message KDVI is currently generating bitmap fonts, and why does the procedure take so long?
- 8.2. What is a MetaFont Mode?
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>
This program is licensed under the terms of the GNU General Public License.
This documentation is licensed under the terms of the GNU Free Documentation License.