improved documentation

svn path=/trunk/kdegraphics/doc/kdvi/; revision=116006

doc/KDVI-features.tex

@@ -9,7 +9,7 @@
 \usepackage{hyperref}
 \usepackage[active]{srcltx}
 
-\newcommand{\KDVI}{{\sf KDVI 0.9d}}
+\newcommand{\KDVI}{{\sf KDVI 1.0alpha}}
 
 \begin{document}
 
@@ -58,6 +58,27 @@ In this, we have tried to be consistent with the {\sf dvips} programm.
 \KDVI\ does not support a number of outdated and unsane standards, nor
 does it support features which impair the system security.
 
+\section{Source specials and inverse search}
+
+\KDVI\ supports ``source'' specials. A DVI file which contains these
+specials, such as the file you are currently looking at, allows \KDVI\ 
+to associate the mouse position in \KDVI's window with a line number
+in the TeX source of the DVI file. Practical use: click with the
+middle mouse button into the DVI display, and your favourite editor
+opens, loads the TeX source and jumps to the proper line. You can try
+this right now! See the \href{help:/kdvi/inverse-search.html}{handbook
+  of \KDVI\ } for an explanation how to tell \KDVI\ what you favourite
+editor actually is.
+
+Source information is included by adding the command
+\begin{verbatim}
+\special{src:<line-number><file-name>}
+\end{verbatim}
+to the beginning of each paragraph of your DVI file (or, if you like,
+to the beginning of each line). Again, the
+\href{help:/kdvi/inverse-search.html}{handbook of \KDVI\ } explains
+how to include source specials automatically with no extra work.
+
 
 \section{Virtual fonts}
 

doc/index.docbook

@@ -171,10 +171,13 @@
     <anchor id="inv-search"></anchor>
 
     <para>Inverse search is a very useful feature when you are writing
-    a TeX-text yourself. If everything is properly set up, you can
+    a TeX-document yourself. If everything is properly set up, you can
-    click into KDVI's window with the right mouse button. After that,
+    click into KDVI's window with the middle mouse button (on some
+    systems, when you don't have a three-button mouse, you can
+    simultaneously use the left and the right button). After that,
     your favourite editor will open, load the TeX-sourcefile and jump
-    to the proper paragraph. To use inverse search, do the following:</para>
+    to the proper paragraph. To use inverse search, do the
+    following:</para>
 
 
     <orderedlist>
@@ -189,11 +192,12 @@
       <listitem>
 	<para>Let &kdvi; know which editor you would like to
 	use. Choose an editor in the <guilabel>Preferences</guilabel>
-	dialog which can be reached by choosing
+	dialog (this dialog can be reached by choosing
 	<guimenu>Settings</guimenu> in the menu <guimenuitem>DVI
-	options</guimenuitem>. The next chapter, <ulink
+	options</guimenuitem>). The next chapter of this
-	url="opt-rendering.html">"The preferences dialog/Rendering
+	documentation, <ulink url="opt-rendering.html">"The
-	Options"</ulink>, explains this dialog in more detail.</para>
+	preferences dialog/Rendering Options"</ulink>, explains this
+	dialog in more detail.</para>
       </listitem>
       <listitem>
 	<para>Some editors need to be started manually, or need
@@ -414,8 +418,8 @@
 
     <para>The <guilabel>Preferences</guilabel> dialog can be reached
     by choosing <menuchoice><guimenu>Settings</guimenu>
-    <guimenuitem>DVI options</guimenuitem></menuchoice> inside
+    <guimenuitem>DVI options</guimenuitem></menuchoice> in the
-    &kviewshell;.</para>
+    <guimenu>Settings</guimenu> menu.</para>
 
     <para>The dialog consists of two tabs, <guilabel>Fonts</guilabel>
     and <guilabel>Rendering</guilabel>.</para>
@@ -440,14 +444,16 @@
 
       <variablelist>
 	<varlistentry>
-	  <term><guilabel>Metafont mode</guilabel></term>
+	  <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>
+	    change these options. You may want to look at the <ulink
+	    url="faq.html#MFModes">Frequently asked questions</ulink>
+	    section of this manual.</para>
 
 	    <para>Safe values are <guilabel>1200 dpi /
 	    Lexmark</guilabel> for good quality, or <guilabel>600 dpi
@@ -492,7 +498,7 @@
 	  <listitem>
 	    <para>If this options is checked, &kdvi; will display
 	    &PostScript; graphics which are embedded into the &DVI;
-	    file.</para>
+	    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
@@ -513,22 +519,48 @@
 	      implemented in &kdvi;. Technical information about
 	      supported ways to include &PostScript; can be found in
 	      the document <ulink
-	      url="KDVI-features.dvi"><filename>KDVI-features.dvi</filename></ulink>. You
+	      url="KDVI-features.dvi"><filename>KDVI-features.dvi</filename></ulink>.</para>
-	      probably want to set this option.</para>
+	    </note>
-</note>
 
-</listitem>
+	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
-		       <term><guilabel>Hyperlinks</guilabel></term>
+	  <term><guilabel>Hyperlinks</guilabel></term>
-		       <listitem>
+	  <listitem>
-		       <para>Check this if you want &kdvi; to display
+	    <para>Check this if you want &kdvi; to display
 	    hyperlinks. The appropriate parts of the text will be
 	    underlined in blue. You probably want to set this
 	    option.</para>
 	  </listitem>
 	</varlistentry>
