<?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ <!ENTITY kappname "&kdvi;"> <!ENTITY package "kdegraphics"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"><!-- change language only here --> ]> <book lang="&language;"> <bookinfo> <title>The &kdvi; Handbook</title> <authorgroup> <author> <firstname>Stefan</firstname> <surname>Kebekus</surname> <affiliation> <address> <email>kebekus@kde.org</email> </address> </affiliation> </author> <!-- TRANS:ROLES_OF_TRANSLATORS --> </authorgroup> <copyright> <year>2001</year> <holder>Stefan Kebekus</holder> </copyright> <legalnotice>&FDLNotice;</legalnotice> <date>2002-04-27</date> <releaseinfo>1.00.00</releaseinfo> <abstract> <para>This document describes &kdvi; version 1.0</para> </abstract> <keywordset> <keyword>KDE</keyword> <keyword>linux</keyword> <keyword>TeX</keyword> <keyword>DVI</keyword> </keywordset> </bookinfo> <chapter id="introduction"> <title>Introduction</title> <para>&kdvi; is a plugin for the &kviewshell; program which allows &kviewshell; to display &DVI;-files (<literal role="extension">.dvi</literal>) 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 <filename>KDVI-features.dvi</filename> (or see <filename>KDVI-features.tex</filename> for the TeX source of that file).</para> <para>For up-to-date information, consult <ulink url="http://devel-home.kde.org/~kdvi">&kdvi;'s home page</ulink>. </para> <para>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 <ulink url="http://www.tug.org">homepage of the TeX user group</ulink> or the German <ulink url="http://www.dante.de">German DANTE e.V.</ulink>. </para> </chapter> <chapter id="starting"> <title>Starting &kdvi;</title> <para>Most of the time, &kdvi; will be started by just clicking onto a <literal role="extension">.dvi</literal> file in the file manager. For convenience there exists a command <command>kdvi</command> which calls &kviewshell; with the &kdvi; plugin preloaded. The viewer may thus be started using the command <userinput><command>kdvi</command> <parameter>somepath/paper.dvi</parameter></userinput>. The command lines <userinput><command>kdvi</command> <parameter>somepath/paper</parameter></userinput> or <userinput><command>kdvi</command> <parameter>somepath/paper.</parameter></userinput> 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: <userinput><command>kdvi</command> <parameter>http://somepath/paper.dvi</parameter></userinput> </para> <para>If you give a &URL; as a parameter, you can tell &kdvi; to jump directly to certain place of the &DVI; file. For example, <userinput><command>kdvi</command> <parameter>file:paper.dvi#43</parameter></userinput> will make &kdvi; to open page 43. If you have included source file information, a command like <userinput><command>kdvi</command> <parameter>file:paper.dvi#src:43paper.tex</parameter></userinput> will make &kdvi; search for the place in the &DVI; file which corresponds to line 43 in the TeX file <parameter>paper.tex</parameter>. You will hardly use this option yourself — read the section on <link linkend="forward-search">forward search</link> to learn how to set up your editor to start &kdvi; automatically. </para> <warning><para>Don't forget the <userinput>file:</userinput> prefix or it will give unexpected results. For example, the command <userinput><command>kdvi</command> <parameter>file:paper.dvi#43</parameter></userinput> will open page 43 of the file <filename>paper.dvi</filename>. The command <userinput><command>kdvi</command> <parameter>paper.dvi#43</parameter></userinput> will try to open the file <filename>paper.dvi#43</filename>.</para> </warning> <para>There is another option which you will most likely not need to specify yourself. If you type <userinput><command>kdvi</command> <parameter>--unique</parameter> <parameter>somepath/paper.dvi</parameter></userinput>, &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 <userinput><command>kdvi</command> <parameter>--unique</parameter> <parameter>file:paper.dvi#43</parameter></userinput> can be used in shell scripts to make a running instance of &kdvi; to jump to page 43.</para> <para>The usual parameters handled by &Qt; and &kde; applications also work: <userinput><command>kdvi</command> <option>-style</option> <parameter>windows</parameter> <option>-display</option> <parameter>:0</parameter> <option>-geometry</option> <parameter>400x400+0+0</parameter> <option>-caption</option> <parameter>"DVI"</parameter></userinput> </para> </chapter> <chapter id="print"> <title>Printing &DVI; Files</title> <para>&kdvi; can print your &DVI; files using the standard &kde; printing interface. Internally, &kdvi; uses the programm <command>dvips</command> to generate &PostScript;, which is then passed on to the printer. In particular, <command>dvips</command> must be installed if you want to print with &kdvi;. The programm <command>dvips</command> 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 <command>dvips</command> manually and make sure to set a default MetaFont mode which fits your printer best — on many systems you'll find a <ulink url="info:/dvips">GNU-texinfo documentation of <command>dvips</command></ulink>, and you might also want to look for a file called <filename>dvips.dvi</filename> or similar.</para> </chapter> <chapter id="export"> <title>Exporting the &DVI; file to other formats</title> <para>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 <application>Acrobat Reader</application>. You will find the export functions in the <guimenu>File</guimenu> menu.</para> <section id="export-ps"> <title>Exporting to &PostScript;</title> <para>As in printing, the external program <command>dvips</command> 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 <command>dvips</command> manually and choose the proper MetaFont mode yourself.</para> </section> <section id="export-pdf"> <title>Exporting to <acronym>PDF</acronym></title> <para>In order to produce <acronym>PDF</acronym> files of high quality, &kdvi; converts &DVI; to <acronym>PDF</acronym> using the external program <command>dvipdfm</command>. If you are working on a machine where an older distribution of the TeX typesetting system is installed, it may be that the programm <command>dvipdfm</command> is not installed. In that case, you need to use the printing function to generate <acronym>PDF</acronym> output.</para> <warning> <para>If you are viewing the generated file in Adobe's <application>Acrobat reader</application>, you may well find that some of the fonts look extremely poor although a printout is fine, and although the document looks ok in <application>ghostview</application>. This is a known issue with the <application>Acrobat Reader</application> and bitmap fonts. At the time of writing, the only practicable workaround seems to be to avoid bitmap fonts.</para> </warning> </section> </chapter> <chapter id="inverse-search"> <title>Using inverse search</title> <anchor id="inv-search"></anchor> <para>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 <mousebutton>middle</mousebutton> mouse button (on some systems, when you don't have a three-button mouse, you can simultaneously use the <mousebutton>left</mousebutton> and the <mousebutton>right</mousebutton> button). After that, your favourite editor will open, load the TeX source file and jump to the proper paragraph. To use inverse search, do the following:</para> <procedure> <step> <para>Produce a &DVI; file that contains inverse search information. This is explained in the section <link linkend="inverse-search-tex">Producing TeX files for inverse search</link> below. If you just want to test the inverse search feature, you can also use the example file <filename>KDVI-features.dvi</filename></para> </step> <step> <para>Let &kdvi; know which editor you would like to use. Choose an editor in the <guilabel>Preferences</guilabel> dialog (this dialog can be reached by choosing <guimenuitem>DVI Options</guimenuitem> in the <guimenu>Settings</guimenu> menu). The next section of this documentation, <link linkend="opt-rendering">Rendering Options</link>, explains this dialog in more detail.</para> </step> <step> <para>Some editors need to be started manually, or need additional configuration. You will find a description of all supported editors in the section <link linkend="inverse-search-editor">Setting up your editor</link> below.</para> </step> <step> <para>Test your setup. Open your &DVI; file in &kdvi; and use the <mousebutton>middle</mousebutton> mouse button to click into &kdvi;. The editor should pop up and display the TeX file.</para> </step> </procedure> <section id="inverse-search-tex"> <title>Producing TeX files for inverse search</title> <para>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.</para> <itemizedlist> <listitem> <para>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 <ulink url="http://www.tetex.org">TeTeX TeX distribution</ulink> will support inverse search natively. </para> </listitem> <listitem> <para>If you do not have a TeX binary which includes inverse search information natively, copy the files <ulink url="srcltx.sty"> <filename>srcltx.sty</filename> </ulink> and <ulink url="srctex.sty"> <filename>srctex.sty</filename> </ulink> to the directory where your TeX file resides (you can do that by pressing the &Shift; key and &LMB; while the mouse pointer is on a hyperlink.) If you use LaTeX, add the line <programlisting> \usepackage[active]{srcltx} </programlisting> to the preamble of your LaTeX file. If you use plain TeX, the line <programlisting> \include{srctex} </programlisting> will do the trick.</para> </listitem> </itemizedlist> <tip> <para>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.</para> </tip> </section> <section id="inverse-search-editor"> <title>Setting up your editor</title> <para>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.</para> <section id="editor-setup-emacs"> <title><application>Emacs</application></title> <para><application>Emacs</application> works well with &kdvi;. The actual behaviour of <application>Emacs</application> depends largely on the configuration. As usual, you can customize <application>Emacs</application> completely, if you are willing to fight your way through Lisp code.</para> <para>&kdvi; uses the program <command>emacsclient</command> to remote control <application>Emacs</application>.</para> <important> <para>The program <command>emacsclient</command> requires that <application>Emacs</application> is running, and that the program <application>Emacs Server</application> is started inside <application>Emacs</application>. Inverse search will not work optimally unless you have started both <application>Emacs</application> and the <application>Emacs Server</application>.</para> </important> <para>To start the <application>Emacs Server</application>, you can do one of the following:</para> <procedure> <step> <para>In <application>Emacs</application>, start the <application>Emacs Server</application> by typing <userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo> <command>server-start</command></userinput></para> </step> <step> <para>Add the line <programlisting> (server-start) </programlisting> to your <filename>.emacs</filename> file. Restart <application>Emacs</application></para> </step> </procedure> <tip> <itemizedlist> <listitem> <para>Make sure that <application>Emacs</application> is installed. Try to start <command>emacs</command> from the command line.</para> </listitem> <listitem> <para>&kdvi; uses the command <command>emacsclient</command> to remote control <application>Emacs</application>. Make sure that <command>emacsclient</command> is available on the command line by trying the command <userinput><command>emacsclient</command> <parameter>Name of a text file</parameter></userinput>. This should open a new text in the <application>Emacs</application> editor.</para> </listitem> <listitem> <para>If <command>emacsclient</command> fails with an error message like <computeroutput>unable to connect to local</computeroutput>, make sure that <application>Emacs</application> is running. Furthermore, make sure that the <application>Emacs Server</application> is started by typing <userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo> <command>server-start</command></userinput>.</para> </listitem> <listitem> <para>If you want the frame to be auto-raised, add the <function>raise-frame</function> function to <quote>server-switch-hook</quote> (do <userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo> <command>customize-variable</command> <keycap>RET</keycap> <command>server-switch-hook</command></userinput> and enter the function name into the text field.</para> </listitem> <listitem> <para>If you have changed the buffer since your last save, <application>Emacs</application> will ask you: <computeroutput>Revert buffer from file ...? (yes or no)</computeroutput>. You will probably always want to say <emphasis>no</emphasis> here, since reverting means that the file is reread from disk, <emphasis>causing all your changes since the last save to be lost!</emphasis></para> <para><command>gnuclient</command>'s behaviour of silently reloading the changed buffer is probably preferable — add the following lines to your <filename>.emacs</filename> file to emulate <command>gnuclient</command>'s behaviour with <command>emacsclient</command>:</para> <programlisting> (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))) </programlisting> </listitem> </itemizedlist> </tip> </section> <section id="editor-setup-kate"> <title>&kate;</title> <para>Unfortunately, &kde;'s editor &kate; does not support the inverse search very well. A <mousebutton>middle</mousebutton>-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.</para> </section> <section id="editor-setup-nedit"> <title><application>NEdit</application></title> <para><application>NEdit</application> 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 <application>NEdit</application>, the newly opened window displays another view of the buffer. Otherwise, the TeX file is loaded. After opening the window, <application>NEdit</application> highlights the first line of the appropriate paragraph.</para> <tip> <procedure> <step> <para>Make sure that <application>NEdit</application> is installed. Try to start <command>nedit</command> from the command line.</para> </step> <step> <para>&kdvi; uses the command <command>ncl</command> to remote control <application>NEdit</application>. Make sure that <command>ncl</command> is available on the command line by trying the command <userinput><command>ncl</command> <parameter>-noask</parameter></userinput>. This should open an instance of the <application>NEdit</application> editor. If <command>ncl</command> is not available, you might be using an older version of <application>NEdit</application>. In that case, you should either upgrade to a more recent version, or you have to use the option <guilabel>User defined editor</guilabel> from the <guilabel>Options</guilabel> dialog.</para> </step> </procedure> </tip> </section> <section id="editor-setup-xemacs"> <title><application>XEmacs</application></title> <para><application>XEmacs</application> works well with &kdvi;. The actual behaviour of <application>XEmacs</application> depends largely on the configuration. As usual, you can customize <application>XEmacs</application> completely, if you are willing to fight your way through Lisp code.</para> <para>&kdvi; uses the program <command>gnuclient</command> to remote control <application>XEmacs</application>.</para> <important> <para>The program <command>gnuclient</command> requires that <application>XEmacs</application> is running, and that the program <application>gnuserv</application> is started inside <application>XEmacs</application>. Inverse search will not work unless you have started both <application>XEmacs</application> and <application>gnuserv</application>.</para> </important> <para>To start the <application>gnuserv</application> program, you can do one of the following:</para> <itemizedlist> <listitem> <para>In <application>XEmacs</application>, start <application>gnuserv</application> by typing <userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo> <command>gnuserv-start</command></userinput></para> </listitem> <listitem> <para>Add the line <programlisting> (gnuserv-start) </programlisting> to your <filename>.xemacs</filename> file. If you use a more recent version of <application>XEmacs</application>, <filename class="directory">.xemacs</filename> will be a directory. In that case, you should append the line to the file <filename>.xemacs/init.el</filename>. Restart <application>XEmacs</application></para> </listitem> </itemizedlist> <para>If you don't want to open a new frame for each editor call, and want the frame to be auto-raised, set <quote>Gnuserv Frame</quote> to <quote>Use selected frame</quote>, and add the <function>raise-frame</function> function to <quote>Visit Hook</quote>. Do <userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo> <command>customize-group</command> <keycap>RET</keycap> <command>gnuserv</command></userinput> to make these settings.</para> <tip> <itemizedlist> <listitem> <para>Make sure that <application>XEmacs</application> is installed. Try to start <command>xemacs</command> from the command line.</para> </listitem> <listitem> <para>&kdvi; uses the command <application>gnuserv</application> to remote control <application>XEmacs</application>. Make sure that <command>gnuclient</command> is available on the command line by trying the command <userinput><command>gnuclient</command> <parameter>Name of a text file</parameter></userinput>. This should open a new frame in the <application>XEmacs</application> editor.</para> </listitem> <listitem> <para>If <application>gnuserv</application> fails with an error message like <computeroutput>unable to connect to local</computeroutput>, make sure that <application>XEmacs</application> is running. Furthermore, make sure that <application>gnuserv</application> is started by typing <userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo> <command>gnuserv-start</command></userinput>.</para> </listitem> <listitem> <para>If you don't want to open a new frame for each editor call, and want the frame to be auto-raised, set <quote>Gnuserv Frame</quote> to <quote>Use selected frame</quote>, and add the <quote>raise-frame</quote> function to <quote>Visit Hook</quote>. Do <userinput><keycombo action="simul"><keycap>M</keycap><keycap>X</keycap></keycombo> <command>customize-group</command> <keycap>RET</keycap> <command>gnuserv</command></userinput> to make these settings.</para> </listitem> </itemizedlist> </tip> </section> <section id="editor-setup-gvim"> <title><application>VI iMproved</application> / &GUI;</title> <para>&kdvi; supports <command>vim</command>, but the result is not thrilling. A <mousebutton>middle</mousebutton> button mouseclick into the &DVI; file will always open a new instance of the <command>vim</command> editor, even if <command>vim</command> is already running and even if the TeX file is already loaded.</para> <tip> <itemizedlist> <listitem> <para>Make sure that <application>VIM/GUI</application> is installed. Try to start <command>gvim</command> from the command line.</para> </listitem> </itemizedlist> </tip> </section> </section> </chapter> <chapter id="forward-search"> <title>Forward search</title> <para>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 <application>Emacs</application> and <application>XEmacs</application> are currently supported. Other editors will hopefully join in soon.</para> <para>To use forward search, you have to do the following:</para> <itemizedlist> <listitem> <para>Set up your editor — this is described below.</para> </listitem> <listitem> <para>Add source file information to your &DVI; file, ⪚ by using the package <command>srcltx</command>. This has been described in the section <link linkend="inverse-search-tex">Producing TeX files for inverse search</link>.</para> </listitem> <listitem> <para>If you use <application>Emacs</application> and everything is properly set up, you just press <userinput><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> <keycombo action="simul">&Ctrl;<keycap>J</keycap> </keycombo></userinput>, and &kdvi; pops up and jumps to the place which corresponds to the place of the TeX file which you are currently editing.</para> </listitem> </itemizedlist> <section id="forward-search-editor"> <title>Setting up your editor for forward search</title> <section id="forw-editor-setup-emacs"> <title><application>Emacs</application></title> <para>In order to use forward search in <application>Emacs</application>, follow these steps:</para> <itemizedlist> <listitem> <para>Download the following <application>Emacs</application> script, <ulink url="kdvi-search.el"> <filename>kdvi-search.el</filename> </ulink> (press &Shift; and &LMB; the filename to download) and store it in a place where <application>Emacs</application> can access it — we recommend a directory <filename class="directory">emacs-scripts</filename>.</para> </listitem> <listitem> <para>Add the lines <programlisting> (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))) </programlisting> to your <filename>.emacs</filename> file. Restart <application>Emacs</application>.</para> </listitem> <listitem> <para>Open <application>Emacs</application>, load a TeX file, produce the corresponding &DVI; file, and either enter the command <userinput><keycombo action="simul"><keycap>M</keycap><keycap>x</keycap> </keycombo><command>kdvi-jump-to-line</command></userinput> or press <userinput><keycombo action="seq"><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> <keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo> </keycombo></userinput>. It may happen that <application>Emacs</application> asks you for the name of a <quote>master file</quote>. 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. <application>Emacs</application> will perhaps also ask to save the name of the master file <quote>as a local variable</quote>, &ie; as a comment at the very end of the file. Type either <userinput>yes</userinput> or <userinput>no</userinput> to continue.</para> </listitem> </itemizedlist> <tip> <itemizedlist> <listitem> <para>Make sure that <application>Emacs</application> is installed. Try to start <command>emacs</command> from the command line.</para> </listitem> <listitem> <para>If <application>Emacs</application> fails to start &kdvi;, you can find its output in the Buffer <guilabel>kdvi-output</guilabel>.</para> </listitem> </itemizedlist> </tip> </section> <section id="forw-editor-setup-xemacs"> <title><application>XEmacs</application></title> <para>To set up <application>XEmacs</application>, follow the steps for <application>Emacs</application> <link linkend="forw-editor-setup-emacs">above</link>, but modify your <filename>.xemacs</filename> rather than your <filename>.emacs</filename> file. If you use a very recent version of <application>XEmacs</application>, <filename class="directory">.xemacs</filename> may be a directory. In that case, append the lines to <filename>.xemacs/init.el</filename>. </para> </section> </section> </chapter> <chapter id="preferences"> <title>The <guilabel>Preferences</guilabel> dialog</title> <anchor id="opts"></anchor> <para>The <guilabel>Preferences</guilabel> dialog can be reached by choosing <guimenuitem>DVI Options</guimenuitem> in the <guimenu>Settings</guimenu> menu.</para> <para>The dialog consists of two tabs, <guilabel>Fonts</guilabel> and <guilabel>Rendering</guilabel>.</para> <sect1 id="opt-fonts"> <title><guilabel>Fonts</guilabel> Options</title> <para>The following picture shows the options dialog of &kdvi;.</para> <screenshot> <screeninfo>The <guilabel>Fonts</guilabel> tab</screeninfo> <mediaobject> <imageobject> <imagedata fileref="optionrequester1.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Fonts</guilabel> tab</phrase> </textobject> </mediaobject> </screenshot> <variablelist> <varlistentry> <term><guilabel>Metafont mode</guilabel> </term> <listitem> <para>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 <command>MetaFont</command> and know what you are doing, it is not a good idea to change these options. You may want to look at the <link linkend="mfmodes">Frequently asked questions</link> section of this manual.</para> <para>Safe values are <guilabel>1200 dpi / Lexmark</guilabel> for good quality, or <guilabel>600 dpi / LaserJet 4</guilabel> for medium quality and faster display.</para> </listitem> </varlistentry> <varlistentry> <term><guilabel>Generate missing fonts</guilabel></term> <listitem> <para>Check this if you want &kdvi; to call the <command>MetaFont</command> 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.</para> </listitem> </varlistentry> </variablelist> </sect1> <sect1 id="opt-rendering"> <title><guilabel>Rendering</guilabel> Options</title> <para>The following picture shows the second options dialog of &kdvi;.</para> <screenshot> <screeninfo>The <guilabel>Rendering</guilabel> tab</screeninfo> <mediaobject> <imageobject> <imagedata fileref="optionrequester2.png" format="PNG"/></imageobject> <textobject> <phrase>The <guilabel>Rendering</guilabel> tab</phrase> </textobject> </mediaobject> </screenshot> <variablelist> <varlistentry> <term><guilabel>Show PostScript specials</guilabel></term> <listitem> <para>If this option is checked, &kdvi; will display &PostScript; graphics which are embedded into the &DVI; file. You probably want to set this option.</para> <para>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.</para> <note> <para>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 <command>xdvi</command> and <command>dvips</command> 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 <filename>KDVI-features.dvi</filename>.</para> </note> </listitem> </varlistentry> <varlistentry> <term><guilabel>Show Hyperlinks</guilabel></term> <listitem> <para>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.</para> </listitem> </varlistentry> <varlistentry> <term><guilabel>Editor for inverse search</guilabel></term> <listitem> <para>If you intend to use <link linkend="inverse-search">inverse search</link>, 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 <application>NEdit</application> editor. If you use one of the pre-configured editors from the <guilabel>Editor</guilabel> combobox, then you don't have to do anything else. If you whish to use a different editor, chose <guilabel>User-defined editor</guilabel> from the <guilabel>Editor</guilabel> combobox and enter the command line which will be used to start your editor. Use the placeholders <token>%f</token> and <token>%l</token> which will be replaced with the name of the TeX file, and the line of the TeX file, respectively.</para> <para>If you use an editor which is not supported, please send us an email at <email>kebekus@kde.org</email> and tell us about the command line you use and how you have configured your editor.</para> </listitem> </varlistentry> </variablelist> </sect1> </chapter> <chapter id="faq"> <title>Frequently asked questions</title> <qandaset> <qandaentry> <question id="fontgen"> <para>What happens when &kdvi; displays the message <computeroutput>KDVI is currently generating bitmap fonts</computeroutput>, and why does the procedure take so long?</para> </question> <answer> <para>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 (<literal role="extension">.pk</literal> 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 roundish 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.</para> <para>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 <literal role="extension">.pk</literal> files for a limited time, ⪚ 100 days. Therefore, if you access the same document more than once, the <literal role="extension">.pk</literal> files will be reused.</para> </answer> </qandaentry> <qandaentry> <question id="mfmodes"> <para>What is a MetaFont Mode?</para> </question> <answer> <para>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 <filename>modes.mf</filename>. A Metafont Mode is just the name of a database entry. For example, the name <quote>ljfour</quote> 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, can print in both 300 and 600 dots per inch. Thus, <quote>ljfour/600</quote> would be a full description.</para> </answer> </qandaentry> </qandaset> </chapter> <chapter id="credits-and-license"> <title>Credits and Licenses</title> <para>&kdvi;</para> <para>&kdvi; is based on based on the stand-alone-program &kdvi; 0.4.3 by Markku Hihnala. That program is in turn based on <application>xdvi</application> version 18f which has many authors.</para> <para>Documentation is copyright 2001, Stefan Kebekus <email>kebekus@kde.org</email></para> <!-- TRANS:CREDIT_FOR_TRANSLATORS --> &underGPL; &underFDL; </chapter> &documentation.index; </book> <!-- Local Variables: mode: sgml sgml-omittag: nil sgml-shorttag: t End: -->