okular/doc/index.docbook

<?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>2003-09-07</date>
    <releaseinfo>1.10.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 &mdash; 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>&quot;DVI&quot;</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 &mdash; 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="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</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 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>
      <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 behavior
	      of silently reloading the changed buffer is probably
	      preferable &mdash; 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>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-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://perso.club-internet.fr/pascal.brachet/kile">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>
      <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 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
           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 &mdash; this is described below.</para>
      </listitem>
      <listitem>
        <para>Add source file information to your &DVI; file, &eg; 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 &mdash; 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-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 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 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>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,
          &eg; 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 &mdash; 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:
-->