okular/doc/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
 <!ENTITY kappname "&kdvi;">
 <!ENTITY % English "INCLUDE">
 <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">

<bookinfo>
<title> The &kdvi; Manual</title>

<authorgroup>
<author>
<firstname>Markku</firstname>
<surname>Hihnala</surname>
<affiliation><address><email>mah@ee.oulu.fi</email></address></affiliation>
</author>

<author>
<firstname>Stefan</firstname>
<surname>Kebekus</surname>
<affiliation><address><email>kebekus@kde.org</email></address></affiliation>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<date>2001-06-05</date>
<releaseinfo>0.09.02</releaseinfo>

<legalnotice>&underFDL;</legalnotice>

<copyright>
<year>2000</year>
<holder>Markku Hihnala</holder>
<holder>Stefan Kebekus</holder>
</copyright>

<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="introduction">
<title>Introduction</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.
</para>

<para>
More information about TeX and &DVI; can be found on the homepage of the
TeX user group. &kdvi; supports the inclusion of &PostScript; graphics
and it supports hyperlinks. More details and the technical
specifications can be found in the file
<filename>KDVI-features.dvi</filename>.
</para>

<para>
For up-to-date information, consult <ulink
url="http://devel-home.kde.org/~kdvi">kdvi's home page</ulink>.
</para>

</chapter>

<chapter id="starting">
<title>Starting &kdvi;</title>

<para>
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>, 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.
</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>

<para>
For integration with TeX the opened &DVI; file is automatically reloaded
when changed.
</para>

</chapter>

<chapter id="preferences">
<title>The <guilabel>Preferences</guilabel> dialog</title>

<para>
The <guilabel>Preferences</guilabel> dialog can be reached by choosing
<menuchoice><guimenu>Settings</guimenu> <guimenuitem>DVI
options</guimenuitem></menuchoice> inside &kviewshell;.
</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> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="optionrequester1.png" format="PNG"/></imageobject>
<textobject>
<phrase>The <guilabel>Fonts</guilabel> dialog</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.
</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> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="optionrequester2.png" format="PNG"/></imageobject>
<textobject>
<phrase>The <guilabel>Rendering</guilabel> dialog</phrase>
</textobject>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Show PostScript specials</guilabel></term>
<listitem>
<para>
If this options is checked, &kdvi; will display
&PostScript; graphics which are embedded into the &DVI;
file.
</para>

<para>
If an external &PostScript; file could not be found, &kdvi; will draw a
red warning box in its place. Unfortunately, rendering &PostScript;
graphics is very slow in the current version of &kdvi;.  We will improve
on the speed in later versions. If this option is off, &kdvi; will
either draw a grey box as a placeholder for the graphics, or it will
leave the space blank.
</para>

<note>
<para>
There is no standard way to embed &PostScript; graphics into a dvi
file. It may therefore happen that &kdvi; cannot properly display a
graphic which works fine with other programs. Older versions of
<command>xdvi</command> and <command>dvips</command> support the
execution of external commands. This is a 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. You probably want to set this option.
</para>
</note>

</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>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>
</variablelist>

</sect1>
</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 <command>dvips</command> and
<command>dvilj4</command>. If you use <command>dvips</command>, you can
also have an n-up program called to make 2 or 4 pages per sheet. Select
<command>psnup</command> (preferred) or <command>mpage</command> (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
<command>lpr</command>) that is supposed to read standard input. Option
<option>-P</option> 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="faq">
<title>Q &amp; A</title>

<qandaset>
<qandaentry>
<question>
<para>
Why is &kdvi; not displaying anything but a busy cursor?
</para>
</question>
<answer>
<para>
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
<command>strace</command> and see below for a cure.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
What can I do when &kdvi; does not find my PK-fonts?
</para>
</question>
<answer>
<para>
You must have correct settings for resolution and
<command>Metafont</command> 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: <userinput><filename
class="directory">/var/lib/texmf/fonts/pk/ljfour/</filename>:<filename
class="directory"><replaceable>/some/other/place</replaceable></filename></userinput>.
You can make &kdvi; search recursively by adding an extra / at the end
of directory name: <userinput>/var/lib/texmf/fonts//</userinput> (This
works like <command>xdvi</command>'s <envar>XDVIFONTS</envar>
environment variable.  There is also good (gnu <command>info</command>)
documentation available for the kpathsea library that &kdvi; uses for
font searching.)  This makes &kdvi; usable when you have some other tex
system than <command>tetex</command> and don't have the
<filename>texmf.cnf</filename> file.
</para>
</answer>
</qandaentry>

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


<chapter id="credits-and-license">
<title>Credits and Licenses</title>

<para>&kdvi;</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
<application>xdvi</application> version 18f which has many authors.
</para>

<para>
Documentation is copyright 2000, 2001, Markku Hihnala
<email>mah@ee.oulu.fi</email> and Stefan Kebekus
<email>kebekus@kde.org</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underGPL;
&underFDL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<para>
&kdvi; is part of the kdegraphics module of &kde;.
</para>

</appendix>

</book>