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.
1073 lines
44 KiB
1073 lines
44 KiB
<?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 "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 — read the section on <link
|
|
linkend="forward-search">forward search</link> to learn how to
|
|
set up your editor to start &kdvi; automatically.
|
|
</para>
|
|
|
|
<warning><para>Don't forget the <userinput>file:</userinput>
|
|
prefix or it will give unexpected results. For example, the command
|
|
<userinput><command>kdvi</command>
|
|
<parameter>file:paper.dvi#43</parameter></userinput> will open
|
|
page 43 of the file <filename>paper.dvi</filename>. The command
|
|
<userinput><command>kdvi</command>
|
|
<parameter>paper.dvi#43</parameter></userinput> will try to open
|
|
the file <filename>paper.dvi#43</filename>.</para>
|
|
</warning>
|
|
|
|
<para>There is another option which you will most likely not need
|
|
to specify yourself. If you type
|
|
<userinput><command>kdvi</command> <parameter>--unique</parameter>
|
|
<parameter>somepath/paper.dvi</parameter></userinput>, &kdvi; will
|
|
load the file if there is no other instance running which has the
|
|
file already loaded. If there is, this instance of &kdvi; will pop
|
|
to the front. A command like <userinput><command>kdvi</command>
|
|
<parameter>--unique</parameter>
|
|
<parameter>file:paper.dvi#43</parameter></userinput> can be used
|
|
in shell scripts to make a running instance of &kdvi; to jump to
|
|
page 43.</para>
|
|
|
|
<para>The usual parameters handled by &Qt; and &kde; applications
|
|
also work: <userinput><command>kdvi</command>
|
|
<option>-style</option> <parameter>windows</parameter>
|
|
<option>-display</option> <parameter>:0</parameter>
|
|
<option>-geometry</option> <parameter>400x400+0+0</parameter>
|
|
<option>-caption</option> <parameter>"DVI"</parameter></userinput>
|
|
</para>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="print">
|
|
<title>Printing &DVI; Files</title>
|
|
|
|
<para>&kdvi; can print your &DVI; files using the standard &kde;
|
|
printing interface. Internally, &kdvi; uses the program
|
|
<command>dvips</command> to generate &PostScript;, which is then
|
|
passed on to the printer. In particular, <command>dvips</command>
|
|
must be installed if you want to print with &kdvi;. The program
|
|
<command>dvips</command> uses its own configuration files and its
|
|
own settings, which are fine for most purposes. However, if you
|
|
care for optimal printing results, you should configure
|
|
<command>dvips</command> manually and make sure to set a default
|
|
MetaFont mode which fits your printer best — on many systems
|
|
you'll find a <ulink url="info:/dvips">GNU-texinfo documentation
|
|
of <command>dvips</command></ulink>, and you might also want to
|
|
look for a file called <filename>dvips.dvi</filename> or
|
|
similar.</para>
|
|
</chapter>
|
|
|
|
<chapter id="export">
|
|
<title>Exporting the &DVI; file to other formats</title>
|
|
|
|
<para>If you want to save your file as in &PostScript; or PDF
|
|
format, it is not recommended that you use the printing function
|
|
and redirect the printer output to a file. Instead, you can use
|
|
the export functions which produce better-quality output that
|
|
retains many of the special features of the dvi format and looks
|
|
better in many of the viewing applications, such as Adobe's
|
|
<application>Acrobat Reader</application>. You will find the
|
|
export functions in the <guimenu>File</guimenu> menu.</para>
|
|
|
|
<section id="export-ps">
|
|
<title>Exporting to &PostScript;</title>
|
|
|
|
<para>As in printing, the external program
|
|
<command>dvips</command> is used to generate the &PostScript;
|
|
file. If the &DVI; file contains hyperlinks, these will also be
|
|
included in the &PostScript; file. If you are an expert, and if
|
|
you would like to generate output which is optimized for a
|
|
specific printer, you should probably start
|
|
<command>dvips</command> manually and choose the proper MetaFont
|
|
mode yourself.</para>
|
|
</section>
|
|
|
|
<section id="export-pdf">
|
|
<title>Exporting to <acronym>PDF</acronym></title>
|
|
|
|
<para>In order to produce <acronym>PDF</acronym> files of high
|
|
quality, &kdvi; converts &DVI; to <acronym>PDF</acronym> using
|
|
the external program <command>dvipdfm</command>. If you are
|
|
working on a machine where an older distribution of the TeX
|
|
typesetting system is installed, it may be that the program
|
|
<command>dvipdfm</command> is not installed. In that case, you
|
|
need to use the printing function to generate
|
|
<acronym>PDF</acronym> output.</para>
|
|
|
|
<warning>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If you use an older TeX installation, and if are viewing
|
|
the generated file in Adobe's <application>Acrobat
|
|
reader</application>, you may well find that some of the
|
|
fonts look extremely poor although a printout is fine,
|
|
and although the document looks ok in
|
|
<command>kghostview</command>. This is a known issue with
|
|
the <application>Acrobat Reader</application> and bitmap
|
|
fonts. At the time of writing, the only practicable
|
|
workaround seems to be to avoid bitmap fonts, or to
|
|
upgrade to a more recent TeX installation.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
While <command>dvipdfm</command> produces high-quality
|
|
<acronym>PDF</acronym> files, <command>dvipdfm</command>
|
|
currently currently ignores the &PostScript; that is
|
|
embedded into the &DVI; file. Embedded PostScript is
|
|
generated e.g. by the <application>xy</application> macro
|
|
package, or by the "Embed PostScript files" function
|
|
&kdvi; described <link linkend="embed">below</link>.
|
|
</para>
|
|
<para>
|
|
If you find that the generated <acronym>PDF</acronym>
|
|
file misses graphical data, use the print function of
|
|
&kdvi; instead.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</warning>
|
|
</section>
|
|
|
|
|
|
<section id="export-text">
|
|
<title>Exporting to text files</title>
|
|
|
|
<para>&kdvi; can also save your &DVI; files in text format.</para>
|
|
|
|
<warning>
|
|
<para>
|
|
The &DVI; file standard was not designed with this kind of
|
|
functionality in mind. This function therefore only works
|
|
well with standard ASCII characters. It will not work with
|
|
non-European languages. Depending on the fonts used in the
|
|
files, there may also be problems with accented characters or
|
|
umlauts, and sometimes with ligatures.
|
|
</para>
|
|
</warning>
|
|
</section>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="embed">
|
|
<title>Embedding PostScript files into the &DVI;</title>
|
|
|
|
<para>The traditional way of using graphics with
|
|
<application>TeX</application> does not include the graphics data
|
|
directly in the &DVI; file. Instead, the &DVI; file contains only
|
|
a link to a graphics file which resides on the hard disk. The
|
|
advantage of this procedure is that the &DVI; file stays small,
|
|
and that the graphics file can be modified indepent of the
|
|
document's <application>TeX</application> source. The method,
|
|
however, becomes fairly inconvenient if you intend to archive the
|
|
&DVI; file, or if you wish to send it to someone else: rather than
|
|
handling a single file, you have to deal with a multitude of
|
|
files, which need to be kept in exactly the place specified in the
|
|
&DVI; file for everything to work.</para>
|
|
|
|
<para>For that reason, &kdvi; allows you to embed external
|
|
&PostScript; files into your &DVI; file. To embed all &PostScript;
|
|
files into a &DVI; file, use the menu entry <guimenu>Edit/Embed
|
|
external PostScript files</guimenu> </para>
|
|
|
|
<warning> <para>&DVI; files with embedded &PostScript; work fine
|
|
with most other &DVI; handling software,
|
|
e.g. <application>xdvi</application>,
|
|
<application>dvips</application> or
|
|
<application>dvipdf</application>. One notable exception is the
|
|
<application>dvipdfm</application> program, which currently
|
|
ignores the embedded &PostScript;. Since
|
|
<application>dvipdfm</application> is used internally by the
|
|
"Export to <acronym>PDF</acronym>" function of &kdvi;, expect
|
|
problems when you use that function. The same issue shows with
|
|
other software that uses embedded PostScript, e.g. the
|
|
<application>TeX</application> <application>xy</application> macro
|
|
package.</para> </warning>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="inverse-search">
|
|
<title>Using inverse search</title>
|
|
<anchor id="inv-search"></anchor>
|
|
|
|
<para>Inverse search is a very useful feature when you are writing
|
|
a TeX document yourself. If everything is properly set up, you can
|
|
click into &kdvi;'s window with the
|
|
<mousebutton>middle</mousebutton> mouse button (on some systems,
|
|
when you don't have a three-button mouse, you can simultaneously
|
|
use the <mousebutton>left</mousebutton> and the
|
|
<mousebutton>right</mousebutton> button). After that, your
|
|
favorite editor will open, load the TeX source file and jump to
|
|
the proper paragraph. To use inverse search, do the
|
|
following:</para>
|
|
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Produce a &DVI; file that contains inverse search
|
|
information. This is explained in the section <link
|
|
linkend="inverse-search-tex">Producing TeX files for inverse
|
|
search</link> below. If you just want to test the inverse
|
|
search feature, you can also use the example file
|
|
<filename>KDVI-features.dvi</filename></para>
|
|
</step>
|
|
<step>
|
|
<para>Let &kdvi; know which editor you would like to
|
|
use. Choose an editor in the <guilabel>Preferences</guilabel>
|
|
dialog (this dialog can be reached by choosing
|
|
<guimenuitem>DVI Options</guimenuitem> in the
|
|
<guimenu>Settings</guimenu> menu). The next section of this
|
|
documentation, <link linkend="opt-rendering">Rendering
|
|
Options</link>, explains this dialog in more detail.</para>
|
|
</step>
|
|
<step>
|
|
<para>Some editors need to be started manually, or need
|
|
additional configuration. You will find a description of all
|
|
supported editors in the section <link
|
|
linkend="inverse-search-editor">Setting up your
|
|
editor for inverse search</link> below.</para>
|
|
</step>
|
|
<step>
|
|
<para>Test your setup. Open your &DVI; file in &kdvi; and use
|
|
the <mousebutton>middle</mousebutton> mouse button to click
|
|
into &kdvi;. The editor should pop up and display the TeX
|
|
file.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
|
|
<section id="inverse-search-tex">
|
|
<title>Producing TeX files for inverse search</title>
|
|
<para>There are essentially two ways to produce &DVI; files
|
|
which contain inverse search information: you can either use a
|
|
TeX/LaTeX binary which generates and includes the necessary
|
|
information automatically, or you can include an extra package
|
|
which is written in TeX/LaTeX.</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A TeX binary which generates and includes the
|
|
necessary information automatically is certainly the
|
|
preferred method of including inverse search information.
|
|
If you use version 2 or greater of the <ulink
|
|
url="http://www.tug.org/teTeX/">TeTeX TeX
|
|
distribution</ulink>, you can use the 'src-specials' command
|
|
line option of the tex or latex command, as follows.
|
|
<programlisting>
|
|
tex --src-specials myfile.tex
|
|
</programlisting>
|
|
or
|
|
<programlisting>
|
|
latex --src-specials myfile.tex
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you do not have a TeX binary which includes inverse
|
|
search information natively, copy the files
|
|
<ulink url="srcltx.sty">
|
|
<filename>srcltx.sty</filename> </ulink> and
|
|
<ulink url="srctex.sty"> <filename>srctex.sty</filename>
|
|
</ulink> to the folder where your TeX file resides (you
|
|
can do that by pressing the &Shift; key and &LMB; while the
|
|
mouse pointer is on a hyperlink.) If you use LaTeX, add the
|
|
line
|
|
<programlisting>
|
|
\usepackage[active]{srcltx}
|
|
</programlisting>
|
|
to the preamble of your LaTeX file. If you use plain TeX, the line
|
|
<programlisting>
|
|
\include{srctex}
|
|
</programlisting>
|
|
will do the trick.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<tip>
|
|
<para>While inverse search is extremely useful when you are
|
|
typing a document yourself, it might be a good idea to remove
|
|
the inverse search information before sending the &DVI; file to
|
|
someone else.</para>
|
|
</tip>
|
|
|
|
</section>
|
|
|
|
<section id="inverse-search-editor">
|
|
|
|
<title>Setting up your editor for inverse search</title>
|
|
|
|
<para>While inverse search works generally very well with most
|
|
editors, some of them require a bit of extra care. This section
|
|
explains how to configure your editor.</para>
|
|
|
|
<section id="editor-setup-emacs">
|
|
<title><application>Emacs</application></title>
|
|
|
|
<para><application>Emacs</application> works well with
|
|
&kdvi;. The actual behavior of <application>Emacs</application>
|
|
depends largely on the configuration. As usual, you can
|
|
customize <application>Emacs</application> completely, if you
|
|
are willing to fight your way through Lisp code.</para>
|
|
|
|
<para>&kdvi; uses the program <command>emacsclient</command> to
|
|
remote control <application>Emacs</application>.</para>
|
|
<important>
|
|
<para>The program <command>emacsclient</command> requires that
|
|
<application>Emacs</application> is running, and that the
|
|
program <application>Emacs Server</application> is started inside
|
|
<application>Emacs</application>. Inverse search will not work
|
|
optimally unless you have started both
|
|
<application>Emacs</application> and the <application>Emacs
|
|
Server</application>.</para>
|
|
</important>
|
|
|
|
<para>To start the <application>Emacs Server</application>, you can do
|
|
one of the following:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>In <application>Emacs</application>, start the
|
|
<application>Emacs Server</application> by typing
|
|
<userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo>
|
|
<command>server-start</command></userinput></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Add the line
|
|
<programlisting>
|
|
(server-start)
|
|
</programlisting>
|
|
to your <filename>.emacs</filename> file. Restart
|
|
<application>Emacs</application></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
|
|
<tip>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Make sure that <application>Emacs</application> is
|
|
installed. Try to start <command>emacs</command> from
|
|
the command line.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&kdvi; uses the command
|
|
<command>emacsclient</command> to remote control
|
|
<application>Emacs</application>. Make sure that
|
|
<command>emacsclient</command> is available on the
|
|
command line by trying the command
|
|
<userinput><command>emacsclient</command>
|
|
<parameter>Name of a text
|
|
file</parameter></userinput>. This should open a new
|
|
text in the <application>Emacs</application>
|
|
editor.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If <command>emacsclient</command> fails with an
|
|
error message like <computeroutput>unable to connect to
|
|
local</computeroutput>, make sure that
|
|
<application>Emacs</application> is
|
|
running. Furthermore, make sure that the
|
|
<application>Emacs Server</application> is started by typing
|
|
<userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo>
|
|
<command>server-start</command></userinput>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you want the frame to be auto-raised, add the
|
|
<function>raise-frame</function> function to
|
|
<quote>server-switch-hook</quote> (do
|
|
<userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo>
|
|
<command>customize-variable</command>
|
|
<keycap>RET</keycap>
|
|
<command>server-switch-hook</command></userinput> and
|
|
enter the function name into the text field.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you have changed the buffer since your last
|
|
save, <application>Emacs</application> will ask you:
|
|
<computeroutput>Revert buffer from file ...? (yes or
|
|
no)</computeroutput>. You will probably always want to
|
|
say <emphasis>no</emphasis> here, since reverting means
|
|
that the file is reread from disk, <emphasis>causing all
|
|
your changes since the last save to be
|
|
lost!</emphasis></para>
|
|
|
|
<para><command>gnuclient</command>'s behavior
|
|
of silently reloading the changed buffer is probably
|
|
preferable — add the following lines to your
|
|
<filename>.emacs</filename> file to emulate
|
|
<command>gnuclient</command>'s behavior with
|
|
<command>emacsclient</command>:</para>
|
|
|
|
<programlisting>
|
|
(defadvice server-visit-files (around save-buffers last activate)
|
|
"Try to emulate gnuclient behavior with emacsclient.
|
|
Works only for visiting one buffer at a time."
|
|
(let* ((filen (car (car (ad-get-arg 0))))
|
|
(buf (get-file-buffer filen))
|
|
(this-buf-modified-p nil))
|
|
;;; the following is copied from server-visit-files, with
|
|
;;; a modification for the `verify-visited-file-modtime' test
|
|
(if (and buf (set-buffer buf))
|
|
(if (file-exists-p filen)
|
|
;;; if the file has changed on disk, reload it
|
|
;;; using `find-file-noselect'
|
|
(if (not (verify-visited-file-modtime buf))
|
|
(progn
|
|
(find-file-noselect filen)
|
|
;;; if user answered `no', reset modtime anyway
|
|
;;; so that server-visit-files doesn't realize the
|
|
;;; difference:
|
|
(set-visited-file-modtime)))
|
|
;;; if file exists no longer, we let server-visit-files
|
|
;;; deal with that
|
|
t)
|
|
(setq buf (find-file-noselect filen)))
|
|
(setq this-buf-modified-p (buffer-modified-p buf))
|
|
(set-buffer buf)
|
|
(set-buffer-modified-p nil)
|
|
ad-do-it
|
|
(set-buffer-modified-p this-buf-modified-p)))
|
|
</programlisting>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</tip>
|
|
</section>
|
|
|
|
|
|
<section id="editor-setup-kate">
|
|
<title>&kate;</title>
|
|
|
|
<para>&kde;'s editor &kate; supports inverse search very well.
|
|
No extra setup is required.</para> </section>
|
|
|
|
|
|
<section id="editor-setup-kile">
|
|
<title><application>Kile</application></title>
|
|
|
|
<para>The LaTeX-editor system <application>Kile</application>,
|
|
supports KDVI very well. No extra setup is
|
|
necessary. Further information about Kile can be found at
|
|
<ulink url="http://kile.sourceforge.net">Kile's
|
|
homepage</ulink>.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="editor-setup-nedit">
|
|
<title><application>NEdit</application></title>
|
|
|
|
<para><application>NEdit</application> generally works very well
|
|
indeed. Clicking into the &DVI; file should open a new
|
|
window. If the TeX file is already used in another window of
|
|
<application>NEdit</application>, the newly opened window
|
|
displays another view of the buffer. Otherwise, the TeX file is
|
|
loaded. After opening the window,
|
|
<application>NEdit</application> highlights the first line of
|
|
the appropriate paragraph.</para>
|
|
<tip>
|
|
<para>&kdvi; uses the command <command>ncl</command> to
|
|
remote control <application>NEdit</application>. Make sure
|
|
that <command>ncl</command> is available on the command line
|
|
by trying the command <userinput><command>ncl</command>
|
|
<parameter>-noask</parameter></userinput>. This should
|
|
open an instance of the <application>NEdit</application>
|
|
editor. If <command>ncl</command> is not available, you
|
|
might be using an older version of
|
|
<application>NEdit</application>. In that case, you should
|
|
either upgrade to a more recent version, or you have to use
|
|
the option <guilabel>User defined editor</guilabel> from the
|
|
<guilabel>Options</guilabel> dialog.</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="editor-setup-xemacs">
|
|
<title><application>XEmacs</application></title>
|
|
|
|
<para><application>XEmacs</application> works well with
|
|
&kdvi;. The actual behavior of
|
|
<application>XEmacs</application> depends largely on the
|
|
configuration. As usual, you can customize
|
|
<application>XEmacs</application> completely, if you are willing
|
|
to fight your way through Lisp code.</para>
|
|
|
|
<para>&kdvi; uses the program <command>gnuclient</command> to
|
|
remote control <application>XEmacs</application>.</para>
|
|
<important>
|
|
<para>The program <command>gnuclient</command> requires that
|
|
<application>XEmacs</application> is running, and that the
|
|
program <application>gnuserv</application> is started inside
|
|
<application>XEmacs</application>. Inverse search will not
|
|
work unless you have started both
|
|
<application>XEmacs</application> and
|
|
<application>gnuserv</application>.</para>
|
|
</important>
|
|
|
|
<para>To start the <application>gnuserv</application> program, you can
|
|
do one of the following:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>In <application>XEmacs</application>, start
|
|
<application>gnuserv</application> by typing
|
|
<userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo>
|
|
<command>gnuserv-start</command></userinput></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Add the line
|
|
<programlisting>
|
|
(gnuserv-start)
|
|
</programlisting>
|
|
to your <filename>.xemacs</filename> file. If you use a
|
|
more recent version of <application>XEmacs</application>,
|
|
<filename class="directory">.xemacs</filename> will be a
|
|
folder. In that case, you should append the line to the
|
|
file <filename>.xemacs/init.el</filename>. Restart
|
|
<application>XEmacs</application></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>If you don't want to open a new frame for each editor
|
|
call, and want the frame to be auto-raised, set <quote>Gnuserv
|
|
Frame</quote> to <quote>Use selected frame</quote>, and add the
|
|
<function>raise-frame</function> function to <quote>Visit
|
|
Hook</quote>. Do <userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo>
|
|
<command>customize-group</command> <keycap>RET</keycap>
|
|
<command>gnuserv</command></userinput> to make these
|
|
settings.</para>
|
|
|
|
<tip>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Make sure that <application>XEmacs</application>
|
|
is installed. Try to start <command>xemacs</command>
|
|
from the command line.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&kdvi; uses the command <application>gnuserv</application>
|
|
to remote control
|
|
<application>XEmacs</application>. Make sure that
|
|
<command>gnuclient</command> is available on the command
|
|
line by trying the command
|
|
<userinput><command>gnuclient</command> <parameter>Name
|
|
of a text file</parameter></userinput>. This should open
|
|
a new frame in the <application>XEmacs</application>
|
|
editor.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If <application>gnuserv</application> fails with an error
|
|
message like <computeroutput>unable to connect to
|
|
local</computeroutput>, make sure that
|
|
<application>XEmacs</application> is
|
|
running. Furthermore, make sure that
|
|
<application>gnuserv</application> is started by typing
|
|
<userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo>
|
|
<command>gnuserv-start</command></userinput>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you don't want to open a new frame for each
|
|
editor call, and want the frame to be auto-raised, set
|
|
<quote>Gnuserv Frame</quote> to <quote>Use selected
|
|
frame</quote>, and add the <quote>raise-frame</quote>
|
|
function to <quote>Visit Hook</quote>. Do
|
|
<userinput><keycombo action="simul"><keycap>M</keycap><keycap>X</keycap></keycombo>
|
|
<command>customize-group</command> <keycap>RET</keycap>
|
|
<command>gnuserv</command></userinput> to make these
|
|
settings.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="editor-setup-gvim">
|
|
<title><application>VI iMproved</application> / &GUI;</title>
|
|
|
|
<para>The <application>gvim</application> variant of the
|
|
<application>vi</application> editor supports inverse search very well.
|
|
No extra setup is required.</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="forward-search">
|
|
<title>Forward search</title>
|
|
|
|
<para>The forward search functions allow you to jump from your
|
|
editor directly into the associated position of the &DVI;
|
|
file. Since forward search must be supported by your editor, only
|
|
<application>Emacs</application> and
|
|
<application>XEmacs</application> are currently supported. Other
|
|
editors will hopefully join in soon.</para>
|
|
|
|
<para>To use forward search, you have to do the following:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Set up your editor — this is described below.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Add source file information to your &DVI; file, ⪚ by
|
|
using the package <command>srcltx</command>. This has been
|
|
described in the section <link linkend="inverse-search-tex">Producing TeX files for inverse
|
|
search</link>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you use <application>Emacs</application> and
|
|
everything is properly set up, you just press
|
|
<userinput><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> <keycombo
|
|
action="simul">&Ctrl;<keycap>J</keycap>
|
|
</keycombo></userinput>, and &kdvi; pops up and jumps to the
|
|
place which corresponds to the place of the TeX file which you
|
|
are currently editing.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="forward-search-editor">
|
|
<title>Setting up your editor for forward search</title>
|
|
|
|
<section id="forw-editor-setup-emacs">
|
|
<title><application>Emacs</application></title>
|
|
|
|
<para>In order to use forward search in
|
|
<application>Emacs</application>, follow these steps:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Download the following
|
|
<application>Emacs</application> script,
|
|
<ulink url="kdvi-search.el">
|
|
<filename>kdvi-search.el</filename> </ulink> (press
|
|
&Shift; and &LMB; the filename to download) and store
|
|
it in a place where <application>Emacs</application>
|
|
can access it — we recommend a folder
|
|
<filename class="directory">emacs-scripts</filename>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Add the lines
|
|
<programlisting>
|
|
(add-to-list 'load-path (expand-file-name "~/emacs-scripts/"))
|
|
(require 'kdvi-search)
|
|
(add-hook 'LaTeX-mode-hook (lambda () (local-set-key "\C-x\C-j" 'kdvi-jump-to-line)))
|
|
(add-hook 'tex-mode-hook (lambda () (local-set-key "\C-x\C-j" 'kdvi-jump-to-line)))
|
|
</programlisting>
|
|
to your <filename>.emacs</filename> file. Restart
|
|
<application>Emacs</application>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Open <application>Emacs</application>, load a
|
|
TeX file, produce the corresponding &DVI; file, and either
|
|
enter the command <userinput><keycombo action="simul"><keycap>M</keycap><keycap>x</keycap>
|
|
</keycombo><command>kdvi-jump-to-line</command></userinput>
|
|
or press <userinput><keycombo action="seq"><keycombo
|
|
action="simul">&Ctrl;<keycap>X</keycap></keycombo>
|
|
<keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo>
|
|
</keycombo></userinput>.
|
|
It may happen that <application>Emacs</application> asks
|
|
you for the name of a <quote>master file</quote>. This is
|
|
useful if you use a TeX file which includes other files:
|
|
the master file is the top-level file which includes the
|
|
others. <application>Emacs</application> will perhaps also
|
|
ask to save the name of the master file <quote>as a local
|
|
variable</quote>, &ie; as a comment at the very end of the
|
|
file. Type either <userinput>yes</userinput> or
|
|
<userinput>no</userinput> to continue.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<tip>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Make sure that <application>Emacs</application> is
|
|
installed. Try to start <command>emacs</command> from
|
|
the command line.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If <application>Emacs</application> fails to start
|
|
&kdvi;, you can find its output in the Buffer
|
|
<guilabel>kdvi-output</guilabel>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="forw-editor-setup-kile">
|
|
<title><application>Kile</application></title>
|
|
<para>If you use Kile, no further setup is necessary.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="forw-editor-setup-xemacs">
|
|
<title><application>XEmacs</application></title>
|
|
|
|
<para>To set up <application>XEmacs</application>, follow the
|
|
steps for <application>Emacs</application> <link
|
|
linkend="forw-editor-setup-emacs">above</link>, but modify
|
|
your <filename>.xemacs</filename> rather than your
|
|
<filename>.emacs</filename> file. If you use a very recent
|
|
version of <application>XEmacs</application>, <filename
|
|
class="directory">.xemacs</filename> may be a folder. In
|
|
that case, append the lines to
|
|
<filename>.xemacs/init.el</filename>.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="preferences">
|
|
<title>The <guilabel>Preferences</guilabel> dialog</title>
|
|
<anchor id="opts"></anchor>
|
|
|
|
<para>The <guilabel>Preferences</guilabel> dialog can be reached
|
|
by choosing <guimenuitem>DVI Options</guimenuitem> in the
|
|
<guimenu>Settings</guimenu> menu.</para>
|
|
|
|
<para>The dialog consists of two tabs, <guilabel>Fonts</guilabel>
|
|
and <guilabel>Rendering</guilabel>.</para>
|
|
|
|
<sect1 id="opt-fonts">
|
|
<title><guilabel>Fonts</guilabel> Options</title>
|
|
|
|
<para>
|
|
Traditionally, the TeX typsetter uses fonts that are generated
|
|
by the <command>MetaFont</command> program. These fonts are
|
|
stored in the PK format. While a carefully configured
|
|
<command>MetaFont</command> system produces printouts of
|
|
highest quality, its configuration requires serious expertise,
|
|
<command>MetaFont</command> is not very good at producing fonts
|
|
suitable for computer displays, and there are only few
|
|
<command>MetaFont</command> fonts available for Asian
|
|
languages.
|
|
</para>
|
|
|
|
<para>
|
|
To overcome these problems, newer TeX installations therefore
|
|
include fonts that are stored in the "PostScript Type 1"
|
|
format, which is a widely used font format in electronic
|
|
publishing. &kdvi; is able to use both font formats.
|
|
</para>
|
|
|
|
<para>
|
|
The following picture shows the font options dialog of &kdvi;
|
|
that can be used to control &kdvi;'s use of the various font
|
|
formats.
|
|
</para>
|
|
|
|
<screenshot>
|
|
<screeninfo>The <guilabel>Fonts</guilabel> tab</screeninfo>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="optionrequester1.png" format="PNG"></imagedata>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>The <guilabel>Fonts</guilabel> tab</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel>Use font hinting for Type 1 fonts, if available</guilabel> </term>
|
|
<listitem>
|
|
<para>
|
|
PostScript "Type 1" often contain "font hints",
|
|
i.e. additional information that is supposed to
|
|
help software produce better quality output on
|
|
computer screens. The quality of the font hints
|
|
varies from font to font, and you should experiment
|
|
to see if enabling this option gives better results.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="opt-rendering">
|
|
<title><guilabel>&DVI; specials</guilabel> Options</title>
|
|
|
|
<para>
|
|
&kdvi; supports a large number of extensions to the original
|
|
&DVI; format, e.g. hyperlinks, graphic file inclusion or
|
|
embedded source file information. These extensions are known as
|
|
"&DVI; specials". A full account of specials supported by
|
|
&kdvi; can be found in <ulink url="KDVI-features.dvi">this
|
|
document</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
The &DVI; specials dialog help you to configure support for
|
|
some specials. </para>
|
|
|
|
<screenshot>
|
|
<screeninfo>The <guilabel>Rendering</guilabel> tab</screeninfo>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="optionrequester2.png"
|
|
format="PNG"></imagedata>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>The <guilabel>Rendering</guilabel> tab</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel>Show PostScript specials</guilabel></term>
|
|
<listitem>
|
|
<para>If this option is checked, &kdvi; will display
|
|
&PostScript; graphics which are embedded into the &DVI;
|
|
file. You probably want to set this option.</para>
|
|
|
|
<para>If an external &PostScript; file could not be found,
|
|
&kdvi; will draw a red warning box in its
|
|
place. Unfortunately, rendering &PostScript; graphics is
|
|
very slow in the current version of &kdvi;. We will
|
|
improve on the speed in later versions. If this option is
|
|
off, &kdvi; will either draw a gray box as a placeholder
|
|
for the graphics, or it will leave the space blank.</para>
|
|
|
|
<note>
|
|
<para>There is no standard way to embed &PostScript;
|
|
graphics into a &DVI; file. It may therefore happen that
|
|
&kdvi; cannot properly display a graphic which works
|
|
fine with other programs. Older versions of
|
|
<command>xdvi</command> and <command>dvips</command>
|
|
support the execution of external commands. This is a
|
|
bad security risk and therefore deliberately not
|
|
implemented in &kdvi;. Technical information about
|
|
supported ways to include &PostScript; can be found in
|
|
the document
|
|
<filename>KDVI-features.dvi</filename>.</para>
|
|
</note>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term><guilabel>Editor for inverse search</guilabel></term>
|
|
<listitem>
|
|
<para>If you intend to use <link linkend="inverse-search">inverse search</link>, a
|
|
very useful feature if you write TeX documents yourself,
|
|
you have to specify which editor you are going to use, and
|
|
how this editor can be started by &kdvi;. In the example
|
|
shown, the user has opted for the
|
|
<application>NEdit</application> editor. If you use one of
|
|
the pre-configured editors from the
|
|
<guilabel>Editor</guilabel> combobox, then you don't have
|
|
to do anything else. If you whish to use a different
|
|
editor, chose <guilabel>User-defined editor</guilabel>
|
|
from the <guilabel>Editor</guilabel> combobox and enter
|
|
the command line which will be used to start your
|
|
editor. Use the placeholders <token>%f</token> and
|
|
<token>%l</token> which will be replaced with the name of
|
|
the TeX file, and the line of the TeX file,
|
|
respectively.</para>
|
|
|
|
<para>If you use an editor which is not supported, please
|
|
send us an email at <email>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,
|
|
⪚ 100 days. Therefore, if you access the same document
|
|
more than once, the <literal role="extension">.pk</literal>
|
|
files will be reused.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question id="mfmodes">
|
|
<para>What is a MetaFont Mode?</para>
|
|
</question>
|
|
<answer>
|
|
<para>In order to produce bitmap fonts which are optimized
|
|
for your printer (see the answer to the first question),
|
|
Metafont comes with a database of printing engines — look
|
|
for a file called <filename>modes.mf</filename>. A Metafont
|
|
Mode is just the name of a database entry. For example, the
|
|
name <quote>ljfour</quote> refers to the entry in the
|
|
database that describes a &Hewlett-Packard; LaserJet 4
|
|
printer. A MetaFont Mode is usually followed by a number,
|
|
the resolution. The LaserJet, for instance, can print in both
|
|
300 and 600 dots per inch. Thus, <quote>ljfour/600</quote>
|
|
would be a full description.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
</qandaset>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="credits-and-license">
|
|
<title>Credits and Licenses</title>
|
|
|
|
<para>&kdvi;</para>
|
|
|
|
<para>&kdvi; is based on based on the stand-alone-program &kdvi;
|
|
0.4.3 by Markku Hihnala. That program is in turn based on
|
|
<application>xdvi</application> version 18f which has many
|
|
authors.</para>
|
|
|
|
<para>Documentation is copyright 2001-2004, Stefan Kebekus
|
|
<email>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:
|
|
-->
|
|
|