Warning, /office/kile/doc/index.docbook is written in an unsupported language. File is not indexed.

 <?xml version="1.0" ?>
 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
   <!ENTITY kile "<application>Kile</application>">
   <!ENTITY latex "L<superscript>A</superscript>T<subscript>E</subscript>X">
   <!ENTITY pdflatex "PDFL<superscript>A</superscript>T<subscript>E</subscript>X">
   <!ENTITY tex "T<subscript>E</subscript>X">
   <!ENTITY tetex "<application>teT<subscript>E</subscript>X</application>">
   <!ENTITY texlive "<application>TeX Live</application>">
   <!ENTITY bibtex "BibT<subscript>E</subscript>X">
   <!ENTITY makeindex "makeindex">
   <!ENTITY kbibtex "KBibT<subscript>E</subscript>X">
   <!ENTITY kbib "KBib">
   <!ENTITY asymptote "Asymptote">
   <!ENTITY imagemagick "<application>ImageMagick</application>">
   <!ENTITY dvipng "<application>dvipng</application>">
   <!ENTITY makeidx "<application>makeidx</application>">
   <!ENTITY cjk "<abbrev>CJK</abbrev>">
   <!ENTITY ucs "<abbrev>ucs</abbrev>">
   <!ENTITY % addindex "IGNORE">
   <!ENTITY % English "INCLUDE">
   <!ENTITY javascript "<application>JavaScript</application>">
   <!ENTITY include-section-scripting SYSTEM "scripting.docbook">
   <!ENTITY include-section-usermenu SYSTEM "usermenu.docbook">
 ]>
 
 <book id="kile" lang="&language;">
 
 <bookinfo>
 <title>The &kile; Handbook</title>
 
 <authorgroup>
         <author><firstname>Jonathan</firstname><surname>Pechta</surname></author>
         <author><firstname>Federico</firstname><surname>Zenith</surname>
         <affiliation><address><email>federico.zenith@member.fsf.org</email></address></affiliation></author>
         <author><firstname>Holger</firstname><surname>Danielsson</surname>
         <affiliation><address><email>holger.danielsson@versanet.de</email></address></affiliation></author>
         <author><firstname>Thomas</firstname><surname>Braun</surname></author>
         <author><firstname>Michel</firstname><surname>Ludwig</surname>
         <affiliation><address><email>michel.ludwig@kdemail.net</email></address></affiliation></author>
         <author><firstname>Felix</firstname><surname>Mauch</surname>
         <affiliation><address><email>felix_mauch@web.de</email></address></affiliation></author>
         <!-- TRANS:ROLES_OF_TRANSLATORS -->
 </authorgroup>
 
 <copyright>
 <year>2003</year>
 <holder>Jonathan Pechta</holder>
 </copyright>
 
 <copyright>
 <year>2003</year><year>2005</year><year>2006</year>
 <holder>Federico Zenith</holder>
 </copyright>
 
 <copyright>
 <year>2005</year><year>2006</year><year>2012</year>
 <holder>Holger Danielsson</holder>
 </copyright>
 
 <copyright>
 <year>2007</year>
 <holder>Thomas Braun</holder>
 </copyright>
 
 <copyright>
 <year>2007</year><year>2011</year>
 <holder>Michel Ludwig</holder>
 </copyright>
 
 <copyright>
 <year>2011</year>
 <holder>Felix Mauch</holder>
 </copyright>
 
 <date>2011-05-22</date>
 <releaseinfo>2.1</releaseinfo>
 
 <legalnotice>
 &FDLNotice;
 </legalnotice>
 
 <abstract>
 <para>
 &kile; is a &tex; and &latex; source editor and shell.
 </para>
 </abstract>
 
 <keywordset>
 <keyword>KDE</keyword>
 <keyword>kdenonbeta</keyword>
 <keyword>Kile</keyword>
 <keyword>LaTeX</keyword>
 <keyword>TeX</keyword>
 </keywordset>
 
 </bookinfo>
 
 <chapter id="preface">
 
 <title>Preface</title>
 
         <sect1 id="preface_sect">
 
                 <title>Requirements</title>
 
                 <para>To run &kile;, you need to have the following components
                 installed on your system:</para>
 
                 <itemizedlist>
                         <listitem><para><ulink url="http://www.kde.org/">K Desktop environment (&kde;)</ulink>:
                         &kde; is a popular open-source desktop environment.</para></listitem>
                         <listitem><para><ulink url="https://qt.io/">&Qt;</ulink>: &Qt; is a C++
                          &GUI; and network library needed to compile &kile;.</para></listitem>
                         <listitem><para><ulink url="http://www.ctan.org/">&latex;</ulink>: high-quality document
                         typesetting program. Most likely you want the &texlive; (or on older systems the &tetex;) package, if you are on a
                         &UNIX;-like system.</para></listitem>
                 </itemizedlist>
 
                 <para>Most of these items might be included in your &Linux; distribution; please refer to your
                 distribution documentation, or refer to your installation &CD; or DVD, for adding these
                 packages to your computer.</para>
 
                 <para>&kile; might also be available as a pre-compiled package for your &Linux; distribution already. Please check with the
                 package manager of your distribution.</para>
 
         </sect1>
 
         <sect1 id="preface_audience">
 
                 <title>Intended Audience</title>
 
                 <para>This manual is intended for any individual, regardless of her or his experience with
                 &latex;, &kde;, &kile; or &Linux;.</para>
 
                 <para>Advanced users are not likely to read this manual, but all suggestions on
                 documentation will be considered. If you would like to contribute to this project or the
                 documentation, please consult the <ulink url="http://kile.sourceforge.net/">&kile; web page</ulink>.</para>
 
                 <para>Do you need answers about &kile;? Are you stuck with the compilation process? Do you want to see a new
                 feature implemented? The preferred way to ask technical questions or to start a discussion is to
                 use our mailing list: <email>kile-devel@lists.sourceforge.net</email>.</para>
 
         </sect1>
 
 </chapter>
 
 <chapter id="introduction">
 
         <title>Introduction</title>
 
         <sect1 id="intro_about">
 
                 <title>Basic facts</title>
 
                 <sect2>
 
                         <title>About &kile;</title>
 
                         <para>&kile; is an integrated &latex; environment for the &kde; desktop. &kile; gives you the
                         ability to use all the functionality of &latex; in a graphical interface, giving you easy,
                         immediate, and customized access to all programs for &latex; code-completion, compiling, postprocessing,
                         debugging, conversion and viewing tools; you also get very handy wizards, a &latex;
                         reference and a powerful project manager.</para>
 
                 </sect2>
 
                 <sect2>
 
                         <title>&kile; and the &kate; Editor Component</title>
 
                         <para>&kile; is based on the &kate; editor component, &ie; a lot of its editing capabilities stem from the &kate;
                         editor component itself. &kile; extends these capabilities with features to edit &latex; documents. To learn more
                         about the &kate; editor component and its capabilities, see the <ulink url="http://kate-editor.org">&kate;
                         webpage</ulink>.</para>
 
                 </sect2>
 
                 <sect2>
 
                         <title>What is &latex;?</title>
 
                         <para>&latex; is a text-processing system derived from &tex;, a program developed originally in
                         1977 by Donald Knuth to help layout text in a professional way and obtain a layout quality that
                         is on a par with the work of a professional typesetter.
                         &latex; was created by Leslie Lamport to give authors an automatic typesetter, especially to ease
                         the expensive and painstaking process of typesetting of mathematical formulas and expressions,
                         which are enclosed within dollar signs in &latex; <emphasis>for a reason</emphasis>.
                         Today, word-processing programs let any user act as typesetter, but what is often needed
                         is a document that simply looks good without having to spend hours to bring it into shape.
                         &latex; takes that burden on its shoulders, and lets you concentrate on the document instead of on the layout.
                         And yes, it <emphasis>will</emphasis> look good!</para>
 
                 </sect2>
 
                 <sect2>
 
                         <title>How do you pronounce it? Why that strange typesetting?</title>
 
                         <para>There is a funny tradition of &tex;-related packages to have the strangest pronunciation
                         and typesetting possible. &tex; was supposed to be brought in from the Greek <emphasis>τεχ</emphasis>,
                         in Latin letters <emphasis>tech</emphasis>. There are a lot of explanations why, but most likely it is because
                         &tex; was originally conceived for technical reports, and indeed its foremost ability was the correct and
                         easy typesetting of mathematical formulae, then an extremely expensive, time-consuming and
                         frustrating business.</para>
                         <para>The pronunciation is supposed to be as follows: <emphasis>T</emphasis> as you would expect,
                         <emphasis>E</emphasis> as in <emphasis>get</emphasis>, and <emphasis>X</emphasis> as in the
                         German i<emphasis>ch</emphasis>. If you do not know what <emphasis>ch</emphasis> sounds like,
                         it is more or less like the sound a hissing cat produces; the IPA symbol is /ç/. Many people report a different pronunciation
                         of <emphasis>ach</emphasis> (IPA symbol /x/), but according to some Greeks, the first version is indeed correct.
                         You should be aware that a lot of people mispronounce &tex; as /teks/ or /tek/.</para>
                         <para>Last, in &latex; the first L<superscript>A</superscript> is pronounced as
                         <emphasis>lay</emphasis>: the idea being, while raw &tex; is difficult, even a <emphasis>lay</emphasis>man
                         can use &latex; macros. A less inspiring, but more realistic explanation is that it stems from the surname of
                         Leslie Lamport, the creator of &latex;. Now you know!</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="intro_latexbasics">
 
                 <title>&latex; 101</title>
 
                 <para>The &latex; typesetting system is similar to other markup languages such as &XML;, which is used in
                 many types of documents (including the one you are reading), or &HTML;, which is used for web
                 pages. The general idea behind markup languages is to have special keywords, called <emphasis>
                 tags</emphasis>, that tell a program (a word processor, a web browser, or the &latex;
                 compiler) how the text enclosed within the tags is to be interpreted. &kile; offers a number of such tags in the
                 <guimenu>LaTeX</guimenu> menu in the menu bar.</para>
 
                 <para>While we will try to give you a good idea of what &latex; is, this document is, of course, not The Definitive
                 Book on &latex;. If you want to learn &latex; in depth, you may want to borrow a specialized book from your local library.</para>
 
                 <para>As with any other markup language, &latex; documents contain a <emphasis>preamble</emphasis>, which
                 defines global properties, such as paper size, page numbering, dimensions of the text on the page,
                 and a document <emphasis>body</emphasis>, which contains the text of the document. The preamble is composed
                 at least of the <userinput>\documentclass</userinput> command. It precedes the document body, which
                 starts with the command <userinput>\begin{document}</userinput> and is concluded with the command
                 <userinput>\end{document}</userinput>.</para>
 
         </sect1>
 
         <sect1 id="intro_mainfeat">
 
                 <title>&kile;'s Main Features</title>
 
                 <sect2 id="intro_docwizard">
 
                         <title>QuickStart Wizard</title>
 
                         <para>The QuickStart wizard built into &kile; is a useful feature to quickly start creating documents
                         in &kile;. Choosing the wizard from the menubar gives you several choices
                         for the creation of your document.
                         You can also specify some options related to the document right away.</para>
 
                         <para>Class options:</para>
 
                         <itemizedlist>
                                 <listitem><para><guilabel>Document Class</guilabel>: choose the type of document you want to create:
                                  article, book, letter, report, scrartcl, scrreprt, scrbook, prosper, beamer or other
                                  custom-defined.</para></listitem>
                                 <listitem><para><guilabel>Typeface Size</guilabel>: tell &kile; what point size (pt)
                                 you want to use.</para></listitem>
                                 <listitem><para><guilabel>Paper Size</guilabel>: choose the size or style of sheets.</para></listitem>
                                 <listitem><para><guilabel>Encoding</guilabel>: In general it is a good idea to use your system's standard
                                                 encoding. Modern systems now move more and more to UTF-8 as the standard encoding.
                                                 If you can, use utf8 or utf8x (which is indeed the correct spelling for &latex; documents).
                                         </para></listitem>
                                 <listitem><para><guilabel>Other options</guilabel>: this allows you to set further options such as printing,
                                 draft, and others.</para></listitem>
                         </itemizedlist>
 
                         <para>Packages</para>
                         <para>This lists some of the most common additional packages used in &latex;. Select the check box to include it.</para>
 
                         <para>Document Properties:</para>
                         <itemizedlist>
                                 <listitem><para><guilabel>Author</guilabel>: put your name here.</para></listitem>
                                 <listitem><para><guilabel>Title</guilabel>: add the document title here.</para></listitem>
                                 <listitem><para><guilabel>Date</guilabel>: specify the date.</para></listitem>
                         </itemizedlist>
 
                 </sect2>
 
                 <sect2 id="intro_templates">
 
                         <title>Predefined Templates</title>
 
                         <para>The predefined templates in &kile; are:</para>
 
                         <itemizedlist>
                                 <listitem><para>Empty document: real freaks start from scratch!</para></listitem>
                                 <listitem><para>Article: sets the article format, for a document short enough not to
                                 be broken down to chapters.</para></listitem>
                                 <listitem><para>Report: sets the report format, for a middle-sized document, with, for
                                 example, page numbering on the page's outer edge.</para></listitem>
                                 <listitem><para>Book: sets the book format, a full-fledged flavor, so powerful that
                                 it is used to write many university textbooks.</para></listitem>
                                 <listitem><para>Letter: sets the letter format.</para></listitem>
                                 <listitem><para>Beamer, HA-Prosper: create nice presentations in PDF with a superior look and all
                                                 &latex; power.</para></listitem>
                                 <listitem><para>Powerdot: Powerdot is the follower of the packages <userinput>seminar</userinput>
                                 and <userinput>HA-Prosper</userinput>. It does not have as many options as Beamer,
                                 but it is easy to use and it can create really nice presentations in PDF.</para></listitem>
                                 <listitem><para>Scrartcl, Scrbook, Scrreprt, Scrlttr2: the KOMA-Script document classes,
                                                 especially adapted to German typography. Use them whenever you write German
                                                 texts.</para></listitem>
                                 <listitem><para>Xelatex: a modified <userinput>Article</userinput> template to use with
                                 <userinput>XeLaTeX</userinput>.</para></listitem>
                         </itemizedlist>
 
                         <para>Note that all of these templates can be adjusted to the user's requirements.</para>
 
                         <para>New users need not worry: this list is just a brief description of the available features,
                         and a more detailed description can be found in <xref linkend="quickstart" role="select: title pageabbrv"/>.</para>
 
                 </sect2>
 
                 <sect2 id="intro_highlight">
 
                         <title>Syntax Highlighting</title>
 
                         <para>&kile; is similar to other programs that deal with source code and editing, and will
                         automatically highlight commands, options and items that are used (and abused).
                         &kile; makes it possible to easily spot problematic areas: for example, if you see major
                         areas of text turn green, it is likely that you forgot to close a math environment somewhere.</para>
 
                 </sect2>
 
                 <sect2 id="intro_autocoml">
 
                         <title>Auto-Completion of Environments</title>
 
                         <para>The auto-completion of environments means that, when you begin a new environment by typing
                         <userinput>\begin{environment}</userinput>, &kile; will automatically insert a matching
                         <userinput>\end{environment}</userinput> command, with a line in between them
                         for your text. You can of course deactivate it if you want in
                         <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                         <guimenuitem>LaTeX</guimenuitem><guilabel>Environments</guilabel></menuchoice>.</para>
 
                 </sect2>
 
                 <sect2 id="intro_jump">
 
                         <title>Jump to Structure Element</title>
 
                         <para>All documents are normally structured in a hierarchy of some type.
                         &latex; allows you to break up documents into the following hierarchy
                         (part being highest in the hierarchy, and subparagraph being lowest):</para>
 
                         <itemizedlist>
                                 <listitem><para>\part</para></listitem>
                                 <listitem><para>\chapter</para></listitem>
                                 <listitem><para>\section</para></listitem>
                                 <listitem><para>\subsection</para></listitem>
                                 <listitem><para>\subsubsection</para></listitem>
                                 <listitem><para>\paragraph</para></listitem>
                                 <listitem><para>\subparagraph</para></listitem>
                         </itemizedlist>
 
                         <para>When viewing a document in the <guilabel>Structure</guilabel> view, you can jump
                         between elements by clicking on the element you would like to view.</para>
 
                 </sect2>
 
                 <sect2 id="intro_inverse">
 
                         <title>Inverse Search</title>
 
                         <para>When creating your own &latex; files, inverse search can be very helpful. Once you
                         have created a &DVI; file (DeVice Independent File) or PDF file, you can click the left
                         mouse button while pressing &Shift; in the viewer and &kile; will jump to the corresponding line in the
                         &latex; source code.</para>
 
                         <para>A &DVI; is a type of file containing a
                         description of a formatted document, along with other
                         information including character font, and is besides PDF the usual output of
                         &tex; or &latex;. A number of utilities exist to view, convert and print &DVI; files on
                         various systems and devices.</para>
 
                 </sect2>
 
                 <sect2 id="intro_forward">
 
                         <title>Forward Search</title>
 
                         <para>When using inverse search, the selection of items in the &DVI; or PDF file is associated with
                         the editor, so when you click on the &DVI; or PDF file, the main window jumps to the
                         corresponding section of &latex; code in the editor. Forward search is the exact
                         opposite of this. Forward search will allow you to click on a specific section of text
                         in the &latex; code, and jump to the associated position in the viewer window.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="intro_toolbar">
 
                 <title>The Toolbar</title>
 
                 <itemizedlist>
                         <listitem><para><guibutton>New</guibutton>: begin a new document.</para></listitem>
                         <listitem><para><guibutton>Open</guibutton>: open a new document.</para></listitem>
                         <listitem><para><guibutton>Close</guibutton>: close your document.</para></listitem>
                         <!-- following toolbar items are different in default master/2.1-->
                         <listitem><para><guibutton>Define document as master</guibutton>: this is used when working with multiple files.
                         Having a master document will let you work more easily with other <literal role="extension">.tex</literal> files included
                         in your document. If you are using projects, you can also set in  <menuchoice><guimenu>Project</guimenu><guisubmenu>Project
                         Options</guisubmenu></menuchoice> a project-wide master document.</para></listitem>
                         <listitem><para><guibutton>Quickbuild</guibutton>: compiles your &latex; source code and displays the results
                         automatically unless there are errors contained in the document.</para></listitem>
                         <listitem><para><guibutton>Watch file mode</guibutton>: this mode will "watch" the &DVI; file for changes, and
                         will not launch a new session of &okular; after <guibutton>Quickbuild</guibutton>.</para></listitem>
                         <listitem><para><guibutton>View logfile</guibutton>: views the <literal role="extension">.log</literal> file,
                                         so you can spot errors.</para></listitem>
                         <listitem><para><guibutton>Previous error</guibutton>: jumps backward through the
                                         <literal role="extension">.log</literal> file
                                         and highlights errors in the source.</para></listitem>
                         <listitem><para><guibutton>Next error</guibutton>: jumps forward through the
                                         <literal role="extension">.log</literal> file and
                         highlights errors in the source.</para></listitem>
                         <listitem><para><guibutton>Stop</guibutton>: halts current tool.</para></listitem>
                         <listitem><para><guibutton>LaTeX</guibutton>: runs &latex; on the active document.</para></listitem>
                         <listitem><para><guibutton>ViewDVI</guibutton>: launches &DVI; viewer.</para></listitem>
                         <listitem><para><guibutton>DVItoPS</guibutton>: converts a &DVI; to a &PostScript; (PS).</para></listitem>
                         <listitem><para><guibutton>ViewPS</guibutton>: launches &PostScript; (PS) viewer.</para></listitem>
                         <listitem><para><guibutton>PDFLaTeX</guibutton>: runs &pdflatex; on the active document.</para></listitem>
                         <listitem><para><guibutton>ViewPDF</guibutton>: launches the PDF viewer.</para></listitem>
                         <listitem><para><guibutton>DVItoPDF</guibutton>: converts a &DVI; to a PDF.</para></listitem>
                         <listitem><para><guibutton>PStoPDF</guibutton>: converts a PS to a PDF.</para></listitem>
                         <listitem><para><guibutton>ViewHTML</guibutton>: views &HTML; created.</para></listitem>
                         <listitem><para><guibutton>ForwardDVI</guibutton>: jump to the page of the &DVI; file that corresponds to the current line in the editor.</para></listitem>
                         <listitem><para><guibutton>ForwardPDF</guibutton>: jump to the page of the PDF file that corresponds to the current line in the editor.</para></listitem>
                 </itemizedlist>
 
                 <para>If you look at the <guilabel>Edit</guilabel> toolbar, you will notice three large
                 drop-down menus. The drop-down menus were designed for you to be able to quickly add
                 certain common features into your document. The first drop down box
                 is used for quickly dividing your document by parts, chapter, sections and so on; the
                 available commands to add segments to your &latex; source code are:</para>
 
                 <itemizedlist>
                         <listitem><para><guilabel>part</guilabel>: highest level of sectioning for a document.</para></listitem>
                         <listitem><para><guilabel>chapter</guilabel>: starts a new chapter.</para></listitem>
                         <listitem><para><guilabel>section</guilabel>: create a new section.</para></listitem>
                         <listitem><para><guilabel>subsection</guilabel>: create a new subsection.</para></listitem>
                         <listitem><para><guilabel>subsubsection</guilabel>: a secondary section between subsection and
                         paragraph.</para></listitem>
                         <listitem><para><guilabel>paragraph</guilabel>: create a new paragraph.</para></listitem>
                         <listitem><para><guilabel>subparagraph</guilabel>: create a new subparagraph.</para></listitem>
                 </itemizedlist>
 
                 <para>The drop down box named <guilabel>Other</guilabel> is used to insert items into your document such as
                 indexes, footnotes, and references; the available commands are:</para>
 
                 <itemizedlist>
                         <listitem><para><guilabel>label</guilabel>: a command that produces a label for a chapter,
                         a figure or another element.</para></listitem>
                         <listitem><para><guilabel>index</guilabel>: creates an entry for the index.</para></listitem>
                         <listitem><para><guilabel>footnote</guilabel>: creates a footnote in your document.</para></listitem>
                         <listitem><para><guilabel>ref</guilabel>: used to refer to a predefined label, which
                         you can choose from a drop-down list.</para></listitem>
                         <listitem><para><guilabel>pageref</guilabel>: just like <guilabel>ref</guilabel>, but refers to
                         a page instead of a structure element.</para></listitem>
                         <listitem><para><guilabel>cite</guilabel>: create a reference with data from a bibliography.</para></listitem>
 <!-- The next feature is currently disabled (see 'kile.cpp'). -->
 <!--                    <listitem><para><guilabel>cite from ViewBib</guilabel>: ask the ViewBib tool for all selected references and insert them.
                         Currently this is only available with <ulink url="http://user.digisurf.com.au/~thachly/kbib/">&kbib;</ulink> as ViewBib tool.</para></listitem>-->
                 </itemizedlist>
 
                 <screenshot>
                         <screeninfo>The <guilabel>Other</guilabel> drop-down menu</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_ref_choose.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>The <guilabel>Other</guilabel> drop-down menu</phrase>
                         </textobject>
                         <caption><para>The <guilabel>Other</guilabel> drop-down menu</para></caption>
                         </mediaobject>
                 </screenshot>
 
                 <screenshot>
                         <screeninfo>Selecting the label for a reference</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_ref_select.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Selecting the label for a reference</phrase>
                         </textobject>
                         <caption><para>Selecting the label for a reference</para></caption>
                         </mediaobject>
                 </screenshot>
 
                 <para>When using <guilabel>cite</guilabel>, you are presented with a drop-down
                 list of bibitems, but if you are using &bibtex; this will only work if the file
                 belongs to a Project. For editing &bibtex; files the usage of specialized editors is recommended.
                 The author has had good results with &kbibtex;. Of course you can also write the &bibtex; files by hand inside &kile;.</para>
 
                 <para>The last drop down box labeled <guilabel>tiny</guilabel> is used to set the size of the text. You can
                 set the size of the main text, of footnotes, and so on. The available commands are:</para>
 
                 <itemizedlist>
                         <listitem><para><guilabel>tiny</guilabel>: smallest.</para></listitem>
                         <listitem><para><guilabel>scriptsize</guilabel>: very small.</para></listitem>
                         <listitem><para><guilabel>footnotesize</guilabel>: smaller.</para></listitem>
                         <listitem><para><guilabel>small</guilabel>: small.</para></listitem>
                         <listitem><para><guilabel>normalsize</guilabel>: normal.</para></listitem>
                         <listitem><para><guilabel>large</guilabel>: large.</para></listitem>
                         <listitem><para><guilabel>Large</guilabel>: larger.</para></listitem>
                         <listitem><para><guilabel>LARGE</guilabel>: even larger.</para></listitem>
                         <listitem><para><guilabel>huge</guilabel>: still larger.</para></listitem>
                         <listitem><para><guilabel>Huge</guilabel>: largest.</para></listitem>
                 </itemizedlist>
 
         </sect1>
 
 </chapter>
 <chapter id="quickstart">
 
         <title>Quickstart</title>
 
         <sect1 id="quick_begin">
 
                 <title>Writing a &latex; Document with &kile; for Beginners</title>
 
                 <para>Users of &kile; have two choices when starting a new document: they can use the
                 <guimenu>Wizard</guimenu> to begin a new document, select the type of document they
                 would like to create and options such as font size, paper size, and so on; otherwise,
                 they can write the code by hand.</para>
 
 <programlisting>\documentclass[12pt]{article}
 \begin{document}
         Here is a bunch of text coded in \LaTeX.
 \end{document}</programlisting>
 
                 <para>Every document in &latex; begins with the command <userinput>
                 \documentclass[optional argument]{class}</userinput>, where class specifies the document type.</para>
 
                 <para>Typing in the code example above from the text box gives you the following output:</para>
 
                 <screenshot>
                         <screeninfo>Compiled text in &DVI; output</screeninfo>
                         <mediaobject>
                                 <imageobject>
                                         <imagedata fileref="latex_example.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                         <phrase>Compiled text in &DVI; output</phrase>
                                 </textobject>
                                 <caption><para>Compiled text in &DVI; output</para></caption>
                         </mediaobject>
                 </screenshot>
 
                 <para>The brackets that come after the command <userinput>\documentclass</userinput>
                 contain the options for the command. The option <userinput>[12pt]</userinput> sets the size
                 of the font for your article; if you do not set the font size in the beginning, you can set
                 it later in the text.</para>
 
                 <para>Once you have typed in the code example from the box above, you will need to
                 compile your &latex; source code. The easiest way for you to compile &latex; is to
                 use the <guimenu>Build</guimenu> menu, or using the <guilabel>Quickbuild</guilabel> button.</para>
 
                 <para><keycombo>&Alt;<keycap>2</keycap></keycombo>
                 is the keyboard shortcut to compile your source code.</para>
 
                 <para>You have to save your source code before you can compile; &kile; will do this automatically for you.</para>
 
                 <para>If your document did not compile, check the log for errors. When using the <guilabel>Quickbuild</guilabel>
                 key, the &okular; viewer should be launched automatically; if it does not, look at the log.</para>
 
         </sect1>
 
         <sect1 id="quick_env">
                 <title>Environments</title>
 
                 <para>An environment is a segment of text that is managed differently
                 from the rest of the document. For example, you create a report with font size 12,
                 but you need to change your font size for a few sentences. The commands
                 <userinput>\begin{environment}</userinput>, <userinput>\huge</userinput> and
                 <userinput>\end{environment}</userinput> will let you temporarily alter the text inside
                 the environment commands to be size huge.</para>
 
                 <para>Changes are only effective from <userinput>\begin{environment}</userinput> to
                 <userinput>\end{environment}</userinput>. There are no limits as to how many changes
                 you can make inside an environment.</para>
 
                 <para>There are many features you can add to your document that will make it more
                 readable and user-friendly. You can add features such as specific fonts, bold, italics,
                 underline &etc; to your document, and these commands will end with either an
                 <userinput>\end</userinput> command, or at the end of your environment.</para>
 
                 <itemizedlist>
                         <listitem><para><userinput>\begin{emph}</userinput>: this command makes
                         text italicized, and is valid until the code comes across a <userinput>\end{emph}</userinput>,
                         or another environment. To italicize one word in a sentence, you
                         can use the syntax: this is <userinput>\emph{my}</userinput> sentence.</para></listitem>
                         <listitem><para><userinput>\textbf{I am making this text inside the brackets bold}</userinput>: this
                         command makes your text bold.</para></listitem>
                         <listitem><para><userinput>\quote</userinput>: to create a quote inside your document; begin your quote
                         with <userinput>\begin{quote}</userinput> and end it with <userinput>\end{quote}</userinput>.</para></listitem>
                         <listitem><para><userinput>\center</userinput>: centers the text.</para></listitem>
                         <listitem><para><userinput>\verse</userinput>: creates offset text for poems.</para></listitem>
                         <listitem><para><userinput>\itemize</userinput>: makes an itemized list.</para></listitem>
                 </itemizedlist>
 
         </sect1>
 
         <sect1 id="quick_using">
 
                 <title>Using &kile;</title>
 
                 <para>Now that we have given you some background about how to write code using the
                 &latex; markup language, we will show you how to create a document
                 using &kile; step-by-step.</para>
 
                 <procedure>
                         <step><para>Start &kile;.</para></step>
                         <step><para>Select <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Quick Start</guimenuitem></menuchoice>,
                         then choose a format, and set your preferences in the wizard.</para></step>
                         <step><para>Once the wizard has entered text, do some customization to make the
                         document more readable, add a minimum of one quote, some bold text,
                         italics, and a verse to see the difference between the commands.</para></step>
                         <step><para>Save your file, and give it the name <filename>intro.tex</filename>.</para></step>
                         <step><para>Build your document using <keycombo>&Alt;<keycap>2</keycap></keycombo>, or the
                         button labeled <guilabel>LaTeX</guilabel>.</para></step>
                         <step><para>Select <guibutton>ViewDVI</guibutton>.</para></step>
                         <step><para>Check out all your new text.</para></step>
                         <step><para>When you are done viewing your document, click the <guibutton>Editor View</guibutton>
                                         button or press <keycombo>&Ctrl;<keycap>E</keycap></keycombo>
                                         to return to the editor if you are using the embedded
                         viewer, or close the viewer window if you are using a separate viewer.</para></step>
                 </procedure>
 
                 <para>That's it! You have just created your first &latex; document!</para>
 
                 <para>Once you have created your &DVI;, you will be able to print your document, or change
                 it into a &PostScript; or PDF file if you want. Experiment and have fun!</para>
 
         </sect1>
 
         <sect1 id="quick_dvi">
 
                 <title>&DVI; Files</title>
 
                 <para>&DVI; stands for <emphasis>DeVice Independent</emphasis> file. These files are produced
                 by &tex; or &latex; to be read by a driver of some sort on your computer. There are many different types of output that
                 a <literal role="extension">.dvi</literal> can be sent to, such as a printer, &PostScript; or PDF file converter, or your computer screen.</para>
 
                 <sect2 id="quick_viewdvi">
 
                         <title>Viewing a &DVI;</title>
 
                         <para>You have already seen how to view a &DVI; file on the screen by using the <guibutton>ViewDVI</guibutton> button in the toolbar.</para>
 
                 </sect2>
 
                 <sect2 id="quick_printdvi">
 
                 <title>Printing a &DVI;</title>
 
                         <para>To print a &DVI;, you can use the same process that you used to create your
                         document earlier (see <xref linkend="quick_using" role="select: title pageabbrv"/>). At step 7, after
                         clicking <guibutton>ViewDVI</guibutton>, select
                         <menuchoice><guimenu>File</guimenu><guimenuitem>Print</guimenuitem></menuchoice>
                         in the viewer, and if you have your printer properly configured, you will be able
                         to print the &DVI;.</para>
 
                 </sect2>
 
                 <sect2 id="quick_exportdvi">
 
                         <title>Converting &DVI; files</title>
 
                         <para>The toolbar gives the options of Converting a &DVI; to other formats. Once you
                         have created a &DVI; from your &latex; source code, you will be able to export it
                         to a format of your choice using the toolbar buttons.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="quick_forward">
 
                 <title>Forward Search between &kile; and &okular;</title>
 
                 <para>The forward search functions allow you to jump from your
                 editor directly to the associated position of the &DVI; or PDF
                 file. </para>
                 <para>&kile; offers a configuration with this option for all &latex; binaries.
                 Go to <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>Tools</guimenuitem><guilabel>Build</guilabel></menuchoice>
                 and always choose the <guilabel>Modern</guilabel> configuration.</para>
 
                 <para>To execute a forward search, position the cursor on a line of source code, and click
                 <guilabel>Forward Search</guilabel> to jump to the associated position
                 in the &DVI; or PDF viewer window.</para>
         </sect1>
 
         <sect1 id="quick_inverse">
 
                 <title>Inverse Search between &kile; and &okular;</title>
 
                 <para>Inverse search is a very useful feature when you are writing
                 a &latex; document yourself. If everything is set up properly, you can
                 click into &okular;'s window with the <mousebutton>left</mousebutton> mouse button while pressing &Shift;. After that &kile; loads the &latex; source file and jumps to
                 the proper paragraph. To use inverse search, you have to compile your &latex; file with the <guilabel>Modern</guilabel> configuration.</para>
 
                 <para>Inverse search cannot work unless:</para>
 
                 <itemizedlist>
                         <listitem><para>The source file has been compiled successfully.</para></listitem>
                         <listitem><para>&okular; knows which editor you would like to use.</para></listitem>
                 </itemizedlist>
 
                 <para>With this feature of &okular;, a left mouse click while pressing &Shift; in the &DVI; or PDF document will
                 result in &kile; opening the corresponding &latex; document and attempt to go to the
                 corresponding line. Remember to tell &okular; to use &kile; as a text editor, in &okular;'s
                 menu item <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Okular...</guimenuitem></menuchoice>
                 (on the page <guimenuitem>Editor</guimenuitem>).</para>
 
                 <screenshot>
                         <screeninfo>Configuring &okular;</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_okular_settings.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Configuring &okular;</phrase>
                         </textobject>
                         <caption><para>Configuring &okular;</para></caption>
                         </mediaobject>
                 </screenshot>
         </sect1>
 
         <sect1 id="quick_errors">
 
                 <title>Resolving Errors</title>
 
                 <para>If you are trying to use quickbuild, and the &DVI; viewer does not open, chances are
                 you have an error. If you have an error, it will be visible in the log file / message area,
                 and the summary of the error will be given.</para>
 
                 <para>The log file will explain the source of the error in your code. In the
                 editor, you can use the buttons in the toolbar labeled <guibutton>Previous LaTeX Error</guibutton>
                 and <guibutton>Next LaTeX Error</guibutton> to jump to and from errors. The log file always states
                 in which line the error occurred. To view the line where an error occurred, click on the error
                 in the log window, and &kile; will take you to the error's line.</para>
 
         </sect1>
 
 </chapter>
 <chapter id="startnew">
 
         <title>Starting a New Document</title>
 
         <para>When you click the button in the toolbar to begin a new document a dialog appears,
         asking which type of template you would like to use to write your document. The
         default choices are:</para>
 
         <itemizedlist>
                 <listitem><para>Empty document</para></listitem>
                 <listitem><para>Article</para></listitem>
                 <listitem><para>Beamer</para></listitem>
                 <listitem><para>Book</para></listitem>
                 <listitem><para>HA-Prosper</para></listitem>
                 <listitem><para>Powerdot</para></listitem>
                 <listitem><para>Letter</para></listitem>
                 <listitem><para>Report</para></listitem>
                 <listitem><para>Scrartcl (from the KOMA-Script package)</para></listitem>
                 <listitem><para>Scrbook (from the KOMA-Script package)</para></listitem>
                 <listitem><para>Scrlttr2 (from the KOMA-Script package)</para></listitem>
                 <listitem><para>Scrreprt (from the KOMA-Script package)</para></listitem>
                 <listitem><para>PDF</para></listitem>
                 <listitem><para>XeLaTeX</para></listitem>
         </itemizedlist>
 
         <para>If you selected an <guilabel>Empty document</guilabel>, you can either start
         writing a document from scratch, or you can use the wizard to quickly start a new
         document (see <xref linkend="intro_docwizard" role="select: title pageabbrv"/>).</para>
 
 
         <sect1 id="startnew_templates">
 
                 <title>Templates</title>
 
                 <para>Frequent users of &latex; typically use the same preamble for almost every document they use.
                 Templates can be created, saved and loaded within &kile; to make it easier to start a new document.</para>
 
 
                 <sect2>
                         <title>Create a New Template</title>
 
                         <para>To create a new template, you must first either open a &tex; / &latex; file, or create a file
                         of your own. &kile; can generate a template from an existing document by opening the desired document and selecting
                         <menuchoice><guimenu>File</guimenu><guimenuitem>Create Template from Document</guimenuitem></menuchoice>.</para>
 
                 </sect2>
 
                 <sect2>
 
                         <title>Configuring Automatic Substitutions</title>
 
                         <para>When creating a new document by selecting a template from
                         <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>,
                         certain character combinations will be replaced by data such as your name,
                         or the character encoding you are using. These variables can be configured in
                         <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                         <guimenuitem>Settings</guimenuitem><guilabel>General</guilabel></menuchoice>.</para>
 
                         <para>When designing your own template, it is useful to know which character
                         combinations are replaced by which template variables:</para>
 
                         <itemizedlist>
                                 <listitem><para><userinput>$$AUTHOR$$</userinput>: This string
                                 will be replaced by the author variable.</para></listitem>
                                 <listitem><para><userinput>$$DOCUMENTCLASSOPTIONS$$</userinput>: This string will be replaced
                                 by the documentclass options variable. Typically this is used as follows:
                                 <userinput>\documentclass[$$DOCUMENTCLASSOPTIONS$$]{article}</userinput>.</para></listitem>
                                 <listitem><para><userinput>$$INPUTENCODING$$</userinput>: If the
                                 inputencoding variable is set to, say, <userinput>latin1</userinput> this string is replaced by
                                 <userinput>\input[latin1]{inputenc}</userinput>.</para></listitem>
                         </itemizedlist>
 
                 </sect2>
 
                 <sect2 id="templ_wiz">
 
                         <title>Create a Template from the Wizard</title>
 
                         <para>The easiest way to create a new template is to start the wizard,
                         and then add commands in the editor. Once you have your
                         document set up the way you like:</para>
 
                         <procedure>
                                 <step><para>Save your file;</para></step>
                                 <step><para>Go to <guimenu>File</guimenu>;</para></step>
                                 <step><para>Choose <guimenuitem>Create Template from Document</guimenuitem>;</para></step>
                                 <step><para>Make any corrections necessary to the template;</para></step>
                                 <step><para>Enter a name for your new template;</para></step>
                                 <step><para>Click <guibutton>OK</guibutton> to add your template to the menu.</para></step>
                         </procedure>
 
                         <para>Next time you start up a new document, you will be able to choose
                         your customized template instead of the default ones.</para>
 
                 </sect2>
 
                 <sect2>
 
                         <title>Creating a Template from any File</title>
 
                         <para>A template can be created from any &latex; file. If you are looking for an easy way to
                         configure a template, go find one you like on the Internet and follow the same steps as
                         listed in <xref linkend="templ_wiz" role="select: title pageabbrv"/>.</para>
 
                         <para>For instance, you may want to create a full-fledged A0 poster. These posters are usually seen
                         at scientific conferences, and &latex; will help you make an attractive, catchy poster. Remember that you will need the <filename>a0poster</filename>
                         package, which is normally not included in standard &tex; distributions. Download it from
                         <ulink url="http://www.ctan.org/tex-archive/macros/latex/contrib/a0poster/">here</ulink> and place it in the same folder as your &latex; file.</para>
                 </sect2>
 
                  <sect2 id="templ_rem">
 
                         <title>Removing a Template</title>
 
                         <para>To remove a template from &kile;, do as follows:</para>
 
                         <procedure>
                                 <step><para>Go to <menuchoice><guimenu>File</guimenu><guimenuitem>Remove
                                 Template...</guimenuitem></menuchoice>;</para></step>
                                 <step><para>A dialog box will appear with all templates listed: select a template;</para></step>
                                 <step><para>Click <guilabel>OK</guilabel>, and your template will be removed.</para></step>
                         </procedure>
 
                         <para>Templates marked with an asterisk (*) cannot be removed without the proper permission.</para>
 
                 </sect2>
 
         </sect1>
 
 </chapter>
 <chapter id="editing">
 
         <title>Editing &latex; Documents</title>
 
         <para>The internal editor that &kile; uses is &kate;.
         &kate; is a text editor created for programmers, which incorporates the ability to read
         and highlight many different types of text files, among which are &latex; and &bibtex;; you can access
         many options for &kate; directly from &kile;'s <guimenu>Tools</guimenu> menu.</para>
 
          <para>To learn more about &kate; and its capabilities, see the <ulink url="help:/kate">&kate; Handbook</ulink>.
         &kile; users can start reading from the chapter <quote>Working with the &kate; Editor</quote>.</para>
 
          <sect1 id="editing_sect">
 
                 <title>The &latex; Reference</title>
 
                 <para>&kile; features a very practical &latex; tag reference, which you can access
                 by choosing <menuchoice><guimenu>Help</guimenu><guimenuitem>LaTeX
                 Reference</guimenuitem></menuchoice>. It contains a thorough description
                 of almost all the commands that you may use in &latex; and their syntax.</para>
 
         </sect1>
 
         <sect1 id="editing_cursor">
 
                 <title>Cursor Movements</title>
 
                 <para>To select text, you have the following options:</para>
 
                 <itemizedlist>
                         <listitem><para>Hold left mouse button, and drag mouse to highlight text.</para></listitem>
                         <listitem><para>Click once on a word to move the cursor to a new area.</para></listitem>
                         <listitem><para>Click twice on a word to select the whole word.</para></listitem>
                         <listitem><para>Click twice on a word and pressing <keycombo>&Ctrl;</keycombo> to select the whole &tex; word.
       This means clicking in this way on <userinput>\par</userinput> from <userinput>\par\bigskip</userinput> only select \par.</para></listitem>
                         <listitem><para>Click three times to select the whole sentence.</para></listitem>
                 </itemizedlist>
 
                 <para>Holding the left mouse button, and dragging the text you want to select,
                 automatically copies the selected text to the clipboard.</para>
 
                 <para>Holding &Shift; and using the arrow keys allows you to select portions of the source
                 code in the editor window.</para>
 
         </sect1>
 
         <sect1 id="editing_bracket">
 
                 <title>Brackets</title>
 
                 <para>Bracket completion is a visual tool that the editor view uses to indicate to you
                 which bracket matches which. If you open any <literal role="extension">.tex</literal> file,
                 and select any bracket, whether it be a parenthesis (), square brackets [] or braces {}, the
                 editor will highlight the bracket and its match in yellow (this default color can be changed).
                 So, for example, if you position the cursor on the braces in
                 <userinput>\section{Introduction}</userinput>, you would see
                 <userinput>\section{Introduction}</userinput> in the default yellow highlight,
                 showing you the location of the beginning and ending brackets.</para>
 
         </sect1>
 
         <sect1 id="editing_highlight">
 
                 <title>Highlighting</title>
 
                 <para>&kile; has the ability to look for and highlight different types of code. For example, &latex; commands
                         are distinguished from normal text, and math formulas are also highlighted in a different color.</para>
 
         </sect1>
 
         <sect1 id="editing_bullets">
 
                 <title>Bullets</title>
 
                 <para>Many wizards can insert optional bullets, a special kind of bookmark within the text. The
                 menu entries <menuchoice><guimenu>Edit</guimenu><guisubmenu>Bullets</guisubmenu></menuchoice> or
                 the corresponding keyboard shortcuts will allow you to jump to the next or last bullet.
                 This will also highlight this bullet so that it will be deleted automatically,
                 when you enter your first letter.</para>
 
                 <screenshot>
                         <screeninfo>Bullets</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="bullets.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Bullets</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <variablelist>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>Right</keycap></keycombo></shortcut>
                 <guimenuitem>Next Bullet</guimenuitem></menuchoice></term>
                 <listitem><para>Jump to the next bullet in the text if there is one.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>Left</keycap></keycombo></shortcut>
                 <guimenuitem>Last Bullet</guimenuitem></menuchoice></term>
                 <listitem><para>Jump to the previous bullet in the text if there is one.</para></listitem>
                 </varlistentry>
 
                 </variablelist>
 
         </sect1>
 
         <sect1 id="editing_select">
 
                 <title>Select</title>
 
                 <para>Editing is of course one of the main aspects when you use a program like &kile;.
                 Although &kate; already has great capabilities, &kile; adds some important features,
                 which are especially needed to write &latex; source. &latex; always needs a lot of
                 environments and groups, so &kile; supports very special commands to select them.
                 Under <menuchoice><guimenu>Edit</guimenu><guisubmenu>Select</guisubmenu></menuchoice>
                 you will find the following commands to select text.</para>
 
                 <screenshot>
                         <screeninfo>Edit->Select items</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="select.png" format="PNG" />
                         </imageobject>
                         <textobject>
                                 <phrase>Edit->Select items</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <variablelist>
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                 <keycap>,E</keycap></shortcut>
                 <guimenuitem>Environment (inside)</guimenuitem></menuchoice></term>
                 <listitem><para>Select an environment
                 without the surrounding tags. If this command is called, when an environment
                 is already selected, &kile; will expand the selection to the next surrounding
                 environment.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                 <keycap>,F</keycap></shortcut>
                 <guimenuitem>Environment (outside)</guimenuitem></menuchoice></term>
                 <listitem><para>Select an environment
                 including the surrounding tags. This selection can also be expanded with a
                 second call of this command. </para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                 <keycap>,T</keycap></shortcut>
                 <guimenuitem>TeX Group (inside)</guimenuitem></menuchoice></term>
                 <listitem><para>Select a &tex; group
                 inside the surrounding braces.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                 <keycap>,U</keycap></shortcut>
                 <guimenuitem>TeX Group (outside)</guimenuitem></menuchoice></term>
                 <listitem><para>Select a &tex; group
                 including the surrounding braces.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                                         <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                                                 <keycap>,M</keycap></shortcut>
                                         <guimenuitem>Math Group</guimenuitem></menuchoice></term>
                         <listitem><para>Select the current math group including the math commands.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                 <keycap>,P</keycap></shortcut>
                 <guimenuitem>Paragraph</guimenuitem></menuchoice></term>
                 <listitem><para>Select a whole paragraph,
                 &ie; a group of text lines separated on both sides by empty lines.
                 A paragraph does not mean just continuous lines of text, as it is
                 in other text editors. This extended meaning also includes tables, &latex;
                 commands and all other lines of source. The only important thing for &kile;
                 is that this kind of paragraph is separated by two empty lines.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                 <keycap>,L</keycap></shortcut>
                 <guimenuitem>Line</guimenuitem></menuchoice></term>
                 <listitem><para>Select the text line of the
                 current cursor position.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
                 <keycap>,W</keycap></shortcut>
                 <guimenuitem>TeX Word</guimenuitem></menuchoice></term>
                 <listitem><para>Select the word under
                 the current cursor position. This selection has also en extended meaning,
                 because this command can also select &latex; commands, which begin with a
                 backslash and may also have an optional star at the
                 end.</para></listitem>
                 </varlistentry>
 
                 </variablelist>
 
                 <sect2 id="editing_select_latex_commands">
 
                 <title>Select &latex; commands</title>
 
                 <para>&kile; has an extended feature to select &latex; commands. If you for example
                 have typed</para>
 
                 <programlisting>text \bfseries\itshape more text</programlisting>
 
                 <para> and double click on one of the &latex; commands, both will be selected.
                 But often you only want to select one of two or more commands. This can be done using
                 the <keycombo>&Ctrl;</keycombo> key. You only have to press the <keycombo>&Ctrl;</keycombo> key
                 and a double click will only select the desired command.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="editing_delete">
 
                 <title>Delete</title>
 
                 <para>To delete some parts of a document you can of course select them, and then
                 use the <keycombo><keycap>Delete</keycap></keycombo> key. &kate; also offers the command
                 <keycombo>&Ctrl;<keycap>K</keycap></keycombo> which deletes the whole line. But &kile; offers a
                 faster way with its own delete commands.
                 Under <menuchoice><guimenu>Edit</guimenu><guisubmenu>Delete</guisubmenu></menuchoice>
                 you will find the following commands to delete text.</para>
 
                 <screenshot>
                         <screeninfo>Edit->Delete items</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="delete.png" format="PNG" />
                         </imageobject>
                         <textobject>
                                 <phrase>Edit->Delete items</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <variablelist>
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                 <keycap>,E</keycap></shortcut>
                 <guimenuitem>Environment (inside)</guimenuitem></menuchoice></term>
                 <listitem><para>Delete an environment without the surrounding tags.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                 <keycap>,F</keycap></shortcut>
                 <guimenuitem>Environment (outside)</guimenuitem></menuchoice></term>
                 <listitem><para>Delete an environment including the surrounding tags.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                 <keycap>,T</keycap></shortcut>
                 <guimenuitem>TeX Group (inside)</guimenuitem></menuchoice></term>
                 <listitem><para>Delete a &tex; group inside the surrounding braces.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                 <keycap>,U</keycap></shortcut>
                 <guimenuitem>TeX Group (outside)</guimenuitem></menuchoice></term>
                 <listitem><para>Delete a &tex; group including the surrounding braces.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                                         <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                                                 <keycap>,M</keycap></shortcut>
                                         <guimenuitem>Math Group</guimenuitem></menuchoice></term>
                         <listitem><para>Delete the current math group including the math commands.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                 <keycap>,P</keycap></shortcut>
                 <guimenuitem>Paragraph</guimenuitem></menuchoice></term>
                 <listitem><para>Delete a whole paragraph. Look at the
                 <menuchoice><guisubmenu>Select</guisubmenu><guimenuitem>Paragraph</guimenuitem></menuchoice>
                 command, how a paragraph is
                 defined in &kile;.</para></listitem>
                 </varlistentry>
 
 
                 <varlistentry><term><menuchoice>
                                         <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                                                 <keycap>,I</keycap></shortcut>
                                         <guimenuitem>To End of Line</guimenuitem></menuchoice></term>
                         <listitem><para>Delete the text from the current cursor position to the end of the line.
                                 </para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
                 <keycap>,W</keycap></shortcut>
                 <guimenuitem>TeX Word</guimenuitem></menuchoice></term>
                 <listitem><para>Delete the word or &latex;
                  command under the current cursor position.</para></listitem>
                 </varlistentry>
 
                 </variablelist>
 
         </sect1>
 
         <sect1 id="editing_environment">
 
                 <title>Environment</title>
 
                 <para>It has already been mentioned that environments are a central point in &latex;.
                 So &kile; offers five other commands to make the work with &latex; as easy as possible
                 under submenus <menuchoice><guimenu>Edit</guimenu><guisubmenu>Environment</guisubmenu></menuchoice>.</para>
 
                 <screenshot>
                         <screeninfo>Edit->Environment items</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="environment.png" format="PNG" />
                         </imageobject>
                         <textobject>
                                 <phrase>Edit->Environment items</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <variablelist>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
                 <keycap>,B</keycap></shortcut>
                 <guimenuitem>Go to Begin</guimenuitem></menuchoice></term>
                 <listitem><para>This command will jump to the beginning of the current environment,
                 wherever your current position is. The cursor will be placed directly
                 in front of the opening environment tag.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
                 <keycap>,E</keycap></shortcut>
                 <guimenuitem>Go to End</guimenuitem></menuchoice></term>
                 <listitem><para>This command will jump to the end of the current environment,
                 wherever your current position is. The cursor will be placed directly
                 behind the closing environment tag.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
                 <keycap>,M</keycap></shortcut>
                 <guimenuitem>Match</guimenuitem></menuchoice></term>
                 <listitem><para>When your cursor is placed in front of or above the
                 <userinput>\begin{environment}</userinput> tag, it will be moved to the
                 opposite end of the environment and vice versa.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
                 <keycap>,C</keycap></shortcut>
                 <guimenuitem>Close</guimenuitem></menuchoice></term>
                 <listitem><para>Typing a lot of nested environment tags, you may lose
                 control of all those environments. This command will close the last
                 opened environment, so that the nested structure of environments
                 will not be broken.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                                         <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
                                                 <keycap>,A</keycap></shortcut>
                                         <guimenuitem>Close All</guimenuitem></menuchoice></term>
                         <listitem><para>This closes all open environments, not only the last opened environment.</para></listitem>
                 </varlistentry>
 
                 </variablelist>
 
         </sect1>
 
         <sect1 id="editing_texgroup">
 
                 <title>&tex; Group</title>
 
                 <para>&kile; also offers some special commands for &latex; groups,
                 which are determined by braces <userinput>{...}</userinput>. In submenu
                 <menuchoice><guimenu>Edit</guimenu><guisubmenu>TeX Group</guisubmenu></menuchoice>
                 you will find some important commands, which correspond to those from
                 <menuchoice><guimenu>Edit</guimenu><guisubmenu>Environment</guisubmenu></menuchoice>.
                 </para>
 
                 <screenshot>
                         <screeninfo>Edit->TeX Group</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="texgroup.png" format="PNG" />
                         </imageobject>
                         <textobject>
                                 <phrase>Edit->TeX Group</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <variablelist>
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
                 <keycap>,B</keycap></shortcut>
                 <guimenuitem>Go to Begin</guimenuitem></menuchoice></term>
                 <listitem><para>This command will jump to the beginning of the current group,
                 wherever your current position is. The cursor will be placed directly in front
                 of the opening brace.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
                 <keycap>,E</keycap></shortcut>
                 <guimenuitem>Go to End</guimenuitem></menuchoice></term>
                 <listitem><para>This command will jump to the end of the current group,
                 wherever your current position is. The cursor will be placed directly
                 behind the closing brace.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
                 <keycap>,M</keycap></shortcut>
                 <guimenuitem>Match</guimenuitem></menuchoice></term>
                 <listitem><para>When your cursor is placed in front of or behind an
                 opening brace of a &tex; group, it will be moved to the opposite end of
                 the group and vice versa.</para></listitem>
                 </varlistentry>
 
                 <varlistentry><term><menuchoice>
                 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
                 <keycap>,C</keycap></shortcut>
                 <guimenuitem>Close</guimenuitem></menuchoice></term>
                 <listitem><para>Typing a lot of nested group braces may be hard work.
                 This command will close the last opened group, so that the nested
                 structure of &tex; groups will not be broken.</para></listitem>
                 </varlistentry>
 
                 </variablelist>
 
         </sect1>
 
         <sect1 id="editing_dblquotes">
 
                 <title>Double Quotes</title>
 
                 <para>In &latex;, two single quotes are used as double quotes. To
                 help you insert these efficiently, &kile; allows you to press
                 <keycap>"</keycap> to insert two opening
                 single quotes. Furthermore, if you want to close a quotation, you also
                 have to press <keycap>"</keycap>. &kile; will
                 be smart enough to recognize this situation and inserts two closing quotes
                 for &latex;.</para>
 
                 <para>To get a literal double quote on the other side, press
                 <keycap>"</keycap> twice.</para>
 
                 <para>You can enable or disable this auto insertion of opening and
                 closing double quotes in section
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
                 Kile...</guisubmenu><guimenuitem>LaTeX</guimenuitem></menuchoice>.</para>
 
                 <screenshot>
                         <screeninfo>Double Quotes</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="config-dblquotes.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Double Quotes</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>If you also include language-specific options
                 like <userinput>ngerman</userinput> or <userinput>french</userinput>,
                 you will also be able to use German or French double quotes. Many more languages are available.
     </para>
 
         </sect1>
 
         <sect1 id="editing_smartnewline">
 
                 <title>Smart Newline</title>
 
                 <para>If you press <keycombo>&Ctrl;<keycap>Return</keycap></keycombo>,
                 &kile; inserts an intelligent newline. If your current position
                 is inside a list environment, like <userinput>enumerate</userinput>
                 or <userinput>itemize</userinput>, &kile; will not only insert
                 a newline, but also add a <userinput>\item</userinput> command.</para>
 
                 <para>If you are inside a tabular environment, &kile; will finish the
                 current line with <userinput>\\</userinput>, followed by the newline.</para>
 
     <para>If you are inside a &latex; comment, &kile; will start the next line with a
     <userinput>%</userinput>.</para>
 
                 <para>Even better, &kile; is smart enough to support predefined &latex;
                 and user defined environments, which can be added in section
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
                 Kile...</guisubmenu><guimenuitem>LaTeX</guimenuitem></menuchoice>.</para>
 
         </sect1>
 
         <sect1 id="editing_tabulator">
 
                 <title>Smart Tabulator</title>
 
                 <para>Some users like to arrange columns in tabular environments and
                 put all ampersand characters <keycap>&amp;</keycap> beneath each other. &kile; tries
                 to support this. If you press <keycombo>&Alt;&Shift;<keycap>&amp;</keycap></keycombo>,
                 &kile; will look for the next tab in the row above. Although this tab may not be the
                 corresponding tab, &kile; will add some spaces to adjust the column position with
                 the current tab.</para>
 
         </sect1>
 
 </chapter>
 
 <chapter id="completion">
 
         <title>Code Completion</title>
 
         <para>Although &kate; already offers a good completion mode, &kile; extends
         code completion to support some special methods especially for &latex;. Five different
         modes are integrated. Three of them work on demand, the other two are autocompletion
         modes. All modes can be configured to work very differently at
         <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Kile...</guimenuitem></menuchoice>.</para>
 
         <sect1 id="complete_autoenvironment">
 
                 <title>Automatic Environment Completion</title>
 
                 <para>When you begin a new environment, typing <userinput>\begin{environment}</userinput>,
                 &kile; will automatically add an <userinput>\end{environment}</userinput> command, with a
                 line in between for your text.</para>
 
                 <para>Autocompletion can be turned off in the &latex; section of
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>LaTeX</guimenuitem><guilabel>Environments</guilabel></menuchoice>.</para>
 
                 <screenshot>
                         <screeninfo>Completing an Equation Environment</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_autocomplete.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Completing an Equation Environment</phrase>
                         </textobject>
                         <caption><para>Completing an Equation Environment</para></caption>
                         </mediaobject>
                 </screenshot>
 
         </sect1>
 
         <sect1 id="complete_command">
 
                 <title>&latex; Commands</title>
 
                 <para>When you type some letters, you can activate this completion mode for &latex; commands
                 and normal words with <menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>(La)TeX Command</guimenuitem></menuchoice> or the keyboard shortcut
                 <keycombo>&Ctrl;&Shift;<keycap>Space</keycap></keycombo>.
                 &kile; first reads the letters from the current cursor position to the
                 left and stops at the first non-letter character or a backslash. If this
                 pattern begins with a backslash, &kile; will enter completion mode for &tex; or &latex;
                 commands. Otherwise it enters normal dictionary mode, where you will not find any
                 &latex; commands. Depending on the chosen mode, a completion box will be opened.
                 You will see all commands or words whose beginning matches the current pattern.
                 You can navigate with the cursor keys through this list and select one entry with
                 &Enter; or a double click with the mouse.</para>
 
                 <screenshot>
                         <screeninfo>Completing a LaTeX Command</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="complete_cmd1.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Completing a LaTeX Command</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>When you push the &Backspace; key, the last letter of your
                 pattern will be deleted, and the completion list may grow. On the other hand, if
                 you type another letter it will expand the pattern and the
                 visible word list may shrink.</para>
 
                 <para>If you decide not to select any of the suggestions, you can leave this
                 dialog with &Esc;.</para>
 
                 <para>You will see that all commands are written with a short description of
                 their parameters. These descriptions are of course stripped when you select a command.
                 Optionally you can let &kile; insert bullets at these places, so that you can easily
                 jump to these positions with <menuchoice><guimenu>Edit</guimenu><guisubmenu>Bullets</guisubmenu><guimenuitem>Next Bullet</guimenuitem></menuchoice>
                 and insert the parameter you want.</para>
 
                 <screenshot>
                         <screeninfo>Completing a LaTeX Command</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="complete_cmd2.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Completing a LaTeX Command</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>Go to
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
                 to configure one or more of these lists. You can choose different word lists
                 for &tex; and &latex; commands and dictionary mode for normal words.</para>
 
                 <para>If you choose the option <guimenuitem>Show Latex commands</guimenuitem>,
                 the entries of all chosen compressed word list (cwl) files for &latex; command completion are shown in a
                 separate view of &kile;'s sidebar. You will see
                 which commands are available and what parameters and options must or can be
                 given for a completion. You can also simply select one entry with a mouse click
                 and it will be inserted into the document, with all named parameters and
                 options stripped.</para>
 
                 <screenshot>
                         <screeninfo>LaTeX commands in the sidebar</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="command-view.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>LaTeX commands in the sidebar</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>As each chosen word list will be shown in a separate view of its own,
                 there could be too many views, so that &kile;'s main window may be larger
                 than a small screen allows. As this looks very ugly, &kile; works with a maximum
                 number of allowed views, which by default is set to 10. If this value is too big
                 for your screen, you should reduce it.</para>
 
         </sect1>
 
         <sect1 id="complete_environment">
 
                 <title>Environments</title>
 
                 <para>The <emphasis>command mode</emphasis> is not useful for code completion of environments.
                 You always have to type some letters of <userinput>\begin</userinput>, and invoking
                 the completion mode will result in a huge list of environment tags. On the other
                 hand, environments are so often used that &kile; offers a special mode for code completion of
                 environments. Forget the opening tag and write, for example, <userinput>al</userinput>.</para>
 
                 <para>When you call the completion mode with
                 <menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>Environment</guimenuitem></menuchoice> or keyboard shortcut <keycombo>&Alt;&Shift;<keycap>Space</keycap></keycombo>,
                 the opening tag is automatically added and you will see <userinput>\begin{al}</userinput>.
                 After this change, the completion list is much less cluttered.</para>
 
                 <screenshot>
                         <screeninfo>Completing a LaTeX Command</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="complete_env1.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Completing a LaTeX Command</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>Now select an environment, and you will see that it is also automatically closed.
                 Even more, if &kile; recognizes it as a list environment, it will also insert a first
                 <userinput>\item</userinput> tag.</para>
 
                 <screenshot>
                         <screeninfo>Completing a LaTeX Command</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="complete_env2.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Completing a LaTeX Command</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>Go to
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
                 to configure one or more of these lists. This mode uses the same word lists as the
                 completion mode for &tex; and &latex; commands.</para>
 
         </sect1>
 
         <sect1 id="complete_abbreviation">
 
                 <title>Abbreviations</title>
 
                 <para>&kile; supports user defined lists of abbreviations, which are replaced
                 on demand by longer text strings. Look at
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
                 to configure one or more of these lists. For the example given here, the
                 abbreviation list in <filename>example.cwl</filename> must be chosen.
                 In this file you will find, for example, the entry <userinput>L=\LaTeX</userinput>.</para>
 
                 <para>For example, type only the letter <userinput>L</userinput>. Now invoke
                 the abbreviation mode of word completion with
                 <menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>Abbreviation</guimenuitem></menuchoice> or keyboard shortcut <keycombo>&Ctrl;&Alt;<keycap>Space</keycap></keycombo>,
                 and the letter <userinput>L</userinput> is replaced by the string
                 <userinput>\LaTeX</userinput>.</para>
 
                 <para>Abbreviation completion also supports newline <userinput>%n</userinput> and <userinput>%C</userinput>
                 to place the cursor, if these characters are present in the expansion text.
                 So if you have the entry</para>
 
                 <programlisting>en1=\begin{enumerate}%n\item %C%n\end{enumerate}%n</programlisting>
 
                 <para>in the completion file, and invoke the abbreviation completion,
                 the expansion looks as below, where <userinput>x</userinput> shows the final cursor position.</para>
 
 <programlisting>\begin{enumerate}
         \item x
 \end{enumerate}</programlisting>
 
                 <sect2 id="complete_abbrev_view">
 
                         <title>Abbreviations</title>
 
                         <para>If you choose <guimenuitem>Show abbreviations</guimenuitem>, all possible
                         abbreviations are shown in a view of the sidebar. So you will have a good survey
                         of all possible abbreviations.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="complete_auto">
 
                 <title>Autocompletion Modes</title>
 
                 <sect2 id="complete_autolatex">
 
                         <title>&latex; Commands</title>
 
                         <para>You can also enable an autocompletion mode for &latex; commands.
                         When a given threshold of letters (default: 3) is entered, a popup window opens
                         with a list of all matching &latex; commands. You can select one of these commands,
                         or ignore this window and type further letters. The entries of the completion box
                         will always change and match your currently typed word.</para>
 
                         <para>Go to
                         <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                         <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
                         to enable or disable this mode or to change the threshold.</para>
 
                 <screenshot>
                         <screeninfo>Completing an Equation Environment</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="config-complete.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Completing an Equation Environment</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 </sect2>
 
                 <sect2 id="complete_autotext">
 
                         <title>Document Words</title>
 
                         <para>Large dictionaries are not useful in autocompletion mode. But, we have seen
                         that a lot of words in a document are typed more than once. So &kile; offers a
                         completion for all words from the document that the user has already typed.
                         You can manually invoke this completion, if you press
                         <keycombo>&Ctrl;<keycap>Space</keycap></keycombo>. Note that
                         this mode is different from the completion mode for &latex; commands.</para>
 
                         <para>If you want to turn this mode on or off, go to
                         <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                         <guimenuitem>Editor</guimenuitem><guimenuitem>Editing</guimenuitem><guilabel>Auto Completion</guilabel></menuchoice>.
                         In this dialog you can configure if completion mode for
                         document words should be enabled. There is also an additional autocompletion mode,
                         where a completion box pops up, when a certain threshold is reached.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="complete_own_files">
 
                 <title>Writing Own Completion Files</title>
 
     <para>The latest specification of the completion file format can found in the
                 <ulink url="https://commits.kde.org/kile?path=README.cwl">
                 CWL file format specification</ulink>.
                 </para>
 
                 <para>
                 Completion files can be installed in a user's home folder under the <filename>~/.kde/share/apps/kile/complete/&lt;mode&gt;/</filename>
                 subdirectory, where <parameter>&lt;mode&gt;</parameter> either stands for <constant>abbreviation</constant>, <constant>dictionary</constant> or <constant>tex</constant>.
                 </para>
 
         </sect1>
 </chapter>
 
 <chapter id="wizard">
 
         <title>Wizards and Dialogs</title>
 
         <sect1 id="wizard_quickstart">
 
                 <title>QuickStart Wizard</title>
 
                 <para>This wizard has already been described in the section <xref linkend="intro_docwizard" role="select: title pageabbrv"/>.</para>
 
         </sect1>
 
         <sect1 id="wizard_graphics">
 
                 <title>Include Graphics</title>
 
                 <para>The <guilabel>Include Graphics</guilabel> dialog makes insertion of
                 graphics as easy as possible. You can reach it via the menubar with <menuchoice><guimenu>LaTeX</guimenu><guimenuitem>Image
                 Insertion</guimenuitem></menuchoice>. Please take a look at
                 <xref linkend="build_graphics" role="select: title pageabbrv"/> and <xref linkend="build_epsgraphics" role="select: title pageabbrv"/> to
                 get an overview of some basic facts concerning graphic formats.</para>
 
                 <screenshot>
                         <screeninfo>Including a graphics element</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="includegraphics.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Including a graphics element</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <procedure>
                 <step><para>Choose a graphics file. This can be a JPEG, PNG, PDF, EPS
                 or even a zipped or gzipped EPS file. If you have installed
                 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>
                 and also configured &kile; to use it
                 (<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>LaTeX</guimenuitem><guilabel>Graphics</guilabel></menuchoice>),
                 the width and the height of the graphic is automatically shown.
                 If &imagemagick; can determine a resolution, the size of the graphics
                 is also shown in centimeters.</para></step>
 
                 <step><para>Decide whether your image shall be centered on the page.</para></step>
 
                 <step><para>Choose whether you want the <userinput>\graphicspath</userinput>
                 notation for your graphics file.</para>
 
                 <para>By default graphics files have to be in the same
                 folder as your master document. However,
                 it is possible to put them in other folders to make
                 things tidier. Without a <userinput>\graphicspath</userinput>
                 command, &kile; would include the path for the graphics file.
                 But if you use <userinput>\graphicspath</userinput> in your
                 preamble like this:</para>
 
                 <programlisting>\graphicspath{{/path/to/my/graphics}{other/path/to/more/graphics}}</programlisting>
 
                 <para>and check this option, &kile; will only use the
                 base name of the graphics file.</para>
 
                 <para>Another example: if you set <userinput>\graphicspath</userinput>
                 command like:</para>
 
                 <programlisting>\graphicspath{{./}{camera/}{images/}}</programlisting>
 
                 <para>&latex; will search in the current folder, then in
                 <filename>camera</filename> and finally in
                 <filename>images</filename> to find your graphics file.</para></step>
 
                 <step><para>If you choose either a width or a height, the whole graphics
                 will be proportionally scaled. If you set two values for width and height
                 at the same time, width and height may be scaled with different factors,
                 and this could not be what you want. See also the information near the top
                 of the dialog to know the original size of the graphics.</para></step>
 
                 <step><para>Insert an angle by which to rotate the graphics counterclockwise.</para></step>
 
                 <step><para>The bounding-box information is set automatically
                 when you choose a graphics file. This information is only needed
                 when you work with traditional &latex; and bitmapped graphics.
                 See the discussion of <link linkend="build_epsgraphics">EPS graphics</link>.
                 </para>
 
                 <para>If &latex; needs a bounding box and you do not want to generate a bb file,
                 &kile; supports this option. On the other hand, &pdflatex; will give a warning
                 when you want to include a png or jpg graphics with this option. This checkbox
                 enables or disables the bounding-box option.</para></step>
 
                 <step><para>Scale the image by the desired scale factor. &eg;, 0.5 to reduce by half,
                 or 2 to double. When you use this option, you do not have to set a width or height for
                 the image.</para></step>
 
                 <step><para>In the <guilabel>Trim Image</guilabel> tab you can crop your
                 image in all four directions.</para></step>
 
                 <step>
                   <para>Finally, you have to specify whether you want to embed this image into a
                         figure environment. When you want the text to wrap around the figure, use the wrapfigure environment instead.
                   </para>
                         <note>
                                 <para>When you choose the wrapfigure environment, you need to include the wrapfig package in your preamble.</para>
                         </note>
                   <para>In either case you can insert a
                   caption and a label for your image. Generally, it is a good idea to add a different prefix to
                   each kind of label. It is common to use the prefix <userinput>fig:</userinput> for images.
                   </para>
                 </step>
 
                 <step><para>If you pick the figure environment, you can choose where &latex; should preferably position the figure.
                 </para></step>
                 <step>
                   <para>In the wrapfigure environment you can:</para>
                   <substeps>
                     <step><para>
                       Pick a placement rule for the figure and decide whether the figure should float or not.
                       In a two-sided document you can define whether the figure should be on the inside or outside edge of the page.
                     </para></step>
                     <step><para>
                       Define how many shortened lines of the text are set alongside the figure. If you leave this empty, &latex; will determine this itself as
                       well as is possible.
                     </para></step>
                     <step><para>
                       Define an overhang to the chosen side. This is especially useful when you have columns in your document and you want
                       a figure to span over more than just one column or you want shortened text on both sides of the figure.
                     </para></step>
                     <step><para>
                       Choose a width for the figure. This should be a bit bigger than the actual image width, so there will be some empty
                       space between the figure and the text.
                     </para></step>
                   </substeps>
                 </step>
                 </procedure>
 
         </sect1>
 
         <sect1 id="wizard_array">
 
                 <title>Arrays and tabulars</title>
 
                 <para>One of the most boring jobs one can do in &latex; is to write a matrix or a
                 tabular environment. One has to keep track of all the elements, ensure that the environment
                 is well formed, and that all things are where they are supposed to be. Good indentation helps,
                 but there is a simpler way: using &kile;'s <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Array</guimenuitem></menuchoice>
                 or
                 <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Tabular</guimenuitem></menuchoice> menu entries.
                 You will then have a matrix-style input form that you can easily fill in with your entries. This dialog also
                 offers some options to typeset the tabular material.</para>
 
                 <screenshot>
                         <screeninfo>Inserting a tabular environment</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="dialog-tabular.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Inserting a tabular environment</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>
                         Using the toolbar on top of the dialog you can set the <userinput>align</userinput> of a cell, define a certain <userinput>font style</userinput>,
                         <userinput>join</userinput> and <userinput>split</userinput> cells, choose a <userinput>border</userinput>, and specify background and font
                         <userinput>colors</userinput>.
                         On the extreme right there is a <guilabel>Paste</guilabel> button. With this button you can insert a table
                         from the clipboard into the dialog, which allows you to copy and paste tables from a spreadsheet program, for example.
                 </para>
 
                 <para>
                         Below you can choose how many rows and columns you want, and you can tweak some more details about your array:
                 </para>
 
                 <itemizedlist>
                         <listitem><para>
                                 With the <guilabel>Name</guilabel> option you can select which environment should be used for your array or tabular material.
                         </para></listitem>
                         <listitem><para>
                                 You can select the vertical cell alignment with the <guilabel>Parameter</guilabel> option. This is only enabled for
                                 environments which support that feature.
                         </para></listitem>
                         <listitem><para>
                                 If it exists for the selected environment, you can select <guilabel>use starred version</guilabel>. When you select this option,
                                 you also have to specify a <guilabel>table width</guilabel>.
                         </para></listitem>
                         <listitem><para>
                                 Tables sometimes look nicer when you select the <guilabel>use booktabs package</guilabel> option.
                         </para></listitem>
                         <listitem><para>
                                 Of course, you can also <guilabel>Center</guilabel> your whole array.
                         </para></listitem>
                         <listitem><para>
                                 <guilabel>Inserting bullets</guilabel> helps you when you want to fill in your content in the editor. With this option
                                 checked, &kile; will insert bullet placeholders for each element of your array.
                         </para></listitem>
                 </itemizedlist>
 
                 <para>The <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Tabbing</guimenuitem></menuchoice> option will display a simpler
                 dialog to quickly set up a tabbing environment. It allows you to easily specify the
                 number of rows or columns and the required spacing.</para>
         </sect1>
 
         <sect1 id="wizard_float">
           <title>Inserting floating elements</title>
 
           <para>&kile; helps you with inserting your floating elements. With the
             <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Floats</guimenuitem></menuchoice> wizard it is very simple to create
             a new figure or table environment.
           </para>
 
           <screenshot>
                 <screeninfo>Inserting a floating element</screeninfo>
                 <mediaobject>
                 <imageobject>
                 <imagedata fileref="dialog-float.png" format="PNG" />
                 </imageobject>
                 <textobject>
                 <phrase>Inserting a floating element</phrase>
                 </textobject>
                 </mediaobject>
         </screenshot>
 
         <para>
            To insert a new floating environment just follow these steps:
          </para>
 
              <procedure>
                <step>
                  <para>
                    Choose whether you want to insert a figure or a table.
                  </para>
                </step>
                <step>
                  <para>
                    Select the desired positioning rules.
                  </para>
                </step>
                <step>
                  <para>
                   Enter a caption for your floating element.
                 </para>
               </step>
               <step>
                 <para>
                   Type in a label for your new floating element. &kile; will automatically suggest an appropriate prefix , &eg; "fig:"
                   for figures and "tab:" for tables.
                 </para>
               </step>
              </procedure>
         </sect1>
 
         <sect1 id="wizard_math">
           <title>Inserting Math environments</title>
 
           <para>Remembering how all the different math elements work can be really annoying. Of course &kile; can do the
           magic for you here: <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Math</guimenuitem></menuchoice></para>
 
           <screenshot>
                 <screeninfo>Inserting a math element</screeninfo>
                 <mediaobject>
                 <imageobject>
                 <imagedata fileref="dialog-math.png" format="PNG" />
                 </imageobject>
                 <textobject>
                 <phrase>Inserting a math element</phrase>
                 </textobject>
                 </mediaobject>
           </screenshot>
 
           <para>
             Options:
           </para>
           <itemizedlist>
                                 <listitem><para><guilabel>Name:</guilabel> Choose the type of math element you want to create.</para></listitem>
                                 <listitem><para><guilabel>Without numbering:</guilabel> This can switch numbering off for numbered
                                         elements like equations or aligns.</para></listitem>
                                 <listitem><para><guilabel>Space command to separate groups:</guilabel> In an environment which supports several
                                 groups like alignat, you can define a space separator when you have more than one group. You can enter any space command here,
                                 which exists in mathmode, &eg; \quad. </para></listitem>
                                 <listitem><para><guilabel>Standard tabulator:</guilabel> Select the tabulator which should be used.
                                         &kile; should automatically pick the right one for you here.</para></listitem>
                                 <listitem><para><guilabel>Displaymath mode:</guilabel> For environments like matrices or arrays you can
                                         choose which math environment your mathematical text should be displayed with. </para></listitem>
                                 <listitem><para><guilabel>Use bullets:</guilabel> With this option checked, &kile; will insert bullet
                                         placeholders for each element of your mathematical text.</para></listitem>
                         </itemizedlist>
         </sect1>
 
         <sect1 id="wizard_postscript">
 
                 <title>&PostScript; Utilities</title>
 
                 <para>PS files are not so popular as PDF files, but are an excellent base
                 for manipulations and rearrangements of pages. If you need PDF
                 output, you can rearrange pages with some &PostScript; utilities and then
                 convert it to PDF with <command>ps2pdf</command>.</para>
 
                 <para>The <emphasis>&PostScript; Wizard</emphasis> under <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Postscript
                 Tools</guimenuitem></menuchoice> will suggest the most
                 popular rearrangement. The conversion is done
                 by the programs <command>pstops</command> and <command>psselect</command>, which
                 can be found in most distributions in the package <userinput>psutils</userinput>.
                 If one of these programs is not available, the corresponding item will not
                 be visible.</para>
 
                 <screenshot>
                         <screeninfo>Dialog PSTools</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="dialog-pstools.png" format="PNG" />
                         </imageobject>
                         <textobject>
                                 <phrase>Dialog PSTools</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>First choose your input file. If &kile; finds a PS file corresponding to your
                 current master document, it is already filled in as the input file, but you are also free
                 to choose another file. Then choose an output file, and select one of the tasks.
                 Finally, you have to decide whether you want to do the conversion only, or also invoke
                 &okular; to view the result.</para>
 
                 <variablelist>
 
                 <varlistentry>
                 <term>1 A5 page + empty page --> A4</term>
                 <listitem><para>Combine one A5 page together with one empty page
                 on one A4 page. Whenever two A5 pages are combined together,
                 they are rotated 90 degrees and will be arranged
                 on an A4 page in landscape mode.</para>
                 <screenshot>
                         <screeninfo>A5 + empty page</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils1.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>A5 + empty page</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>1 A5 page + duplicate --> A4</term>
                 <listitem><para>Put one A5 page and a duplicate together
                 on one A4 page.</para>
                 <screenshot>
                         <screeninfo>duplicate A5 pages</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils2.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Duplicate an A5 page</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>2 A5 pages --> A4</term>
                 <listitem><para>Put two consecutive A5 pages together
                 on one A4 page.</para>
                 <screenshot>
                         <screeninfo>Combine two A5 pages</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils3.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Combine two A5 pages</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>2 A5L pages --> A4</term>
                 <listitem><para>Put two consecutive A5 pages in landscape mode together
                 on one A4 page.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>4 A5 pages --> A4</term>
                 <listitem><para>Combine four consecutive A5 pages together on one
                 A4 page. The A5 pages have to be scaled with factor 0.7 to fit
                 on the page.</para>
                 <screenshot>
                         <screeninfo>4 A5 pages --> A4</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils5.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>4 A5 pages --> A4</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>1 A4 page + empty page --> A4</term>
                 <listitem><para>Combine one A4 page together with one empty page
                 on one A4 page. Whenever two A4 pages are combined together on one
                 resulting A4 page, they have to be scaled with factor 0.7 and will
                 be arranged in landscape mode.</para>
                 <screenshot>
                         <screeninfo>1 A4 page + empty page --> A4</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils6.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>1 A4 page + empty page --> A4</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>1 A4 page + duplicate --> A4</term>
                 <listitem><para>Put one A4 page and a duplicate together
                 on one A4 page.</para>
                 <screenshot>
                         <screeninfo>1 A4 page + duplicate --> A4</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils7.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>1 A4 page + duplicate --> A4</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>2 A4 pages --> A4</term>
                 <listitem><para>Put two consecutive A4 pages together
                 on one A4 page.</para>
                 <screenshot>
                         <screeninfo>Combine two A4 pages</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils8.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Combine two A4 pages</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>2 A4L pages --> A4</term>
                 <listitem><para>Put two consecutive A4 pages in landscape mode together
                 on one A4 page.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>select even pages</term>
                 <listitem><para>Select all even pages of a document.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>select odd pages</term>
                 <listitem><para>Select all odd pages of a document.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>select even pages (reverse order)</term>
                 <listitem><para>Select all even pages of a document and reverse the order.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>select odd pages (reverse order)</term>
                 <listitem><para>Select all odd pages of a document and reverse the order.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>reverse all pages</term>
                 <listitem><para>Reverse all pages of a document.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>copy all pages (sorted)</term>
                 <listitem><para>Copy all pages of a document. You have to
                 choose the number of sorted copies.</para>
                 <screenshot>
                         <screeninfo>Copy all pages (sorted)</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils15.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Copy all pages (sorted)</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>copy all pages (unsorted)</term>
                 <listitem><para>Copy all pages of a document. You have to
                 choose the number of non-sorted copies.</para>
                 <screenshot>
                         <screeninfo>Copy all pages (unsorted)</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="psutils16.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Copy all pages (unsorted)</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>pstops: choose parameter</term>
                 <listitem><para>There are many options for &PostScript; utilities
                 <command>pstops</command> and <command>psselect</command>. If you
                 need a very special one, you can invoke <command>pstops</command> with
                 an option of your choice. Please read the manual for all possible
                 options.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term>psselect: choose parameter</term>
                 <listitem><para>You can invoke <command>psselect</command> with
                 an option of your choice. Please read the manual for all possible
                 options.</para></listitem>
                 </varlistentry>
 
                 </variablelist>
 
         </sect1>
 
         <sect1 id="wizard_pdf">
 
                 <title>PDF Utilities</title>
 
                 <para>Many people think of PDFs as frozen files, which cannot be modified. But this is not true, as there exist excellent tools</para>
 
                 <itemizedlist>
                 <listitem><para>for manipulations and rearrangements of pages</para></listitem>
                 <listitem><para>to read and update document info</para></listitem>
                 <listitem><para>to read, set or change some permissions</para></listitem>
                 </itemizedlist>
 
                 <para>of an existing PDF document.</para>
 
                 <para>&kile;'s <emphasis>PDF wizard</emphasis> under <menuchoice><guimenu>Wizard</guimenu><guimenuitem>PDF Tools</guimenuitem></menuchoice> uses two different methods to manipulate and rearrange PDF documents:</para>
 
                 <itemizedlist>
                 <listitem><para>&latex; package <command>pdfpages</command>, which is part of each &latex; distribution. <command>pdfpages</command> doesn't work with encrypted pages.</para></listitem>
                 <listitem><para><command>pdftk</command>, which is an excellent command line tool for doing everyday things with PDF documents (see <ulink url="http://www.pdflabs.com/tools/pdftk-the-pdf-toolkit">The PDF Toolkit</ulink>).</para></listitem>
                 </itemizedlist>
 
                 <para>If one of these helpers, <command>pdfpages</command> or <command>pdftk</command>, is not present in your system, the corresponding items will not be visible. Furthermore, remember that only <command>pdftk</command> can work with encrypted files.</para>
 
                 <sect2 id="pdf_rearrangements">
 
                         <title>Rearrangements</title>
 
                         <para>If &kile;'s PDF wizard is called, it starts with the <userinput>Rearrangements</userinput> register card.</para>
 
                         <screenshot>
                                 <screeninfo>Dialog PDF Tools</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="dialog-pdftools1.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                         <phrase>Dialog PDF Tools</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
 
                         <para>First choose your input file. If &kile; finds a PDF file corresponding to your current master document, it will already be filled in as the input file, but you are also free to choose another file. Then choose an output file or overwrite the existing PDF file, and select one of the tasks. Finally, you have to decide whether you want to do the conversion only, or also invoke the viewer (&eg; &okular;) to show the resulting document.</para>
 
                         <para>If the PDF file is encrypted, only <command>pdftk</command> will work and you have to give the password of this document to execute tasks.</para>
 
                         <variablelist>
 
                         <varlistentry>
                         <term>1 page + empty page --> A4</term>
                         <listitem><para>Combine one page together with an empty page on one A4 page. Whenever two A5 pages are combined together, they are rotated by 90 degrees and arranged on an A4 page in landscape mode.</para>
                         <screenshot>
                                 <screeninfo>A5 + empty page</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="psutils1.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>A5 + empty page</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         <para>Whenever two A4 pages are combined together, they are scaled, rotated by 90 degrees and arranged on an A4 page in landscape mode.</para>
                         <screenshot>
                                 <screeninfo>A4 + empty page --> A4</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="psutils6.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>A4 + empty page</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         </listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>1 page + duplicate --> A4</term>
                         <listitem><para>Put one page and a duplicate together on one A4 page.</para>
                         <screenshot>
                                 <screeninfo>Duplicate a page</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="psutils2.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Duplicate a page</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         <para>If the page to be duplicated has A4 size, it will be scaled to fit on the page.</para>
                         <screenshot>
                                 <screeninfo>Duplicate a page</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="psutils7.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Duplicate a page</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         </listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>2 pages --> A4</term>
                         <listitem><para>Combine two consecutive pages together on one A4 page. Whenever two A5 pages are combined together, they are rotated by 90 degrees and arranged on an A4 page in landscape mode.</para>
                         <screenshot>
                                 <screeninfo>Combine two A5 pages</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="psutils3.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Combine two A5 pages</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         <para>Whenever two A4 pages are combined together, they are scaled, rotated by 90 degrees and arranged on an A4 page in landscape mode.</para>
                         <screenshot>
                                 <screeninfo>Combine two A4 pages</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="psutils8.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Combine two A4 pages</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         </listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>2 pages (landscape) --> A4</term>
                         <listitem><para>Put two consecutive pages in landscape mode together on one A4 page.</para>
                         <screenshot>
                                 <screeninfo>Combine two pages (in landscape mode)</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="pdftools1.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Combine two pages (in landscape mode)</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         </listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>4 pages --> A4</term>
                         <listitem><para>Combine four consecutive pages together on one
                         A4 page. The pages have to be scaled to fit on the page.</para>
                         <screenshot>
                                 <screeninfo>4 pages --> A4</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="psutils5.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>4 pages --> A4</phrase>
                                 </textobject>
                         </mediaobject>
                         </screenshot>
                         </listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>4 pages (landscape) --> A4</term>
                         <listitem><para>Combine four consecutive pages in landscape mode together on one A4 page. The pages have to be scaled to fit on the page.</para>
                         <screenshot>
                                 <screeninfo>Combine four pages (in landscape mode)</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="pdftools2.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Combine four pages (in landscape mode)</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
                         </listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>select even pages</term>
                         <listitem><para>Select all even pages of a document.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>select odd pages</term>
                         <listitem><para>Select all odd pages of a document.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>select even pages (reverse order)</term>
                         <listitem><para>Select all even pages of a document and reverse the order.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>select odd pages (reverse order)</term>
                         <listitem><para>Select all odd pages of a document and reverse the order.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>reverse all pages</term>
                         <listitem><para>Reverse all pages of a document.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>decrypt a file</term>
                         <listitem><para>If the PDF file is encrypted, you can decrypt it.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>select pages</term>
                         <listitem><para>Add a comma separated list of pages or page ranges, &eg; 1,4-7,9. Only these pages will appear in the resulting PDF file.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>delete pages</term>
                         <listitem><para>Add a comma separated list of pages or page ranges, which should be removed from the chosen PDF file.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>apply a background watermark</term>
                         <listitem><para>Applies a PDF watermark to the background of a single input PDF. The wizard only uses the first page from the background PDF and applies it to every page of the input PDF. This page is scaled and rotated as needed to fit the input page.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>apply a background color</term>
                         <listitem><para>Applies a background color to all pages of the current document. This can only be done once, as the second color will be put behind the first color and will not then be visible.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>apply a foreground stamp</term>
                         <listitem><para>Applies a foreground stamp on top of the input PDF document's pages. The wizard  uses only the first page from the stamp PDF and applies it to every page of the input PDF. This page is scaled and rotated as needed to fit the input page. This works best if the stamp PDF page has a transparent background.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>pdftk: choose parameter</term>
                         <listitem><para>You can invoke <command>pdftk</command> with an option of your choice. Please read the manual for all possible options.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         <term>pdfpages: choose parameter</term>
                         <listitem><para>You can invoke <command>pdfpages</command> with an option of your choice. Please read the manual for all possible options.</para></listitem>
                         </varlistentry>
 
                         </variablelist>
 
                 </sect2>
 
                 <sect2 id="pdf_properties">
 
                         <title>Properties</title>
 
                         <para>The setting, changing and removing of properties will only be possible if <command>pdftk</command> is installed and if additionally &kile; was compiled with the <userinput>libpoppler</userinput> library.</para>
 
                         <screenshot>
                                 <screeninfo>Dialog PDF Properties</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="dialog-pdftools2.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                         <phrase>Dialog PDF Properties</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
 
                         <para>Traditional PDF metadata includes the document's title, author, subject, keywords, creator, producer and the dates of creation and last modification.</para>
 
                 </sect2>
 
                 <sect2 id="pdf_permissions">
 
                         <title>Permissions</title>
 
                         <para>Also, the setting, changing and removing of permissions will be only possible if <command>pdftk</command> is installed.</para>
 
                         <screenshot>
                                 <screeninfo>Dialog PDF Permissions</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="dialog-pdftools3.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                         <phrase>Dialog PDF Permissions</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
 
                         <para>A password is necessary to set or change these document settings. Additionally, PDF encryption is done to lock the file's content behind this password or to enforce lighter restrictions imposed by the author. So the author can allow or restrict:</para>
 
                         <itemizedlist>
                         <listitem><para>printing pages</para></listitem>
                         <listitem><para>modifying pages</para></listitem>
                         <listitem><para>copying text and graphics from pages</para></listitem>
                         <listitem><para>changing or adding annotations</para></listitem>
                         <listitem><para>filling form fields with data.</para></listitem>
                         </itemizedlist>
 
                         <para>Changing permissions always forces encryption associated with 128-bit security of <userinput>Acrobat</userinput> 5 and 6, and also needs a password.</para>
 
                         <para>But always remember: encryption and a password do not provide any real PDF security. The content is encrypted, but the key is known. You should see it more as a polite but firm request to respect the author's wishes.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="statistics">
                 <title>Document Statistics</title>
 
                 <para>The statistics dialog in <menuchoice><guimenu>File</guimenu><guimenuitem>Statistics</guimenuitem></menuchoice> gives you
                 a statistical overview for a selection,
                 a document or a whole project. It includes the number of words, &latex;
                 commands/environments and also includes the number of characters for each type.</para>
 
                 <para>The statistics obtained can be copied as text or as a nicely formatted &latex; table
                 to the clipboard. </para>
                 <para>When you select a text and open the statistics dialog, you get the statistics for the currently selected text. If
                 you open the dialog without any text selected, the statistics for all opened files are shown.
                 If you want to get statistics for the whole project, you can use
                 <menuchoice><guimenu>Project</guimenu><guisubmenu>Open All Project Files</guisubmenu></menuchoice>
                 for an easy and quick way to open all source files of your project.</para>
 
                 <para>A note of caution has to be sounded about the accuracy of the numbers.
                 We have included some logic to get a good estimate, &eg; K\"uhler gives one word and one command,
                 with six and two characters respectively. But there are other combinations in which parts of commands
                 are counted as words and vice versa. Please note that the algorithm
                 was developed and tested for languages similar to English or German.
                 So don't take the numbers for granted. If you write a report whose length has to be of a certain
                 numbers of words or characters, please make some tests first in order to check whether &kile;'s accuracy satisfies your needs.</para>
         </sect1>
 
 </chapter>
 
 
 <chapter id="latex">
 
         <title>Special Tags in &latex;</title>
 
         <sect1 id="latex_library">
                 <title>Using the &latex; Tag Library</title>
 
                 <para>&latex; has thousands of tags for symbols and special characters.
                 The easiest way to insert these tags is to use the sidebar menu,
                 to the left of the editor window.</para>
 
                 <screenshot>
                         <screeninfo>The Sidebar Menu</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_sidebarmenu.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>The Sidebar Menu</phrase>
                         </textobject>
                         <caption><para>The Sidebar Menu</para></caption>
                         </mediaobject>
                 </screenshot>
                 <para>The following types are available:</para>
 
                 <itemizedlist>
                         <listitem><para>Most Frequently Used</para></listitem>
                         <listitem><para>Relation</para></listitem>
                         <listitem><para>Operators</para></listitem>
                         <listitem><para>Arrows</para></listitem>
                         <listitem><para>Miscellaneous Math</para></listitem>
                         <listitem><para>Miscellaneous Text</para></listitem>
                         <listitem><para>Delimiters</para></listitem>
                         <listitem><para>Greek</para></listitem>
                         <listitem><para>Special Characters</para></listitem>
                         <listitem><para>Cyrillic Characters</para></listitem>
                         <listitem><para>User Defined</para></listitem>
                 </itemizedlist>
                 <para>The tooltips of the icons show the &latex; commands and additionally needed packages.</para>
                 <para>Pressing <keycombo>&Shift;</keycombo> and clicking a symbol will result in
                 <userinput>$\symbolcmd$</userinput> being inserted. Similarly, pressing <keycombo>&Ctrl;</keycombo>
                 inserts it in curly brackets.</para>
                 <para>If you insert a command which requires a package which is not included in your &latex; document,
                 you will see a warning message in the logview window.</para>
                 <para>The first list of symbols holds the <guilabel>Most Frequently Used</guilabel> symbols. Inserted symbols will be
                         added to this list, for quick and easy reference. The ordering of the symbols will not be changed
                         upon addition of new symbols, instead a reference counter is incremented. If the number of items
                         exceeds 30 items, the item with the lowest count is removed.</para>
                 <para>The <guilabel>User Defined</guilabel> symbol list can hold your own symbols.
                 To create your own symbols you need the program gesymb and the file <filename>definitions.tex</filename> from the kile source package.
                 Additionally you need a &latex; compiler (what a surprise) and
                 <ulink url="http://www.dvipng.sourceforge.net">&dvipng;</ulink> (version 1.7 or later).
                 The procedure is that you create a &latex; file with <userinput>\input{definitions}</userinput>,
                 which makes the commands listed below available, and let <userinput>gesymb mysymbols.tex user</userinput>
                 (which calls &latex; and &dvipng;) create the icons. After copying them to
                 <userinput>$HOME/.kde/share/apps/kile/mathsymbols/user/</userinput> and restarting kile you can use your own symbols.
                 </para>
                 <para>
                 The following commands are defined in <filename>definitions.tex</filename>:
                 <itemizedlist>
                         <listitem>
                                 <para>
                                         <userinput>\command[\optarg]{\symbol}</userinput>: Include the symbol <userinput>\symbol</userinput> in the
                                         symbol list, the optional argument <userinput>\optarg</userinput> specifies the command which kile should insert.
                                         If it is not given the command in the mandatory argument is used.
                                 </para>
                         </listitem>
                         <listitem>
                                 <para>
                                         <userinput>\mathcommand[\optarg]{\symbol}</userinput>: Same as above, except that the command in the mandatory
                                         argument is inserted in math mode.
                                 </para>
                         </listitem>
                         <listitem>
                                 <para>
                                         <userinput>\pkgs[arg]{pkg}</userinput>: Declare that the command given in this line needs the &latex; package
                                         <userinput>pkg</userinput> with the optional argument <userinput>arg</userinput>. This command has to be in
                                         front of the <userinput>\command</userinput> command and overrides any package specification by the neededpkgs
                                         enviroment.
                                 </para>
                         </listitem>
                         <listitem>
                                 <para>
                                         <userinput>\begin{neededpkgs}[pkgs-args]{pkgs} ... \end{neededpkgs}</userinput>: Has the same effect as
                                         above, but for all enclosed commands.
                                 </para>
                         </listitem>
                 </itemizedlist>
                 </para>
                 <para>
                 An example for completeness is given here:
 <programlisting>\documentclass[a4paper,10pt]{article}
 \usepackage{amssymb}
 \input{definitions}
 %
 \begin{document}
 \pagestyle{empty}
 %
 \begin{neededpkgs}{amssymb}
 \mathcommand{\surd}
 \pkgs{amsmath}\mathcommand[\ddddot{}]{\ddddot{a}}
 \mathcommand{\angle}
 \end{neededpkgs}
 \command{\"A}
 \mathcommand{\exists}
 \mathcommand[\stackrel{}{}]{\stackrel{abc}{=}}
 
 %\begin{neededpkgs}[russian,koi8-r,T2C,]{babel,inputenc,fontenc,mathtext}
 %
 %   \end{neededpkgs}
 % this would need to include the packages
 % \usepackage{mathtext}
 % \usepackage[T2C]{fontenc}
 % \usepackage[russian]{babel}
 % \usepackage[koi8-r]{inputenc}
 %  just to explain the format
 \end{document}</programlisting>
                 </para>
         </sect1>
 
         <sect1 id="latex_bib">
 
                 <title>Using Bibitems</title>
 
                 <para><userinput>\bibitem</userinput> is a command used to enter a reference in a
                 <userinput>thebibliography</userinput> environment in your document. The syntax for using
                 <userinput>\bibitem</userinput> is <userinput>\bibitem[label]{key}</userinput>.</para>
 
                 <para>The optional <userinput>[label]</userinput> is for you to add your own
                 labeling system for the bibliography entry. If no label is set, the entries
                 will be set in numerical order: [1], [2], [3], &etc;</para>
 
                 <para>The argument <userinput>{key}</userinput> is used to reference and link the commands
                 <userinput>\bibitem</userinput> and <userinput>\cite</userinput> to
                 each other and the information they contain. The command <userinput>\cite</userinput> contains the
                 label associated with the intended <userinput>\bibitem</userinput>, which is located inside a
                 <userinput>thebibliography</userinput> environment, and contains the reference data.
                 Both corresponding <userinput>\bibitem</userinput> and <userinput>\cite</userinput> must
                 have the same <userinput>{key}</userinput>; the easiest way to organize keys is by
                 the author's last name. The secondary braces in the <userinput>thebibliography</userinput>
                 environment denote the longest bibliography label you expect to have.
                 So, inserting <userinput>{<replaceable>foo</replaceable>}</userinput> means
                 you can have any label shorter or as large as the expression
                 <userinput><replaceable>foo</replaceable></userinput>. Failure to set this parameter correctly
                 may result in a not so attractive indentation of your bibliography.</para>
 
                 <para>The bibliography is a section apart from your main document, and an example of
                 code for the bibliography would look like the following:</para>
 
 <programlisting>\begin{thebibliography}{50}
         \bibitem{Simpson} Homer J. Simpson. \textsl{Mmmmm...donuts}. Evergreen Terrace Printing Co.,
                           Springfield, SomewhereUSA, 1998
 \end{thebibliography}</programlisting>
 
                 <para>Then, your main source code would contain the location of the information relating to
                 the <userinput>\bibitem</userinput> using <userinput>\cite</userinput>. That source code would look similar to this:</para>
 
                 <programlisting>My thesis, about the philosophy of The Simpsons\copyright comes from my favorite book \cite{Simpson}.</programlisting>
 
                 <para>As it is often difficult to remember the exact citation key once you have many
                 references, &kile; provides an easy way to insert a citation. Using <menuchoice><guimenu>LaTeX
                 </guimenu><guimenuitem>References</guimenuitem><guimenuitem>Cite</guimenuitem></menuchoice>
                 a list with all the citation keys pops up. Select the correct
                 reference and a citation will be inserted into your document. To update the list of keys,
                 either save the file, or <menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh
                 Structure</guimenuitem></menuchoice>, or press <keycap>F12</keycap>.
                 With code completion enabled, &kile; will show you a list of all the <userinput>bibitem</userinput>-labels
                 as soon as you open up a <userinput>\cite</userinput> command.</para>
 
                 <para>The final result in your document's bibliography would then look like this:</para>
 
                 <para><computeroutput>[1] Homer J. Simpson. Mmmmm...donuts. Evergreen Terrace Printing Co.,
                 Springfield, SomewhereUSA, 1998.</computeroutput></para>
 
                 <para>&kile; can also work together with &bibtex; editors,
                 such as &kbibtex; to make it easier to enter citations. When a &bibtex; file is added to the project,
                 &kile; will help you complete citation commands, just as described above.</para>
 
         </sect1>
 
 </chapter>
 
 &include-section-usermenu;
 
 <chapter id="build">
 
         <title>The Build Tools</title>
 
         <sect1 id="build_sect">
 
                 <title>Compiling, converting and viewing</title>
 
                 <para>To view the result of your work, you first need to compile the source. All the build
                 tools are grouped closely together in the
                 <menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu></menuchoice>,
                 <menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu></menuchoice>,
                 and <menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu></menuchoice>
                 menus.</para>
 
                 <para>To compile your source code for screen viewers like &okular; or
                 further conversion, you can use the shortcut <keycombo>&Alt;<keycap>2</keycap></keycombo>.
                 Then you can view the &DVI; file using your default viewer with
                 <keycombo>&Alt;<keycap>3</keycap></keycombo>, convert
                 the &DVI; to a PS file with <keycombo>&Alt;<keycap>4</keycap></keycombo>,
                 and view the PS file with <keycombo>&Alt;<keycap>5</keycap></keycombo>.</para>
 
                 <sect2>
 
                 <title>&bibtex;</title>
 
                         <para>If you are using <ulink url="http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html">&bibtex;</ulink>
                         for your bibliography entries, you usually have to follow a special compiling scheme.
       This means calling &latex; and then &bibtex; and then &latex; twice again. Fortunately &kile; is clever enough to
       detect automatically if it is necessary to call additional tools like &bibtex;, &makeidx; and &asymptote;.
       This logic is turned on by default and can be changed in <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
       Kile...</guisubmenu><guisubmenu>Tools</guisubmenu><guilabel>Build</guilabel></menuchoice> in the <guilabel>General</guilabel> tab in the &latex; and &pdflatex; tools.
       </para>
 
                 </sect2>
 
 <!-- Already stated in last paragraph
                 <sect2>
 
                         <title>&makeidx;</title>
 
                         <para>If you are using the <ulink url="http://ipagwww.med.yale.edu/latex/makeindex.pdf">&makeidx;</ulink>
                         package to make a final, alphabetical index for your document, you have also to follow a certain
                         compilation pattern or let &kile; do this for you in the same way as with &bibtex; files.</para>
 
                 </sect2>
 -->
                 <sect2>
 
                         <title>MetaPost and &asymptote;</title>
 
                         <para>If you want to compile your document with <application>MetaPost</application> or <application>&asymptote;</application>, picture drawing programs, you can do it with
                         <menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu><guimenuitem>Metapost</guimenuitem></menuchoice>,
                         or <menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu><guimenuitem>&asymptote;</guimenuitem></menuchoice>.</para>
 
                 </sect2>
 
                 <sect2>
 
                         <title>&pdflatex;</title>
 
                         <para>There is also another way to compile your document, if you want a PDF: you can run
                         &pdflatex;, that will compile the source directly into a PDF file, with
                         <keycombo>&Alt;<keycap>6</keycap></keycombo>: you can then view the compiled
                         file by pressing <keycombo>&Alt;<keycap>7</keycap></keycombo>.</para>
 
                         <para>Alternatively, you can convert a PS into a PDF with
                         <keycombo>&Alt;<keycap>8</keycap></keycombo>, or a
                         &DVI; directly into a PDF with <keycombo>&Alt;<keycap>9</keycap></keycombo>.</para>
 
                         <para>Using &pdflatex; instead of &latex; may be just a matter of simplicity or habit,
                         but sometimes the behavior of the two programs can differ.</para>
 
                 </sect2>
 
                 <sect2>
 
                         <title>&latex; to Web</title>
 
                         <para>Finally, you may want to publish your work on the web and not just on paper. You may
                         then use the <application>latex2html</application> program, that can be called from &kile;'s menu
                         <menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu><guimenuitem>LaTeX
                         to Web</guimenuitem></menuchoice>. The result will be placed in a subfolder of the work folder,
                         and you will be able to see the result of the conversion choosing the menu item
                         <menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu><guimenuitem>View
                         &HTML;</guimenuitem></menuchoice>.</para>
 
                 </sect2>
 
                 <sect2 id="build_cl">
 
                         <title>Passing Command Line Parameters</title>
 
                         <para>If you want to pass some specific command line parameters to the compile, convert
                         or view tools, you can configure their call in <menuchoice><guimenu>Settings</guimenu>
                         <guisubmenu>Configure Kile...</guisubmenu><guisubmenu>Tools</guisubmenu><guilabel>Build</guilabel></menuchoice>.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="build_preview">
                 <title>Quick Preview</title>
 
                 <para>You will always need some time to view the result, when working with &latex;.
                 &latex; has to compile the source and the viewer has to be called. This can be
                 annoying if you only changed some letters in an equation difficult to typeset.
                 &kile; offers a <emphasis>Quick Preview</emphasis> mode, where you can compile
                 only a part of a document and save a lot of time. It supports four different modes,
                 which can be combined with seven configurations.</para>
 
                 <screenshot>
                         <screeninfo>Quick Preview</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="quickpreview.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Quick Preview</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>All settings must be done in
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>Tools</guimenuitem><guilabel>Preview</guilabel></menuchoice>.</para>
 
                 <screenshot>
                         <screeninfo>Quick Preview Configuration</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="config-quickpreview.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Quick Preview Configuration</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <sect2 id="build_qp_selection">
 
                         <title>Selection Mode</title>
 
                         <para>The user has to select a part of the document. Menu entry <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Selection</guimenuitem></menuchoice>
                         or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>S</keycap>
                         will start the selected programs. &kile; takes the preamble of the original text, so that
                         all packages and user defined commands are included. The user can choose one
                         of eight predefined configurations:</para>
 
                         <itemizedlist>
                         <listitem><para><application>LaTeX+&DVI; (embedded viewer)</application></para></listitem>
                         <listitem><para><application>LaTeX+&DVI; (&okular;)</application></para></listitem>
                         <listitem><para><application>LaTeX+PS (embedded viewer)</application></para></listitem>
                         <listitem><para><application>LaTeX+PS (&okular;)</application></para></listitem>
                         <listitem><para><application>PDFLaTeX+PDF (embedded viewer)</application></para></listitem>
                         <listitem><para><application>PDFLaTeX+PDF (&okular;)</application></para></listitem>
                         <listitem><para><application>XeLaTeX+PDF (embedded viewer)</application></para></listitem>
                         <listitem><para><application>XeLaTeX+PDF (&okular;)</application></para></listitem>
                         </itemizedlist>
 
                         <para>This should be sufficient for all situations for which a quick preview is needed.</para>
 
                 </sect2>
 
                 <sect2 id="build_qp_environment">
 
                         <title>Environment Mode</title>
 
                         <para>Very often you want to preview the current environment, and especially mathematical
                         environments, which sometimes may be difficult to write. &kile; offers a very fast way
                         to do this. No selection is needed, just choose
                         <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Environment</guimenuitem></menuchoice>
                         or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>E</keycap>
                          and the current environment will be compiled and shown.</para>
 
                 </sect2>
 
                 <sect2 id="build_qp_subdocument">
 
                         <title>Subdocument Mode</title>
 
                         <para>If you have a large project with a lot of documents, compiling the whole
                         project is not a great idea, if you have made changes only in one single document.
                         &kile; is able to compile and show a preview of the current subdocument. It
                         takes the preamble from the master document and only compiles the current part
                         when you choose <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Subdocument</guimenuitem></menuchoice>
                         or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>D</keycap>.</para>
 
                 </sect2>
 
                 <sect2 id="build_qp_mathgroup">
 
                         <title>Mathgroup Mode</title>
 
                         <para>The mathgroup preview mode allows you to preview the mathgroup you are currently editing. &kile;
                         takes the preamble from the master document and only compiles the mathgroup the cursor is currently in
                         when you choose <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Mathgroup</guimenuitem></menuchoice>
                         or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>M</keycap>.</para>
 
                 </sect2>
 
                 <sect2 id="qp_bottombar">
 
                         <title>Quick Preview in Bottom Bar</title>
 
                         <para>Instead of showing the preview in a new document &kile; can also be configured to use the bottom bar for preview
                         compilations. You can activate this feature in the quick preview configuration panel.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="build_graphics">
 
                 <title>Graphic File Formats</title>
 
                 <sect2 id="build_graphics_latex">
 
                 <title>&latex; and &pdflatex;</title>
 
                 <para>&pdflatex;, when used with <userinput>graphics</userinput> or
                 <userinput>graphicx</userinput> packages, can correctly compile PNG and JPG files into
                 &DVI; or PDF, but is not able to handle EPS files. Conversely, the process of compiling
                 with &latex; to &DVI; and converting to PS and eventually PDF does support EPS, but does
                 not support PNG and JPG.</para>
 
                 <para>A lot of users want to create PDF documents, but also want to use the excellent
                 <application>Pstricks</application> package to create &PostScript; graphics, or they want
                 to use the &PostScript; output of mathematical and scientific software like
                 <application>Mathematica</application>, <application>Maple</application> or <application>MuPAD</application>.
                 These &latex; users have to compile first in &PostScript;, even if they want to create
                 PDF documents, because these programs produce &PostScript; code which cannot be managed
                 by &pdflatex;. However, it is not so hard as it may sound, because &kile; will help.</para>
 
                 </sect2>
 
                 <sect2 id="build_graphics_conversion">
 
                 <title>Graphics Conversion</title>
 
                 <para>To overcome this frustrating loop, when you want to include both &PostScript; code and PNG or JPG files,
                 you have a number of workarounds:</para>
 
                 <itemizedlist>
                         <listitem><para>If you need a file in PS format, but have JPG or PNG graphics, you can also
                         simply use &pdflatex; with &DVI; output first, and then run <application>dvips</application>
                         to create the PS file. You see that &pdflatex; is a very good choice, if your source contains
                         no &PostScript; code at all.</para></listitem>
 
                         <listitem><para>You can convert EPS files to PNG or other formats with utilities as the
                         <ulink url="http://www.gimp.org/"><application>Gimp</application></ulink> or
                         <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>
                         and use &pdflatex;.</para></listitem>
 
                         <listitem><para><anchor id="build_graphics_epstopdf"></anchor>A preferred way
                         is to convert EPS graphics to PDF graphics with
                         <command>epstopdf</command>, which comes with every &tex; distribution
                         and then use &pdflatex;. It produces high quality graphics,
                         and you can even control the result with some of the following options:
 
 <programlisting>
         -dAutoFilterColorImages=false
         -dAutoFilterGrayImages=false
         -sColorImageFilter=FlateEncode
         -sGrayImageFilter=FlateEncode
         -dPDFSETTINGS=/prepress
         -dUseFlateCompression=true
 </programlisting>
                         </para>
 
                         <para>Even better: if your system allows <userinput>shell-escape</userinput>, conversion
                         can be done on the fly. All you have to do is to include the <application>epstopdf</application> package,
                         which is part of all &tex; distributions, with the command <userinput>\usepackage{epstopdf}</userinput>.
                         Assuming that your code is:
 
 <programlisting>
         \includegraphics[width=5cm]{test.eps}
 </programlisting>
 
                         When you call &pdflatex; with option <option>--shell-escape</option>,
                         graphics <filename>test.eps</filename> is automatically converted into <filename>test.pdf</filename>.</para>
 
                         <para>This conversion will take place each time you run &pdflatex;.
                         If your graphics command is given implicitly:
 
 <programlisting>
         \includegraphics[width=5cm]{test}
 </programlisting>
 
                         <application>epstopdf</application> checks whether <filename>test.pdf</filename> is already
                         available, so that the conversion step can be skipped.</para></listitem>
 
                         <listitem><para>You can convert the other way around, and use &latex; and PS-PDF conversion.
                         This is not always a good idea, since EPS encapsulation of JPG or PNG can yield larger
                         files, that in turn yield unnecessarily large documents. This is however <emphasis>highly</emphasis>
                         dependent on the graphic utility that you use, since EPS can encapsulate other graphics,
                         but not all applications support this perfectly. Some might actually try to build your JPG image
                         with vectors and various scripting, which will result in gigantic files. Conversion of
                         all graphics formats to EPS can be done by
                         <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>.
                         Another simple program that does this process correctly is
                         <ulink url="http://www.tex.uniyar.ac.ru/win32/tools/jpg2ps/"><application>jpg2ps</application></ulink>.
                         </para></listitem>
 
                         <listitem><para>You can also use an automatic conversion. All graphics files are
                         converted on the fly to EPS, and inserted into the PS document. This is a comfortable
                         way, but you have to set up your system properly. This is discussed in the section
                         <link linkend="build_epsgraphics">EPS Graphics</link>.</para></listitem>
 
                 </itemizedlist>
 
                 </sect2>
 
                 <sect2 id="build_graphics_type">
 
                 <title>Use the right File for the right Graphic</title>
 
                 <itemizedlist>
                         <listitem><para>EPS is sort of a graphic vector scripting language, describing
                         all the lines and dots the graphic is made of; it looks good even when magnified beyond its
                         default size, and suits best diagrams and vectorial graphics natively produced in EPS,
                         which look very clear and sharp while maintaining a very small byte size.</para></listitem>
                         <listitem><para>PNG (or the deprecated &GIF;) is a <emphasis>non-lossy</emphasis> file format,
                         with good compression and quality. It is very good for diagrams, scans of drawings,
                         or anything whose sharpness you do want to retain. It is sometimes overkill
                         when used for photos.</para></listitem>
                         <listitem><para>JPG is a <emphasis>lossy</emphasis> format, that compresses files better than PNG
                         at the price of some loss in the picture detail. This is usually irrelevant for photos,
                         but may cause bad quality for diagrams, drawings, and may make some thin lines disappear outright;
                         in those cases use EPS or PNG.</para></listitem>
                 </itemizedlist>
 
                 <para>But always remember: garbage in, garbage out! No conversion will make a bad picture good.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="build_epsgraphics">
 
                 <title>EPS Graphics</title>
 
                 <para>EPS graphics files are the traditional way to insert graphics files into
                 &latex; documents. As mailing lists are full with questions concerning
                 EPS graphics, we will discuss some important aspects and
                 demonstrate how &kile; supports them.</para>
 
                 <sect2 id="build_graphics_eps">
 
                 <title>&latex; and EPS Graphics</title>
 
                 <para>If you decided to use the traditional &latex; to produce
                 PS or PDF output, you will probably run into some problems
                 with graphics. You have to use EPS graphics (Encapsulated &PostScript;);
                 no JPEG or PNG files. This should be no problem, as there are a lot of
                 <link linkend="build_graphics_conversion">converters</link> like
                 <command>convert</command> from the excellent
                 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>
                 package. But, it needs some time of course.</para>
 
                 <para>The EPS files are used by both &latex; and the &DVI;-PS converter:</para>
 
                 <itemizedlist>
                 <listitem><para>&latex; scans the EPS file for the bounding-box
                 line, which tells &latex; how much space to reserve for the
                 graphics.</para></listitem>
 
                 <listitem><para>The &DVI;-PS converter then reads the EPS file and
                 inserts the graphics in the PS file.</para></listitem>
                 </itemizedlist>
 
                 <para>This has some implications:</para>
 
                 <itemizedlist>
                 <listitem><para>&latex; never reads the EPS file if the bounding-box
                 parameters are specified in the graphics insertion command.</para></listitem>
 
                 <listitem><para>Since &latex; cannot read non-ASCII files,
                 it cannot read the bounding-box information from compressed or non-EPS
                 graphics files.</para></listitem>
 
                 <listitem><para>The EPS graphics are not included in the &DVI; file. Since the
                 EPS files must be present when the &DVI; file is converted to
                 PS, the EPS files must accompany the &DVI; files whenever they are
                 moved.</para></listitem>
                 </itemizedlist>
 
                 <para>Now you can call &latex;, and a &DVI;-PS converter like <application>dvips</application>
                 to create your &PostScript; document. If your goal is a PDF document, you should run
                 <command>dvips</command> with option <option>-Ppdf</option> and then call
                 <command>ps2pdf</command>. You will find a lot of documents describing this solution.</para>
 
                 </sect2>
 
                 <sect2 id="build_graphics_epskile">
 
                 <title>The &PostScript; Way of &kile;</title>
 
                 <para>&kile; helps you to get the bounding-box information. If you have installed
                 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>
                 package, &kile; will extract this information from the EPS file and insert it as an
                 option. This is done automatically when you select the graphics file.
                 There are two advantages to proceeding like this:</para>
 
                 <itemizedlist>
                 <listitem><para>The information is already scanned in the dialog, and
                 need not to be done by &latex; later on.</para></listitem>
                 <listitem><para>Even more important is that the width and height of the picture
                 can be calculated, when the resolution is known. This information will be shown
                 near the top of the dialog, and may serve as a clue when you want to scale the
                 graphics.</para></listitem>
                 <listitem><para>&kile; can also support zipped or gzipped EPS files,
                 which are much smaller than uncompressed EPS files. But, this feature can only be used
                 with a special system setup and a change of your local graphics configuration,
                 as it is described in the <link linkend="build_graphics_bitmap">Bitmap Graphics</link>
                 section.</para></listitem>
                 </itemizedlist>
         <!-- FIXME I don't understand the following sentence, tbraun
                 <para> The <emphasis>&PostScript; Way of &kile;</emphasis> can be turned off or on in
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>LaTeX</guimenuitem><guilabel>General</guilabel></menuchoice>.</para>
                 -->
         </sect2>
 
         <sect2 id="build_graphics_bitmap">
 
                 <title>The &PostScript; Way and Bitmap Graphics</title>
 
                 <para>If your system allows <userinput>shell-escape</userinput>, &kile;
                 also supports an easy way to include bitmap graphics, if you set up your &tex;
                 system properly. There is no need to convert JPEG or PNG graphics,
                 this can be done automatically when the &DVI; file is converted to PS.</para>
 
                 <para>&latex; needs some information about the file suffixes. The package
                 <userinput>graphicx</userinput> looks for a file <filename>graphics.cfg</filename>,
                 which must be somewhere in your search path for &latex; documents. Search for
                 entries like:</para>
 
 <programlisting>
    \DeclareGraphicsRule{.pz}{eps}{.bb}{}%
    \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}%
    \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}%
    \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}%
    \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{}%
 </programlisting>
 
                 <para>and replace these lines with:</para>
 
 <programlisting>
    \DeclareGraphicsRule{.pz}{eps}{.bb}{}%
    \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}%
    \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}%
    \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}%
    % changed or new graphic rules
    \DeclareGraphicsRule{.eps.zip}{eps}{.eps.bb}{`unzip -p #1}%   zipped EPS
    \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c #1}%   gzipped EPS
    \DeclareGraphicsRule{.jpg}{eps}{}{`convert #1 eps:-}%         JPEG
    \DeclareGraphicsRule{.gif}{eps}{.bb}{`convert #1 eps:-}%      GIF
    \DeclareGraphicsRule{.png}{eps}{.bb}{`convert #1 eps:-}%      PNG
    \DeclareGraphicsRule{.tif}{eps}{.bb}{`convert #1 eps:-}%      TIFF
    \DeclareGraphicsRule{.pdf}{eps}{.bb}{`convert #1 eps:-}%      PDF-graphics
 </programlisting>
 
                 <para>You will find this file, for example in Debian, at
                 <filename>/etc/texmf/latex/graphics.cfg</filename>. The best way to proceed is to copy this
                 file to your local texpath and then change this copy. See your &tex; distribution manual
                 to learn how to get a list of your &tex; folders.</para>
 
                 <para>With this configuration file you are able to insert bitmap graphics and
                 zipped or gzipped EPS files in &latex;. The command for conversion
                 is given by <command>dvips</command>. When you look
                 at the conversion command you will see that no extra file is created.
                 The result of the conversion process is directly piped into the PS file.
                 The only thing &latex; must know is the size of the graphics, and
                 therefore we need the bounding box, which is provided by &kile;.</para>
 
                 <para>Some say that this way is insecure; you have to decide on how to work.
                 In any case, you need no bounding box, as &kile; will extract this information
                 from all types of graphics.</para>
 
                 </sect2>
 
                 <sect2 id="build_graphics_pdflatex">
 
                 <title>&pdflatex; and EPS Graphics</title>
 
                 <para>As already stated, &pdflatex; is not able to handle EPS graphic files,
                 but converters like <link linkend="build_graphics_epstopdf">epstopdf</link>
                 will help. The best way is to include package <filename>epstopdf</filename>,
                 which must follow the <userinput>graphicx</userinput> package.</para>
 
 <programlisting>
    \usepackage[pdftex]{graphicx}
    \usepackage{epstopdf}
 </programlisting>
 
                 <para>Now you can already include EPS graphics, if you run <command>pdflatex</command>
                 with option <option>--shell-escape</option>, but we can make it even better
                 and also handle zipped or gzipped EPS files. Again we have to change
                 the graphics configuration file <filename>graphics.cfg</filename> as above.
                 This time we search for:</para>
 
 <programlisting>
    % pdfTeX is running in pdf mode
    \ExecuteOptions{pdftex}%
 </programlisting>
 
                 <para>and simply add some lines:</para>
 
 <programlisting>
    % pdfTeX is running in pdf mode
    \ExecuteOptions{pdftex}%
    \AtEndOfPackage{%
       \g@addto@macro\Gin@extensions{.eps.gz,.eps.zip}%
       \@namedef{Gin@rule@.eps.gz}#1{{pdf}{.pdf}{`gunzip -c #1 | epstopdf -f >\Gin@base.pdf}}%
       \@namedef{Gin@rule@.eps.zip}#1{{pdf}{.pdf}{`unzip -p #1 | epstopdf -f >\Gin@base.pdf}}%
    }%
 </programlisting>
 
                 <para>With these lines, &pdflatex; is able to handle EPS files,
                 and hopefully there should be no more issues concerning graphics.</para>
 
         </sect2>
 
         </sect1>
 
         <sect1 id="build_master">
 
                 <title>Master Document</title>
 
                 <para>Defining your document as a master allows you to work with separate files,
                 which gives you a parent document (or Master document), and child documents that
                 make up a complete work. After having defined your Master document, with the
                 corresponding command in the <guimenu>Settings</guimenu>
                 menu, all the commands of the <guimenu>Tools</guimenu>
                 menu will apply only to this document, even when you are working on the child
                 documents. You can even close the Master document.</para>
         </sect1>
 
         <sect1 id="build_errorhandling">
 
                 <title>Error Handling</title>
 
                 <para>After you have compiled something, &kile; takes a look at the error messages
                 that were generated. If there are any errors or warnings, they will be briefly reported
                 in the <guilabel>Log and Messages</guilabel> window. One can take a closer look at the
                 messages by selecting <menuchoice><guimenu>Build</guimenu><guimenuitem>View Log File</guimenuitem></menuchoice>,
                 or by using the keyboard shortcut <keycombo>&Alt;<keycap>0</keycap></keycombo>.
                 The generated log is then displayed in the <guilabel>Log and Messages</guilabel> view; errors and warnings are highlighted.</para>
 
                 <screenshot>
                         <screeninfo>Viewing the log</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_compile_error.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Viewing the log</phrase>
                         </textobject>
                         <caption><para>Viewing the log</para></caption>
                         </mediaobject>
                 </screenshot>
 
                 <para>You can easily jump from one message in the log file to another by using the
                 <menuchoice><guimenu>Build</guimenu><guimenuitem>Next / Previous
                 LaTeX Error / Warning</guimenuitem></menuchoice> menu items, or by using
                 the corresponding toolbar buttons.</para>
 
                 <para>To jump to the line in the &latex; source where the error or warning occurred,
                 click on the error or warning in the <guilabel>Log and Messages</guilabel> view.
                 &kile; will take you automatically to the offending line.</para>
 
         </sect1>
 
         <sect1 id="build_watch">
 
                         <title>The Watch File Mode</title>
 
                         <para>When you launch the <guibutton>Quickbuild</guibutton> command, a viewer of
                         some sort will normally be called after the compilation. If you are not using an embedded
                         viewer, a new window will be opened every time.</para>
 
                         <para>If you are adjusting the look of your document, you might launch
                         <guibutton>Quickbuild</guibutton> very often, and have many viewer windows open on
                         your desktop; to avoid this confusion, you can activate the <guibutton>Watch file</guibutton>
                         mode, that will prevent <guibutton>Quickbuild</guibutton> from launching a viewer.</para>
 
                         <para>This mode is of course useless with the embedded viewers, as you have to close them
                         anyway to get back to editing the document and recompiling.</para>
 
         </sect1>
 
 </chapter>
 
 <chapter id="navigating">
 
         <title>Navigating the &latex; Source</title>
 
         <sect1 id="navigating_struct">
 
                 <title>Using the Structure View</title>
 
                 <para>The <guilabel>Structure</guilabel> view shows the hierarchy of the document
                 being created in &kile;, and allows you to quickly navigate it, showing its segmentation.
                 To navigate around your document, all you need to do is to left click on any label, chapter,
                 section, subsection, etc., and you will be taken to the beginning of
                 the corresponding area.</para>
 
                 <para>If you included a separate &latex; file in your source using
                 the <userinput>\input</userinput> or <userinput>\include</userinput> tags, these files will
                 be referred to in the <guilabel>Structure</guilabel> view; double-clicking on their names
                 will make &kile; bring up the included file in the editor window.</para>
 
                 <para>The hierarchy tree also has a separate branch for labels used in the text.</para>
 
 <!--            <screenshot>
                         <screeninfo>Using the Structure View</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_structview_label.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Using the Structure View</phrase>
                         </textobject>
                         <caption><para>Using the Structure View</para></caption>
                         </mediaobject>
                 </screenshot>-->
 
                 <sect2 id="navigating_contextmenu">
 
                         <title>Using the Context Menu</title>
 
                         <para>Most of the entries in the structure view have a lot of entries in the context menu,
                         which you can open with a right mouse click. So look at the structure view in the
                         following picture.</para>
 
                         <screenshot>
                                 <screeninfo>Using the Structure View</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="structureview.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Using the Structure View</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
 
                         <para>You will find some labels, some sectioning entries, two figure environments and three
                         pictures. If you right click on one of the sectioning entries, a menu with some useful
                         commands will popup. All commands like <guibutton>Select</guibutton>, <guibutton>Delete</guibutton>
                         or <guibutton>Comment</guibutton> will work with all lines, which belong to this section.</para>
 
                         <screenshot>
                                 <screeninfo>Context menu for sectioning entries</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="structureview-context1.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Context menu for sectioning entries</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
 
                         <para>Clicking on a figure or table entry will offer some actions with respect to references
                         and a right click on a graphics entry will offer some programs to open the graphics.</para>
 
                         <screenshot>
                                 <screeninfo>Context menu for figure/tables and graphics entries</screeninfo>
                                 <mediaobject>
                                 <imageobject>
                                 <imagedata fileref="structureview-context2.png" format="PNG" />
                                 </imageobject>
                                 <textobject>
                                 <phrase>Context menu for figure/tables and graphics entries</phrase>
                                 </textobject>
                                 </mediaobject>
                         </screenshot>
 
                         </sect2>
 
                 <sect2 id="navigating_update">
 
                         <title>Updating the Structure View</title>
 
                         <para>To update your structure view you can either go to
                         <menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh
                         Structure</guimenuitem></menuchoice>, hit <keycombo><keycap>F12</keycap></keycombo>, or you can save your document,
                         which will make &kile; update its <guilabel>Structure</guilabel> view.</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="navigating_bookmarks">
 
                 <title>Bookmarks</title>
 
                 <para>Bookmarks are your reference to a segment of text or a line inside the &kile;
                 environment. To use a bookmark, select a specific line of your document
                 you would like to return to, then press <keycombo>&Ctrl;
                 <keycap>B</keycap></keycombo>, and &kile; will add a bookmark to this line.
                 Alternatively, you can also set a bookmark by highlighting a line and choosing
                 the menu labeled <menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Set
                 Bookmark</guimenuitem></menuchoice>.</para>
 
                 <para>To remove all your bookmarks, select <menuchoice><guimenu>Bookmarks</guimenu>
                 <guimenuitem>Clear All Bookmarks</guimenuitem></menuchoice>.</para>
 
         </sect1>
 
 </chapter>
 
 <chapter id="projects">
 
         <title>Projects</title>
 
         <sect1 id="projects_working">
 
                 <title>Working with Projects</title>
 
                 <para>In &kile; you can create and work with <emphasis>projects</emphasis>. A project is a
                 group of &latex;, graphic, &bibtex;, or other files that contain all the information that is used to build
                 your complete document. A typical project would be a document consisting of several chapters,
                 written in different <literal role="extension">.tex</literal> files; all of them could be included in
                 a project, to make the whole document easier to manage. The specifications of the project are stored in a special file,
                 with extension <literal role="extension">.kilepr</literal>.</para>
 
                 <para>A Project adds the following functionalities:</para>
 
                 <itemizedlist>
                         <listitem><para>You need not set a master document, &kile; does this automatically.</para></listitem>
                         <listitem><para>Project files can easily be archived together by going to <menuchoice><guimenu>Project</guimenu><guimenuitem>Archive</guimenuitem></menuchoice></para></listitem>
                         <listitem><para>The <guilabel>Files and Projects</guilabel> view shows which files are included
                         in the project.</para></listitem>
                         <listitem><para>After opening a project, any file that was previously opened will be
                         restored with the original encoding and highlighting.</para></listitem>
       <listitem><para> Code completion works across all project files.</para></listitem>
       <listitem><para> Reference completion works across all project files.</para></listitem>
       <listitem><para> Citation completion works across all project files.</para></listitem>
       <listitem><para> Search in all project files.</para></listitem>
       <listitem><para> Specify custom quickbuild and &makeidx; command.</para></listitem>
                 </itemizedlist>
 
                 <para>You can find all project related commands in the <guilabel>Project</guilabel>-menu. From there you can open, close and manage your projects.</para>
 
         </sect1>
 
         <sect1 id="projects_creating">
 
                 <title>Creating a Project</title>
 
                 <para>To create a project, select <menuchoice><guimenu>Project</guimenu>
                     <guimenuitem>New Project...</guimenuitem></menuchoice>.</para>
                 <screenshot>
                   <screeninfo>Project creation window</screeninfo>
                   <mediaobject>
                     <imageobject>
                       <imagedata fileref="project-creation.png" format="PNG" />
                     </imageobject>
                     <textobject>
                       <phrase>Project creation window</phrase>
                     </textobject>
                   </mediaobject>
                 </screenshot>
                 <para>You will be
                 asked to give the following information to create your project:</para>
                 <itemizedlist>
                   <listitem>
                     <para>
                       Title of your project (<guilabel>Project title</guilabel> text field).
                     </para>
                     <para>
                       The title of the project will be used to create a name of the project file by transforming to lowercase and adding <filename role="extension">.kilepr</filename> extension.
                     </para>
                   </listitem>
                   <listitem>
                     <para>
                       A folder where the project file will be stored (<guilabel>Project folder</guilabel> text field).
                     </para>
                   </listitem>
                   <listitem>
                     <para>
                       If you want to create a new main file of the project check the <guilabel>Create a new file and add it to this project</guilabel> item.
                     </para>
                   </listitem>
                   <listitem>
                     <para>
                       When you fill out the <guilabel>Filename</guilabel> box, you have to include a relative path from where the <filename role="extension">.kilepr</filename> project file is stored (see the <guilabel>Project folder</guilabel> item).
                     </para>
                   </listitem>
                   <listitem>
                     <para>
                       Type of the created file, <guilabel>Empty File</guilabel>, <guilabel>Article</guilabel>, <guilabel>Book</guilabel>, <guilabel>Letter</guilabel>, <guilabel>Report</guilabel>, &etc; can be chosen from a visual list at the bottom of the <guilabel>File</guilabel> panel.
                     </para>
                   </listitem>
                   <listitem>
                     <para>
                       Extensions for the default files in the project can be selected using the <guilabel>Extensions</guilabel> panel. Your choice will be used to define the files that should be opened when you choose <menuchoice><guimenu>Project</guimenu><guimenuitem>Open All Project Files</guimenuitem></menuchoice> menu item and in the &kile; wizards. The extensions in the text field should be separated with spaces.
                     </para>
                   </listitem>
                 </itemizedlist>
         </sect1>
 
         <sect1 id="projects_view">
 
                 <title>The Files and Projects View</title>
 
                 <para>The <guilabel>Files and Projects</guilabel> view is a button of the sidebar menu.
                 From this view, you can see the structure of your project, its files,
                 and the name of the <literal role="extension">.kilepr</literal> file that stores the project information.
                 Adding, removing, or changing options in your project is done via
                 the <guilabel>Files and Projects</guilabel> view.</para>
 
                 <screenshot>
                         <screeninfo>The Files and Projects View</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_projectview.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>The Files and Projects View</phrase>
                         </textobject>
                         <caption><para>The Files and Projects View</para></caption>
                         </mediaobject>
                 </screenshot>
 
         </sect1>
 
         <sect1 id="projects_adding">
 
                 <title>Adding and Removing Files</title>
 
                 <para>To add a file to your project, open any &tex; file, right click on its name in the
                 <guilabel>Files and Projects</guilabel> view, and select <guilabel>Add to
                 Project</guilabel>. If you have opened multiple projects, a dialog box will pop up in which
                 you can specify to which project the file should be added.</para>
                 <!-- duplicated see next para
                 <para>If you have multiple files to be added to a project, you can select the
                 project from the <guilabel>Files and Projects</guilabel> view and right-click then select
                 <guilabel>Add Files...</guilabel>; you will then be able to select your files in a dialog box.</para>
                 -->
                 <para>You can also right-click on the project's name in the <guilabel>Files and
                 Projects</guilabel> view, and select <guilabel>Add Files...</guilabel> to bring
                 up a file selection dialog.</para>
 
                 <screenshot>
                         <screeninfo>Adding a file to a project</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="snap_projectview_add.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Adding a file to a project</phrase>
                         </textobject>
                         <caption><para>Adding a file to a project</para></caption>
                         </mediaobject>
                 </screenshot>
 
                 <para>To remove a file from a project, right-click on it and select <guilabel>Remove File</guilabel>.
                 This does <emphasis>not</emphasis> delete your file (and also does not close it), but only removes it from the list
                 of files contained in the <literal role="extension">.kilepr</literal> extension.</para>
 
                 <sect2 id="projects_archive">
 
                         <title>Archiving your Project</title>
 
                         <para>&kile; allows you to easily backup your project by storing all its files
                         into a single archive (often known as a <emphasis>tarball</emphasis>). To archive your project,
                         right-click on its name in the <guilabel>Files and Projects</guilabel> view, or select
                         <menuchoice><guimenu>Project</guimenu><guimenuitem>Archive</guimenuitem></menuchoice>.</para>
 
                         <para>By default, all files in a project are added to the archive. If you do not want to include
                         a certain file in the archive, right-click on it in the <guilabel>Files and Projects</guilabel>
                         view, and uncheck the <guilabel>Include in Archive</guilabel> option.</para>
 
                         <para>The archive operation is currently realized by executing the <command>tar</command> from the project
                         folder (where the <literal role="extension">.kilepr</literal> file is located).</para>
 
                 </sect2>
 
         </sect1>
 
         <sect1 id="projects_options">
 
                 <title>Project Options</title>
 
                 <para>&kile; has a few options related to your project that can be set. To change them,
                 right-click on the title of your project and select <guilabel>Project Options</guilabel>,
                 and you will have the option of changing:</para>
 
                 <itemizedlist>
                         <listitem><para>The title of your project.</para></listitem>
                         <listitem><para>Default file extensions.</para></listitem>
                         <listitem><para>The Master document.</para></listitem>
                         <listitem><para>The Quickbuild command.</para></listitem>
                         <listitem><para>The &makeidx; options.</para></listitem>
                 </itemizedlist>
 
 
 <!-- FIXME not working in kile, tbraun 11/3/2007
                 <sect2 id="projects_ext">
 
                         <title>Extensions for Non-Source Files</title>
 
                         <para>Non-source files are files such as pictures, PDF or &PostScript; files, etc. that are
                         to be included in the project, but are not source files with the extension <literal role="extension">.tex</literal>. You have
                         the option to use your own regular expressions to match non-source files.</para>
                 </sect2>
 -->
 
         </sect1>
 
         <sect1 id="projects_closing">
 
                 <title>Closing a Project</title>
 
                 <para>To close a project, select the <guilabel>Files and Projects</guilabel> view from
                 the vertical toolbar, right click on your project title, and then select <guimenuitem>
                 Close</guimenuitem>. This will close your project, all the files associated with your project,
                 and will also add the name of the project you just closed to <guisubmenu>Open Recent
                 Project...</guisubmenu> in the <guimenu>Project</guimenu> menu.</para>
 
         </sect1>
 
 </chapter>
 
 <chapter id="lang">
 
         <title>Document Encoding</title>
 
         <para>The &kile; editor allows you to read, convert and save text in the character encoding
         your document needs. With this it is possible, for example, to use accented characters, such
         as are commonly used in Italian or French, directly in &latex; documents.
         Selecting the encoding for your document can be done in two ways:</para>
 
         <itemizedlist>
                 <listitem><para>One way to set the document encoding is by using the submenu
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
                 Kile...</guisubmenu><guimenuitem>Editor</guimenuitem></menuchoice>,
                 where you can set the default character encoding for all files.</para>
                 <screenshot>
                         <screeninfo>Set the default character encoding</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="config-encoding.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Set the default character encoding</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
                 </listitem>
                 <listitem><para>A second way to set the encoding for a document is to choose the desired encoding
                 within the wizard to create a new document.</para></listitem>
         </itemizedlist>
 
         <para>&latex; itself only understands ASCII, which represents a very limited set of characters. Hence, it is not possible to use
         accented characters directly. To use them nevertheless, a special syntax was invented:
         such as for example <userinput>\"e</userinput> for <computeroutput>ë</computeroutput>.
         The <application>inputenc</application> package is available to help you with this. It is included
         in the preamble using <userinput>\usepackage[latin1]{inputenc}</userinput>, where the optional argument
         specifies the encoding you would like to use (nowadays in most cases <userinput>utf8</userinput>). This tells &latex;
         to translate all of the <userinput>ë</userinput>'s you wrote to <userinput>\"e</userinput>'s before
         compiling. Please refer to the <application>inputenc</application> documentation directly for more
         information. Last but not least: remember to make sure that your file is <emphasis>actually</emphasis> saved
         in the same encoding you specified for the <application>inputenc</application> package!</para>
 
         <para>This multitude of different character coding tables has created numerous problems: for example,
         you cannot write a course of Turkish in French without losing one language's special characters.
         There is general agreement that, sooner or later,
         everybody will switch to <ulink url="http://www.unicode.org">Unicode</ulink>. There
         are many implementations of Unicode, and <abbrev>UTF-8</abbrev> is the most
         successful in &Linux;; &Windows;&reg; relies instead on the more cumbersome and
         less flexible <abbrev>UCS-2</abbrev>. Most distributions have already
         begun setting their default encoding to <abbrev>UTF-8</abbrev>, and therefore you
         may be very interested in using the <userinput>utf8</userinput> argument to the
         <userinput>inputenc</userinput> package.</para>
 
         <sect1 id="ucs">
 
                 <title>The &ucs; Package</title>
                 <para>If you don't have the &ucs; package installed, you can proceed as follows:</para>
                 <itemizedlist>
                 <listitem><para>Get the &ucs; package from
                 <ulink url="http://www.ctan.org/tex-archive/macros/latex/contrib/unicode/">CTAN</ulink>.
                 </para></listitem>
                 <listitem>
                 <para>To install it, unpack the downloaded file and place it in a folder listed
                  in your $<envar>TEXINPUTS</envar> environment variable. This can also be set inside &kile;.</para>
                 </listitem>
                 </itemizedlist>
 
 <programlisting>\usepackage{ucs}
 \usepackage[utf8]{inputenc}</programlisting>
 
         </sect1>
 
         <sect1 id="xelatex">
 
                 <title>XeLaTeX</title>
 
                 <para>If you are using <userinput>XeLaTeX</userinput>, you can simply load the
                 <userinput>xltxtra</userinput> package. It will additionally load all the required packages.</para>
                 <programlisting>\usepackage{xltxtra}</programlisting>
 
         </sect1>
 
         <sect1 id="cjk">
 
                 <title>&cjk; Support</title>
 
                 <para>Adding support for ideographic languages is quite tricky. However, once
                 you are done with it, it will work quite well. Other than installing packages,
                 there is some extra configuration work to do.</para>
 
                 <tip><para>Your &Linux; distribution might already have a &cjk; (Chinese, Japanese,
                 Korean) package ready for you, so you might be saved the hassle of manually
                 installing everything. Do check before going forward!</para></tip>
 
                 <para>There is the possibility of using the &ucs; package in order to write
                 short snippets of &cjk; text, but that option is seriously limited as it does
                 not handle, among other things, newlines. Instead, we will install the complete
                 &cjk;-&latex; package and make it work for both &latex; and &pdflatex;. A lot
                 of this material has been inspired by <ulink url="http://www.ece.uci.edu/~chou/">Pai
                 H. Chou</ulink>'s <ulink url="http://www.ece.uci.edu/~chou/unicode-tex.html">page
                 about how to setup &pdflatex;</ulink>.</para>
 
                 <orderedlist>
 
                 <listitem><para>Download the <ulink
                 url="http://www.ctan.org/tex-archive/help/Catalogue/entries/cjk.html">&cjk;</ulink>
                 package. Copy its unpacked files to an appropriate subfolder of
                 $<envar>TEXMF</envar>, just as you did with the &ucs; package
                 before (see <xref linkend="ucs" role="select: title pageabbrv"/>). The files will be unpacked in a
                 <filename>CJK/X_Y.Z</filename> folder; it is not important that you
                 take them out, though it will probably be tidier and easier for you to
                 maintain.</para></listitem>
 
                 <listitem><para>Now you have to download a font that supports all the &cjk; characters
                 you need. You can choose any <literal role="extension">*.ttf</literal> file that
                 covers them, but in this walkthrough we will use <ulink
                 url="ftp://ftp.wu-wien.ac.at/pub/www/Netscape/communicator/extras/fonts/windows/Cyberbit.ZIP">Cyberbit</ulink>.
                 Unzip the file and rename <filename>Cyberbit.ttf</filename> to
                 <filename>cyberbit.ttf</filename>, since uppercase might confuse your system.</para>
                 <para>Place <filename>cyberbit.ttf</filename> in a folder together with
                 <ulink url="http://delloye.free.fr/Unicode.sfd"><filename>Unicode.sfd</filename></ulink>,
                 and generate the <literal role="extension">*.tfm</literal> and
                 <literal role="extension">*.enc</literal> files with the command
                 <userinput><command>$ ttf2tfm cyberbit.ttf -w cyberbit@Unicode@</command></userinput>.
                 For some reason, sometimes this does not produce the hundreds
                 of files it should. Should that happen in your case, you can download both
                 <ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-tfm.tgz"><literal
                 role="extension">*.tfm</literal></ulink> and
                 <ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-enc.tgz"><literal
                 role="extension">*.enc</literal></ulink> files.</para>
                 <para>Place the <literal role="extension">*.tfm</literal> files in an
                 appropriate folder, say <filename>$<envar>TEXMF</envar>/fonts/tfm/bitstream/cyberbit/</filename>;
                 the <literal role="extension">*.enc</literal> files may be installed in
                 <filename>$<envar>TEXMF</envar>/pdftex/enc/cyberbit/</filename>.</para></listitem>
 
                 <listitem><para>Now we need a map file to connect the <literal
                 role="extension">*.enc</literal> files to the font. Download <ulink
                 url="http://delloye.free.fr/cyberbit.map"><filename>cyberbit.map</filename></ulink>
                                 and install it in <filename>$<envar>TEXMF</envar>/pdftex/config/</filename>.</para></listitem>
 
                 <listitem><para>Download another file, <ulink
                 url="http://delloye.free.fr/c70cyberbit.fd"><filename>c70cyberbit.fd</filename></ulink>,
                 and place it in an appropriate folder. You may choose, for example,
                 <filename>$<envar>TEXMF</envar>/tex/misc/</filename>.</para></listitem>
 
                 <listitem><para>The last file we have to generate is a &PostScript; Type 1
                 font, necessary to read &DVI; files generated with &latex;. Run the command
                 <userinput><command>$ ttf2pfb cyberbit.ttf -o cyberbit.pfb</command></userinput>, and copy the
                 resulting <filename>cyberbit.pfb</filename> to a folder such as
                 <filename>$<envar>TEXMF</envar>/fonts/type1/cyberbit/</filename>.</para></listitem>
 
                 <listitem><para>Let's now place <filename>cyberbit.ttf</filename> among the fonts
                 where &latex; can find it. You could place it in a folder named
                 <filename>$<envar>TEXMF</envar>/fonts/truetype/</filename>.</para></listitem>
 
                 <listitem><para>Check the configuration file you find at
                 <filename>$<envar>TEXMF</envar>/web2c/texmf.cnf</filename>, and make sure that the
                 line mentioning <envar>TTFONTS</envar> is uncommented and points to
                 the folder where you saved <filename>cyberbit.ttf</filename>.</para></listitem>
 
                 <listitem><para>To make it possible for &pdflatex; to use your &cjk;
                 fonts, it is necessary that you add a line in the configuration file
                 <filename>$<envar>TEXMF</envar>/pdftex/config/pdftex.cfg</filename>. Add
                 <userinput>map +cyberbit.map</userinput> in the file to complete the
                 configuration for &pdflatex;.</para></listitem>
 
                 <listitem><para>To configure &latex; so that you can produce &DVI;
                 files with &cjk; characters, you have to add a line in file
                 <filename>ttfonts.map</filename>. The file might be in a folder named
                 <filename>$<envar>TEXMF</envar>/ttf2pk/</filename>, but you will probably have to look
                 for it. Append the line <userinput>cyberbit@Unicode@ cyberbit.ttf</userinput>
                 to it.</para></listitem>
 
                 <listitem><para>Now, you only have to run <userinput><command>texhash</command></userinput>
                 and the system should be ready.</para></listitem>
 
                 </orderedlist>
 
                 <para>To test whether your configuration is correct, you can try to compile
                 <ulink url="http://www.math.nus.edu.sg/aslaksen/cs/sample-utf8.tex">this test
                 file</ulink>.</para>
 
                 <sect2>
                         <title>&cjk; Troubleshooting</title>
 
                         <para>There are many things that can go wrong when adding &cjk;
                         support manually. If something seems not to work, the following
                         checklist might help you.</para>
 
                         <itemizedlist>
 
                         <listitem><para>Obviously, since you run &latex; as a user and
                         not as root, you must <emphasis>allow</emphasis> ordinary users
                         to access the new files. Make sure all folders and files are
                         accessible using the <command>chmod</command> command.</para></listitem>
 
                         <listitem><para>If &latex; writes a &DVI; without problems, but you
                         cannot view it, it is almost certainly because of some problems in the
                         automatic generation of <literal role="extension">*.pk</literal>
                         fonts. They are supposed to be generated on the fly when viewing a
                         &DVI; file, but this might fail for a number of reasons: double-check
                         <filename>ttfonts.map</filename> for your custom line first. However,
                         it might happen that your <command>ttf2pk</command> command, which
                         is usually invoked by the &DVI; viewer, has been compiled
                         <emphasis>without</emphasis> support for the
                         <application>kpathsea</application> libraries. If this is the case,
                         <userinput><command>ttf2pk</command> <option>--version</option></userinput>
                         will make no mention of <application>kpathsea</application>. As support for
                         these libraries is necessary, you might have to find a new package, or
                         recompile <application>FreeType 1</application> yourself.</para></listitem>
 
                         </itemizedlist>
 
                 </sect2>
 
 
                 <sect2>
 
                         <title>How do I input &cjk; in Unicode?</title>
 
                         <para>There are a number of different input engines, and the choice can
                         depend also on personal preference. The author uses <ulink
                         url="http://www.scim-im.org/projects/skim"><application>Skim</application></ulink>,
                         a port to &kde; of the <ulink
                         url="http://www.scim-im.org"><application>Scim</application></ulink>
                         engine. Refer to your distribution's documentation to learn how to
                         install these programs. Configuration of such programs can be tricky
                         too, in the case of <application>Skim</application> you will have to
                         define an environment variable <userinput><envar>XMODIFIERS</envar>="@im=SCIM"</userinput>
                         <emphasis>before</emphasis> starting <application>X</application>.</para>
 
                 </sect2>
 
         </sect1>
 
 </chapter>
 
 &include-section-scripting;
 
 <chapter id="help">
 
         <title>Help</title>
 
         <sect1 id="help_documents">
 
                 <title>Help Documents</title>
 
                 <para>&latex; is a rather sophisticated system, where basic features
                 can be expanded by a great variety of additional packages.
                 &kile; provides numerous different ways to aid the user.</para>
 
                 <para>
                         The <menuchoice><guimenu>Help</guimenu> <guisubmenu>LaTeX Documentation</guisubmenu></menuchoice> submenu includes links on documentation for all the included packages and an additional &latex;
                 reference.
                 </para>
 
                 <variablelist>
 
                 <varlistentry>
                 <term><guimenu>Documentation Browser</guimenu></term>
                 <listitem><para>A handy tool to browse all &latex; topics. Please install &latex; help packages for your distribution if you need the full-fledged documentation compendium.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term><guimenu>LaTeX</guimenu></term>
                 <listitem><para>A full unofficial reference for &tex; and friends. This is not
                 only a description of all programs, but some important packages are also
                 mentioned. It also includes a full reference manual of &latex;
                 commands&mdash;ideal for looking up a particular piece of formatting
                 while writing a document. As this document is really extensive,
                 it is referenced in &kile; by three bookmarks.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term><guimenu>LaTeX Commands</guimenu></term>
                 <listitem><para>Another alphabetical index of the most common
                 &latex; commands.</para></listitem>
                 </varlistentry>
 
                 <varlistentry>
                 <term><guimenu>LaTeX Environments</guimenu></term>
                 <listitem><para>An alphabetical index of the most common
                 &latex; environments.</para></listitem>
                 </varlistentry>
 
                 </variablelist>
 
         </sect1>
 
         <sect1 id="help_contextsentitive">
 
                 <title>Context Sensitive Help</title>
 
                 <para>&kile; also supports a context sensitive help, which is called
                 with <keycombo action="simul">&Ctrl;&Alt;<keycap>H</keycap></keycombo>,<keycap>K</keycap>.
                 In <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>Kile</guimenuitem><guilabel>Help</guilabel></menuchoice>
                 you can choose whether you want to use &kile;'s &latex; reference or the
                 help system of &tetex;/&texlive;, which is the default setting.</para>
 
                 <screenshot>
                         <screeninfo>Bullets</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="config-userhelp.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Bullets</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
         </sect1>
 
         <sect1 id="help_search">
 
                 <title>Searching for Keywords</title>
 
                 <para>It is not always easy to find the right document as &tetex;/&texlive;
                 ships with a huge number of help documents. In order to facilitate this process, &tetex;/&texlive;
                 provides a tiny program called <application>texdoctk</application>.
                 It provides a database of all the help documents, for which &kile; offers a user-friendly
                 interface.</para>
 
                 <screenshot>
                         <screeninfo>Bullets</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="dialog-docbrowser1.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Bullets</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>All the documents are grouped into categories. Additionally,
                 one can search for package names or keywords.
                 &kile; will then show only the help documents matching the search string.</para>
 
                 <screenshot>
                         <screeninfo>Bullets</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="dialog-docbrowser2.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Bullets</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>A mouse double-click or the <keycap>Space</keycap> key will start a
                 viewer for the selected document. This can be an arbitrary document, not only a
                 &DVI;, PS, PDF or &HTML; document. &kile; takes the &kde; settings into account in order to
                 start an appropriate viewer.</para>
 
 
         </sect1>
 
         <sect1 id="help_userdefined">
 
                 <title>User Defined Help</title>
 
                 <para>Besides this static &tetex;/&texlive; documentation, &kile; also supports
                 a more flexible variable way for help documents. In the <guimenu>Help</guimenu>
                 menu &kile; has a special <guimenu>User help</guimenu>
                 submenu, where the user can add documents of his or her own choice.
                 These can be the most important documents of the &tetex;/&texlive; documentation, or even
                 self-written documents. It is also possible to enter URLs.</para>
 
                 <para>Go to
                 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
                 <guimenuitem>Kile</guimenuitem><guilabel>Help</guilabel></menuchoice>
                 and choose the <guibutton>Configure</guibutton> button
                 to configure this <guimenu>User help</guimenu> menu. You can add,
                 remove or move menu entries around, and insert separators to optimize
                 the structure of the menu.</para>
 
                 <screenshot>
                         <screeninfo>Dialog: configure user defined help entries</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="dialog-userhelp.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Dialog: configure user defined help entries</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>Pressing the <guibutton>Add</guibutton> button will open
                 another dialog, where you can edit the name of the menu entry,
                 and choose the corresponding file or &URL;. The second button to the right of the text field launches
                 &konqueror;, which can be used to determine the correct &URL;.</para>
 
                 <screenshot>
                         <screeninfo>Dialog: add a new helpentry</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="dialog-addhelp.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Dialog: add a new helpentry</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
                 <para>After finishing the configuration, all the entries will appear in the <guimenu>Help</guimenu>
                 menu of &kile; as a special menu entry <guimenu>User help</guimenu>.</para>
 
                 <screenshot>
                         <screeninfo>Userhelp menu</screeninfo>
                         <mediaobject>
                         <imageobject>
                         <imagedata fileref="menu-userhelp.png" format="PNG" />
                         </imageobject>
                         <textobject>
                         <phrase>Userhelp menu</phrase>
                         </textobject>
                         </mediaobject>
                 </screenshot>
 
         </sect1>
 
 </chapter>
 
 <chapter id="credits">
 
         <title>Credits and License</title>
 
         <para>&kile; is an open-source user-friendly &latex; / &tex; source code editor. It runs on systems
         that have the &kde; Desktop Environment installed. &kde; is available for several architectures
         including &Linux; and other Unix-like systems.</para>
 
         <para>Many thanks are owed to the people who strive to continue the &kile; project and to those
         who sacrifice numerous hours of their time to develop tools we can all use under the &GNU; license.
         Up-to-date information about contributors can be found in
         the <guimenuitem>About &kile;</guimenuitem> dialog from the <guimenu>Help</guimenu> menu.
         </para>
 
         <para>Many thanks to all those involved!</para>
 
 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 
         &underFDL;              <!-- FDL: do not remove -->
         &underGPL;              <!-- GPL License -->
 
 </chapter>
 
 
 &documentation.index;
 
 </book>
 
 <!--
 Local Variables:
 mode: xml
 sgml-minimize-attributes:nil
 sgml-general-insert-case:lower
 sgml-indent-step:0
 sgml-indent-data:nil
 End:
 
 vim:tabstop=2:shiftwidth=2:expandtab
 -->