okular/doc/index.docbook

<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN">

<book lang="en">
  <bookinfo>
    <title> The KDVI Manual</title>
    <authorgroup>
      <author>
	<firstname>Markku</firstname>
	<surname>Hihnala</surname>
	<affiliation>
	  <address role="email">mah@ee.oulu.fi</address>
	</affiliation>
      </author>
      
      <author>
	<firstname>Stefan</firstname>
	<surname>Kebekus</surname>
	<affiliation>
	  <address role="email">kebekus@kde.org</address>
	</affiliation>
      </author>
    </authorgroup>

    <date>30/06/2000</date>
    <releaseinfo>0.9 beta</releaseinfo>
    <abstract>
      <para>This Handbook describes KDVI Version 0.9</para>
    </abstract>
    <keywordset>
      <keyword>KDE</keyword>
      <keyword>DVI</keyword>
      <keyword>TeX</keyword>
      <keyword>LaTeX</keyword>
      <keyword>device-independent</keyword>
      <keyword>viewer</keyword>
      <keyword>dvi viewer</keyword>
      <keyword>kdvi</keyword>
      <keyword>xdvi</keyword>
    </keywordset>
  </bookinfo>

  <chapter id="usage">
    <title>Usage</title>

    <para>kdvi is a plugin for the kviewshell program which allows
    kviewshell to display dvi-files which are produced by the TeX
    typesetting system. More information about TeX and DVI can be
    found on the homepage of the TeX user group. kdvi 0.9 supports the
    inclusion of PostScript graphics and it supports hyperlinks. More
    details and the technical specifications can be found in a <ulink
    url="KDVI-features.dvi">separate document</ulink>. For up-to-date
    information, consult <ulink
    url="http://devel-home.kde.org/~kdvi">kdvi's home
    page</ulink>.</para>

    <para>kdvi 0.9 is based on based on the stand-alone-program kdvi
    0.4.3 by Markku Hihnala. That program is in turn based on xdvik
    version 18f which has many authors.</para>

    <para>For convenience there exists a command kdvi which calls
    kviewshell with the kdvi-plugin preloaded. The viewer may thus be
    started using the command <screen>kdvi somepath/paper.dvi</screen>
    or without a file name as kviewshell will then allow a file to be
    opened from a dialog or a menu of recently used files. This menu
    can also be popped up by clicking the File button with the right
    mouse button.</para>

    <para>The usual parameters handled by Qt and KDE applications also
    work: <screen>kdvi -style windows -display :0 -geometry 400x400+0+0 -caption "DVI"</screen>
    For integration with TeX the opened DVI file is automatically
    reloaded when changed.</para>


  </chapter>

  <chapter id="options">
    <title>The option dialog</title>

    <anchor id="opts">
    <section id="opt-fonts">
      <title>Font Options</title>

      <para> The following picture shows the options dialog of
      kdvi.</para>
      <informalfigure>
	<graphic fileref="optionrequester1.png"></graphic>	
      </informalfigure>

      <glosslist>
	<glossentry>
	  <glossterm>Resolution/Metafont mode</glossterm> 
	  <glossdef> 
	    <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 MetaFont and know what you are doing,
	    it is absolutely no good idea to change these
	    options. Save values are "600" and "ljfour" for good
	    quality or "300" and "cx" for medium quality and faster
	    display.</para> 
	  </glossdef>
	</glossentry>
      
	<glossentry>
	  <glossterm>Generate fonts</glossterm> 
	  <glossdef> 
	    <para> Check this if you want kdvi to call the MetaFont
	    program in the likely case that kdvi wants to display
	    documents which use fonts which are not yet readily
	    made. You most certainly want to set this option.</para>
	    </glossdef>
	</glossentry>

	<glossentry>
	  <glossterm>PK font path</glossterm> 
	  <glossdef> 

	    <para>	    If this is not empty, it points to a list of directories
	    to be searched for pk-fonts, e.g.
	    <screen>
