You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdegraphics/doc/kdvi/index.docbook

1072 lines
43 KiB

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY kappname "&kdvi;">
<!ENTITY package "tdegraphics">
<!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-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 &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 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 &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 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 &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>&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 &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 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>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-2004, 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:
-->