+	
+	<varlistentry>
+	  <term><guilabel>Editor for inverse search</guilabel></term>
+	  <listitem>
+	    <para>If you intend to use <ulink
+	    url="inverse-search.html">inverse search</ulink>, 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 NEdit 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 "%f" and "%l" 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 <ulink
+	    url="mailto:kebekus@kde.org">email</ulink> and tell us
+	    about the command line you use and how you have configured
+	    your editor.</para>
+	  </listitem>
+	</varlistentry>
       </variablelist>
 
     </sect1>
@@ -536,64 +568,60 @@
 
 
   <chapter id="faq">
-    <title>Q &amp; A</title>
+    <title>Frequently asked questions</title>
 
     <qandaset>
       <qandaentry>
-	<question>
+	<question id="fontgen">
 	  <para>What happens when &kdvi; displays the message
 	  "Generating bitmap fonts", and why does the procedure take
 	  so long?</para>
 	</question>
 	<answer>
-	  <para>The TeX typesetting system is geared towards highest
+	  <para>Many of the fonts which are typically used in a TeX
-	  quality output, and the same holds for the fonts which are
+	  document must be generated by the MetaFont system. Metafont
-	  used by TeX. </para>
+	  is a language similar to TeX (included in most TeX
+	  distributions) which takes a description of the font
+	  outline, and produces a rasterized version (=
+	  <filename>.pk</filename>-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 roundisch 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
+	  <filename>.pk</filename>-files for a limited time, e.g. 100
+	  days. Therefore, if you access the same document more than
+	  once, the <filename>.pk</filename> files will be
+	  reused.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
-	<question>
+	<question id="MFModes">
-	  <para>What can I do when &kdvi; does not find my
+	  <para>What is a MetaFont Mode?</para>
-	  PK-fonts?</para>
 	</question>
 	<answer>
-	  <para>You must have correct settings for resolution and
+	  <para>In order to produce bitmap fonts which are optimized
-	  <command>Metafont</command> mode. If this does not help, you
+	  for your printer (see the answer to the first question),
-	  may set the field 'PK Font Path' in Preferences/Fonts to
+	  Metafont comes with a database of printing engines --look
-	  point to the list of directories to be searched for
+	  for a file called <filename>modes.mf</filename>. A Metafont
-	  pk-fonts: <userinput><filename
+	  Mode is just the name of a database entry. For example, the
-	  class="directory">/var/lib/texmf/fonts/pk/ljfour/</filename>:<filename
+	  name "ljfour" refers to the entry in the database that
-	  class="directory"><replaceable>/some/other/place</replaceable></filename></userinput>.
+	  describes a Hewlett Packard LaserJet 4 printer. A MetaFont
-	  You can make &kdvi; search recursively by adding an extra /
+	  Mode is usually followed by a number, the resolution. The
-	  at the end of directory name:
+	  LaserJet, for instance canprint in both 300 and 600 dots per
-	  <userinput>/var/lib/texmf/fonts//</userinput> (This works
+	  inch. Thus, "ljfour/600" would be a full description.</para>
-	  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>
 
@@ -608,8 +636,7 @@
     <application>xdvi</application> version 18f which has many
     authors.</para>
 
-    <para>Documentation is copyright 2000, 2001, Markku Hihnala
+    <para>Documentation is copyright 2001, Stefan Kebekus
-    <email>mah@ee.oulu.fi</email> and Stefan Kebekus
     <email>kebekus@kde.org</email></para>
 
     <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
@@ -620,48 +647,6 @@
   </chapter>
 
     
-  <appendix id="installation">
-    <title>Installation</title>
-			    
-    <para>&kghostview; is part of the &kde; 2 project, details of
-    which can be found at <ulink url="http://www.kde.org">
-    http://www.kde.org</ulink>.</para>
-
-    <para>To use &kghostview;, you must have the
-    <application>Ghostscript</application> program as well as &kde; 2
-    installed on your machine. The
-    <application>Ghostscript</application> home page is at
-    <ulink url="http://www.cs.wisc.edu/~ghost/">
-http://www.cs.wisc.edu/~ghost/</ulink></para>
-
-    <para>Most distributions will include &kghostview;, but if you
-    want to roll your own the source code can be found in the
-    Kdegraphics package on <ulink
-    url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>,
-    the main ftp site of the KDE project. </para>
-
-    <para>To see if a later version of &kghostview; has been released,
-    you can take a look in <ulink
-    url="http://apps.kde.com">http://apps.kde.com</ulink>. </para>
-
-    <para>To compile and install &kghostview; on your system, as root
-    type the following in the directory where you saved the
-    &kghostview; source code:</para>
-
-<screen width="40">
-<prompt>%</prompt> <userinput><command>./configure</command></userinput>
-<prompt>%</prompt> <userinput><command>make</command></userinput>
-<prompt>%</prompt> <userinput><command>make</command> <option>install</option></userinput>
-</screen>
-
-<para>
-Since &kghostview; uses <command>autoconf</command> and
-<command>automake</command> you should not have any trouble compiling
-it. But if you do run into problems please report them to the &kde;
-mailing lists.
-</para>
-
-</appendix>
 
 &documentation.index;