/var/lib/texmf/fonts/pk/ljfour/:/some/other/place
            </screen>
	    You can make kdvi search recursively by adding an extra /
	    at the end of directory name: <screen>

/var/lib/texmf/fonts//
            </screen>
	    This works like xdvi's XDVIFONTS environment
	    variable. There is also good (gnu info) documentation
	    available for the kpathsea library that kdvi uses for font
	    searching. This makes kdvi usable when you have some other
	    tex system than tetex and don't have the texmf.cnf
	    file. Again this option is strikly for the experts only.</para>
	    </glossdef> 
	</glossentry>
      </glosslist>
    </section>
    
    <section id="opt-rendering">
      <title>Rendering Options</title>


      <para> The following picture shows the second options dialog of
      kdvi.
      <informalfigure>
	  <graphic fileref="optionrequester2.png"></graphic>
	</informalfigure>
</para>
      
      <glosslist>
	<glossentry>
	  <glossterm>PostScript</glossterm> 
	  <glossdef> 

	    <para> If this options is checked, kdvi will display
	    PostScript graphics which are embedded into the dvi
	    file. 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>

	    <para> Note: there is no standard way to embed PostScript
	    graphics into a dvi file. It may therefore happen that
	    kdvi cannot properly display a graphic which works fine
	    with other programs. Older versions of xdvi and dvips
	    support the execution of external commands. This is a
	    hight security risk and therefore deliberately not
	    implemented in kdvi. Technical information about supported
	    ways to include PostScript can be found in an external
	    document.</para>
	  </glossdef>
      </glossentry>

	<glossentry>
	  <glossterm>Hyperlinks</glossterm> 
	  <glossdef> 

	    <para> Check this if you want kdvi to display
	    hyperlinks. The appropriate parts of the text will be
	    underlined in blue.</para> </glossdef>
	</glossentry>
      </glosslist>
    </section>
  </chapter>


  <chapter id="Printing">
    <title>Printing</title>

    <para>This version has a print setup dialog (available from the
    print dialog) that lets you configure the printing method, n-up
    program, printer names and spooler command. Printing method
    selects the external program to use for printing.  Available
    choices are dvips and dvilj4. If you use dvips, you can also have
    an n-up program called to make 2 or 4 pages per sheet. Select
    psnup (preferred) or mpage (may work) if you have that installed
    in your system.</para>

    <para>You may add printer names that will be available in the
    print dialog.</para>

    <para>And last you can change the spooler command (defaults to
    lpr) that is supposed to read standard input. Option -P is
    appended when printing to nondefault printer.</para>

    <para>Having setup printing you can use the print dialog where you
    can select the pages to be printed, which printer or file to use
    for output and more.</para>
</chapter>

<chapter id="QampA">
<title>Q &amp; A</title>

<para>Q: Why is kdvi not displaying anything but a busy cursor?
A: It is
possible, that kdvi is searching for the pk-fonts from wrong places,
and this can be very time consuming if these include network mounted
filesystems. You can check for this with strace and see below for a
cure.</para>

<para>Q: What can I do when kdvi does not find my PK-fonts?
A: You must have correct settings for resolution and Metafont mode. 
If this does not help, you may set the field
'PK Font Path' in Preferences/Fonts to point to the  list of directories
to be searched for pk-fonts:
/var/lib/texmf/fonts/pk/ljfour/:/some/other/place
You can make kdvi search recursively by adding an extra / at the end of
directory name:
/var/lib/texmf/fonts//
(This works like xdvi's XDVIFONTS environment variable.
There is also good (gnu info) documentation available for the kpathsea library
that kdvi uses for font searching.)
This makes kdvi usable when you have some other tex system than tetex and don't
have the texmf.cnf file.</para>

<para>Q: How do I get the font generation to work?
A: If you like to enable automatic font generation using MakeTeXPK,
you must also supply correct Metafont mode in preferences dialog.
When automatic pk-font generation is disabled (menu option)
the missing fonts will be logged to file missfont.log in the current directory.
It is a good idea to check that the font generation commands in
missfont.log are correct before enabling font generation.</para>
</chapter>

</book>