diff options
Diffstat (limited to 'doc/kdvi/index.docbook')
| -rw-r--r-- | doc/kdvi/index.docbook | 1072 |
1 files changed, 1072 insertions, 0 deletions
diff --git a/doc/kdvi/index.docbook b/doc/kdvi/index.docbook new file mode 100644 index 00000000..cd60e640 --- /dev/null +++ b/doc/kdvi/index.docbook @@ -0,0 +1,1072 @@ +<?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>[email protected]</email> + </address> + </affiliation> + </author> + <!-- TRANS:ROLES_OF_TRANSLATORS --> + </authorgroup> + + <copyright> + <year>2001-2004</year> + <holder>Stefan Kebekus</holder> + </copyright> + + <legalnotice>&FDLNotice;</legalnotice> + + <date>2004-02-27</date> + <releaseinfo>1.11.00</releaseinfo> + + <abstract> + <para>This document describes &kdvi; version 1.1</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 program + <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 program + <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 program + <command>dvipdfm</command> is not installed. In that case, you + need to use the printing function to generate + <acronym>PDF</acronym> output.</para> + + <warning> + <itemizedlist> + <listitem> + <para> + If you use an older TeX installation, and if 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 + <command>kghostview</command>. 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, or to + upgrade to a more recent TeX installation. + </para> + </listitem> + <listitem> + <para> + While <command>dvipdfm</command> produces high-quality + <acronym>PDF</acronym> files, <command>dvipdfm</command> + currently currently ignores the &PostScript; that is + embedded into the &DVI; file. Embedded PostScript is + generated e.g. by the <application>xy</application> macro + package, or by the "Embed PostScript files" function + &kdvi; described <link linkend="embed">below</link>. + </para> + <para> + If you find that the generated <acronym>PDF</acronym> + file misses graphical data, use the print function of + &kdvi; instead. + </para> + </listitem> + </itemizedlist> + </warning> + </section> + + + <section id="export-text"> + <title>Exporting to text files</title> + + <para>&kdvi; can also save your &DVI; files in text format.</para> + + <warning> + <para> + The &DVI; file standard was not designed with this kind of + functionality in mind. This function therefore only works + well with standard ASCII characters. It will not work with + non-European languages. Depending on the fonts used in the + files, there may also be problems with accented characters or + umlauts, and sometimes with ligatures. + </para> + </warning> + </section> + </chapter> + + + <chapter id="embed"> + <title>Embedding PostScript files into the &DVI;</title> + + <para>The traditional way of using graphics with + <application>TeX</application> does not include the graphics data + directly in the &DVI; file. Instead, the &DVI; file contains only + a link to a graphics file which resides on the hard disk. The + advantage of this procedure is that the &DVI; file stays small, + and that the graphics file can be modified indepent of the + document's <application>TeX</application> source. The method, + however, becomes fairly inconvenient if you intend to archive the + &DVI; file, or if you wish to send it to someone else: rather than + handling a single file, you have to deal with a multitude of + files, which need to be kept in exactly the place specified in the + &DVI; file for everything to work.</para> + + <para>For that reason, &kdvi; allows you to embed external + &PostScript; files into your &DVI; file. To embed all &PostScript; + files into a &DVI; file, use the menu entry <guimenu>Edit/Embed + external PostScript files</guimenu> </para> + + <warning> <para>&DVI; files with embedded &PostScript; work fine + with most other &DVI; handling software, + e.g. <application>xdvi</application>, + <application>dvips</application> or + <application>dvipdf</application>. One notable exception is the + <application>dvipdfm</application> program, which currently + ignores the embedded &PostScript;. Since + <application>dvipdfm</application> is used internally by the + "Export to <acronym>PDF</acronym>" function of &kdvi;, expect + problems when you use that function. The same issue shows with + other software that uses embedded PostScript, e.g. the + <application>TeX</application> <application>xy</application> macro + package.</para> </warning> + </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 + favorite 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 for inverse search</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. + If you use version 2 or greater of the <ulink + url="http://www.tug.org/teTeX/">TeTeX TeX + distribution</ulink>, you can use the 'src-specials' command + line option of the tex or latex command, as follows. +<programlisting> +tex --src-specials myfile.tex +</programlisting> +or +<programlisting> +latex --src-specials myfile.tex +</programlisting> + </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 folder 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 for inverse search</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 behavior 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> + <itemizedlist> + <listitem> + <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> + </listitem> + <listitem> + <para>Add the line +<programlisting> +(server-start) +</programlisting> + to your <filename>.emacs</filename> file. Restart + <application>Emacs</application></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>&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 behavior + 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 behavior with + <command>emacsclient</command>:</para> + +<programlisting> +(defadvice server-visit-files (around save-buffers last activate) + "Try to emulate gnuclient behavior 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>&kde;'s editor &kate; supports inverse search very well. + No extra setup is required.</para> </section> + + + <section id="editor-setup-kile"> + <title><application>Kile</application></title> + + <para>The LaTeX-editor system <application>Kile</application>, + supports KDVI very well. No extra setup is + necessary. Further information about Kile can be found at + <ulink url="http://kile.sourceforge.net">Kile's + homepage</ulink>. + </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> + <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> + </tip> + </section> + + <section id="editor-setup-xemacs"> + <title><application>XEmacs</application></title> + + <para><application>XEmacs</application> works well with + &kdvi;. The actual behavior 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 + folder. 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>The <application>gvim</application> variant of the + <application>vi</application> editor supports inverse search very well. + No extra setup is required.</para> + </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 folder + <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-kile"> + <title><application>Kile</application></title> + <para>If you use Kile, no further setup is necessary. + </para> + </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 folder. 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> + Traditionally, the TeX typsetter uses fonts that are generated + by the <command>MetaFont</command> program. These fonts are + stored in the PK format. While a carefully configured + <command>MetaFont</command> system produces printouts of + highest quality, its configuration requires serious expertise, + <command>MetaFont</command> is not very good at producing fonts + suitable for computer displays, and there are only few + <command>MetaFont</command> fonts available for Asian + languages. + </para> + + <para> + To overcome these problems, newer TeX installations therefore + include fonts that are stored in the "PostScript Type 1" + format, which is a widely used font format in electronic + publishing. &kdvi; is able to use both font formats. + </para> + + <para> + The following picture shows the font options dialog of &kdvi; + that can be used to control &kdvi;'s use of the various font + formats. + </para> + + <screenshot> + <screeninfo>The <guilabel>Fonts</guilabel> tab</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="optionrequester1.png" format="PNG"></imagedata> + </imageobject> + <textobject> + <phrase>The <guilabel>Fonts</guilabel> tab</phrase> + </textobject> + </mediaobject> + </screenshot> + + <variablelist> + <varlistentry> + <term><guilabel>Use font hinting for Type 1 fonts, if available</guilabel> </term> + <listitem> + <para> + PostScript "Type 1" often contain "font hints", + i.e. additional information that is supposed to + help software produce better quality output on + computer screens. The quality of the font hints + varies from font to font, and you should experiment + to see if enabling this option gives better results. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="opt-rendering"> + <title><guilabel>&DVI; specials</guilabel> Options</title> + + <para> + &kdvi; supports a large number of extensions to the original + &DVI; format, e.g. hyperlinks, graphic file inclusion or + embedded source file information. These extensions are known as + "&DVI; specials". A full account of specials supported by + &kdvi; can be found in <ulink url="KDVI-features.dvi">this + document</ulink>. + </para> + + <para> + The &DVI; specials dialog help you to configure support for + some specials. </para> + + <screenshot> + <screeninfo>The <guilabel>Rendering</guilabel> tab</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="optionrequester2.png" + format="PNG"></imagedata> + </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 gray 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>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>[email protected]</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-2004, Stefan Kebekus + <email>[email protected]</email></para> + + <!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underGPL; +&underFDL; + + </chapter> + +&documentation.index; + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + |