diff options
Diffstat (limited to 'doc/en/index.docbook')
| -rw-r--r-- | doc/en/index.docbook | 3720 |
1 files changed, 3720 insertions, 0 deletions
diff --git a/doc/en/index.docbook b/doc/en/index.docbook new file mode 100644 index 0000000..5ec2f64 --- /dev/null +++ b/doc/en/index.docbook @@ -0,0 +1,3720 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.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 kde "<acronym>KDE</acronym>"> + <!ENTITY kdvi "<application>KDVI</application>"> + <!ENTITY dvipng "<application>dvipng</application>"> + <!ENTITY kghostview "<application>KGhostView</application>"> + <!ENTITY kpdf "<application>KPDF</application>"> + <!ENTITY postscript "<application>PostScript</application>"> + <!ENTITY makeidx "<application>makeidx</application>"> + <!ENTITY kate "<application>Kate</application>"> + <!ENTITY cjk "<abbrev>CJK</abbrev>"> + <!ENTITY ucs "<abbrev>ucs</abbrev>"> + <!ENTITY url "<acronym>URL</acronym>"> + <!ENTITY kappname "&kile;"> + <!ENTITY package "kdeextragear-2"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book 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>zenith@chemeng.ntnu.no</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> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +<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> +<holder>Holger Danielsson</holder> +</copyright> + +<copyright> +<year>2007</year> +<holder>Thomas Braun</holder> +</copyright> + +<copyright> +<year>2007</year> +<holder>Michel Ludwig</holder> +</copyright> + +<date>November 19, 2007</date> +<releaseinfo>2.0</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 will be required to have the following components + installed on your system:</para> + + <itemizedlist> + <listitem><para>Trinity Desktop environment (&tde;): + &tde; is a popular open-source desktop environment.</para></listitem> + <listitem><para><ulink url="http://www.trolltech.com/products/qt/">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>The &kile; project includes several binary packages of &kile; for different distributions that can be easily + installed and run without having to compile; check out the <ulink url="http://kile.sourceforge.net/">&kile; + homepage</ulink>.</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>Need answers about &kile;? Are you stuck with your compile? Want to see a new + feature? The preferred way to ask technical questions or 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 functionalities of &latex; in a graphical interface, giving you easy, + immediate, and customized access to all programs for &latex; codecompletion, compiling, postprocessing, + debugging, conversion and viewing tools; you also get very handy wizards, a &latex; + reference and a powerful project management.</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 him layout his work professionally, obtaining a work similar + to a typesetter's; the typesetter is the professional that styles a document's look according to + specifications for the type of document. + &latex; was created by Leslie Lamport to give authors an automatic typesetter, especially when + it came to the expensive and painstaking typesetting of mathematical formulas and expressions, + that <emphasis>by no chance</emphasis> are enclosed in dollar signs in &latex;. + Today, word-processing programs let any user be the typesetter; but what you often want + is a document that looks good, not one that you spent hours on to make it look good. + &latex; takes that burden, and lets you think of the document, not of 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 traditions 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 as an hissing cat; the IPA symbol is /ç/. Many people report the different pronunciation + of <emphasis>ach</emphasis> (IPA symbol /x/), but I have personally asked some Greeks, and can + confirm the first version. You should be aware that a lot of people mispronounce /teks/ or /tek/.</para> + <para>Last, in &latex; the first L<superscript>A</superscript> is pronounced as + <emphasis>lay</emphasis>: the idea is that, 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 as XML, used for + many types of documents (including the one you are reading), or HTML, used for web + pages. The general idea is about having specially wrapped keywords, called <emphasis> + tags</emphasis>, that tell a program (a word processor, a web browser, or the &latex; + compiler) how to present text. &kile; offers you a good number of such tags in the + menu <guimenu>LaTeX</guimenu> in the menu bar.</para> + + <para>While we will try to give you a good idea of what &latex; is, this is not The Definitive + Book on &latex;. If you want to learn &latex; well, you may want to loan a book in your + library. The writer has had a good experience with A Guide to &latex; by H. Kopka + and P. W. Daly, and still keeps it on the shelf.</para> + + <para>As other markup languages, &latex; contains a <emphasis>preamble</emphasis>, which + sets global commands, such as paper size, page numbering, dimensions of the text on the page, + and a <emphasis>body</emphasis>, that contains the document text; the preamble contains + at least the <userinput>\documentclass</userinput> command, and precedes the body, that + starts with the command <userinput>\begin{document}</userinput>, and is quite predictably + concluded by 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 systems standard + encoding. Modern systems now move more and more to UTF-8 as the standard encoding. + If you can, use 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 checkbox 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, that can automatically do those nasty + indentations that nobody really remembers.</para></listitem> + <listitem><para>Beamer,HA-Prosper: create nice presentations in PDF with a superior look and all + &latex; power.</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> + </itemizedlist> + + <para>New users need not to worry, this list is just a brief description of features, + and more attention will be paid to complete these tasks in detail later in + <xref linkend="quickstart"/>.</para> + + </sect2> + + <sect2 id="intro_highlight"> + + <title>Syntax Highlighting</title> + + <para>&kile; is similar to 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 spot easily problem areas: for example, if you see major + areas of text turned green, it is likely that you forgot closing a math environment somewhere; + you would have noticed anyway by how crappy the output file would have looked, but + highlighting really saves you time and frustration.</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), you can click the middle- + mouse button in the DVI 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 file is associated with + the editor, so when you click on the DVI 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 DVI 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> + <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 you have code errors.</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 &kdvi; 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 source.</para></listitem> + <listitem><para><guibutton>Next error</guibutton>: jumps forward through + <literal role="extension">.log</literal> file and + highlights errors in 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>View DVI</guibutton>: launches DVI viewer.</para></listitem> + <listitem><para><guibutton>DVI to PS</guibutton>: converts a DVI to a &postscript; (PS).</para></listitem> + <listitem><para><guibutton>View PS</guibutton>: launches &postscript; (PS) viewer.</para></listitem> + <listitem><para><guibutton>PDFLaTeX</guibutton>: runs &pdflatex; on the active document.</para></listitem> + <listitem><para><guibutton>View PDF</guibutton>: launches the PDF viewer.</para></listitem> + <listitem><para><guibutton>DVI to PDF</guibutton>: converts a DVI to a PDF.</para></listitem> + <listitem><para><guibutton>PS to PDF</guibutton>: converts a PS to a PDF.</para></listitem> + <listitem><para><guibutton>View HTML</guibutton>: views HTML created.</para></listitem> + <listitem><para><guibutton>Kdvi Forward Search</guibutton>: jump to page 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>label</guilabel> is used to insert items to 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> + <listitem><para><guilabel>cite from ViewBib</guilabel>: ask the ViewBib tool for all selected references and insert them. + Currently this is only avaible with <ulink url="http://user.digisurf.com.au/~thachly/kbib/">&kbib;</ulink> as ViewBib tool.</para></listitem> + </itemizedlist> + + <screenshot> + <screeninfo>The <guilabel>Label</guilabel> drop-down menu</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="snap_ref_choose.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>The <guilabel>Label</guilabel> drop-down menu</phrase> + </textobject> + <caption><para>The <guilabel>Label</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 specialised editors is recommened. + The author has made good experience with &kbibtex; and &kbib;. 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> + + <screen><userinput> + \documentclass[12pt]{article} + \begin{document} + Here is a bunch of text coded in \LaTeX. + \end{document}</userinput></screen> + + <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 &kdvi; 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 + than 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 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>, + <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>View DVI</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>View + DVI</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"/>). At step 7, after + clicking <guibutton>View DVI</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 &kdvi;</title> + + <para>The forward search functions allow you to jump from your + editor directly into the associated position of the &DVI; + 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>Kdvi Forward Search</guilabel> to jump to the associated position + in the DVI viewer window.</para> + </sect1> + + <sect1 id="quick_inverse"> + + <title>Inverse Search between &kile; and &kdvi;</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 &kdvi;'s window with the &MMB; (on some systems, + when you do not have a three-button mouse, you can simultaneously + use the <mousebutton>left</mousebutton> and the + <mousebutton>right</mousebutton> button). After that kile load the &latex; source file and jump 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>&kdvi; knows which editor you would like to use.</para></listitem> + </itemizedlist> + + <para>With this feature of &kdvi;, a middle mouse click in the DVI document will + result in &kile; opening the corresponding &latex; document and attempt to go to the + corresponding line. Remember to tell &kdvi; to use &kile; as a text editor, in &kdvi;'s + menu item <menuchoice><guimenu>Settings</guimenu><guimenuitem>DVI Options...</guimenuitem></menuchoice>.</para> + + <screenshot> + <screeninfo>Configuring &kdvi;</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="snap_kdvi_settings.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Configuring &kdvi;</phrase> + </textobject> + <caption><para>Configuring &kdvi;</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 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>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> + </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"/>).</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 your 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 known 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 + listed in <xref linkend="templ_wiz"/>.</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 making an attractive, catchy poster. You can get a + template for A0 posters at <ulink url="http://www.stats.ox.ac.uk/~marchini/a0poster.html">Jonathan Marchini's + home page</ulink>, but many more are available. Remember that you will need the <filename>a0poster</filename> + package, which is normally not in standard tex distributions included. Download it from + <ulink url="http://www.ctan.org/tex-archive/macros/latex/contrib/a0poster/">here</ulink> and place it in the same directory 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 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 highlighted also in a different color.</para> + + </sect1> + + <sect1 id="editing_bullets"> + + <title>Bullets</title> + + <para>Many wizards can insert optional bullets, a special kind of bookmarks within the text. The + menu entries <menuchoice><guimenu>Edit</guimenu><guisubmenu>Bullets</guisubmenu></menuchoice> or + the corresponding keyboards 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.</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.</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 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> + + </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 hole line.But &kile; offers a + faster way with its own delete commands. + Under <menuchoice><guimenu>Edit</guimenu><guisubmenu>Delete</guisubmenu></menuchoice> + you will find 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 was already 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, he 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 case 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>&Shift;<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 environment, 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>&</keycap> beneath each other. &kile; tries + to support this. If you press <keycombo>&Shift;&Alt;<keycap>&</keycap></keycombo>, + &kile; will look for the next tab in the row above. Although his which may not 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; extended + 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;<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 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 the 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> + + </sect1> + + <sect1 id="complete_environment"> + + <title>Environments</title> + + <para>The <emphasis>command mode</emphasis> is not useful to complete environments. + You always have to type some letters of <userinput>\begin</userinput>, and invoking + the completion mode will result in a huge list of environments tags. On the other + hand, environments are so often used that &kile; offers a special mode to complete + environments. Forget the opening tag and write, for example, <userinput>eq</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;<keycap>Space</keycap></keycombo>, + the opening tag is automatically added and you will see <userinput>\begin{eq}</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 theses 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> for example.</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> + + </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 before.</para> + + <para>If you want to turn this mode on or off, go to + <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> + <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>. + In this configuration dialog you can also change the threshold at which + the completion box pops up.</para> + + </sect2> + + </sect1> + + <sect1 id="complete_own_files"> + + <title>Writing Own Completion Files</title> + + <para>The specification of the completion file format can found in the <ulink url="http://websvn.kde.org/*checkout*/tags/kile/2.0/src/README.cwl"> + CWL file format specification</ulink>. + </para> + + <para> + Completion files can be installed in a user's home directory under the <filename>~/.trinity/share/apps/kile/complete/<mode>/</filename> + subdirectory, where <parameter><mode></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_graphics"> + + <title>Include Graphics</title> + + <para>The <guilabel>Include Graphics</guilabel> dialog makes insertion of + graphics as easy as possible. Please take a look at + <xref linkend="build_graphics"/> and <xref linkend="build_epsgraphics"/> 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, 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>General</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 either traditional &latex; or &pdflatex;. + Please remember that &pdflatex; can also create DVI output, + not only PDF.</para></step> + + <step><para>You can choose whether the filename should be taken + relative. This is the preferred way, when you use the + <userinput>\graphicspath</userinput> command.</para> + + <para>By default graphics files have to be in the same + folder than 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>, + like:</para> + +<programlisting> + \graphicspath{{/path/to/my/graphics}{other/path/to/more/graphics}} +</programlisting> + + <para>and check this option, &kile; with 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 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></step> + + <step><para>Your last choice is whether to embed this graphics into a + figure environment. If you decide to do so, you can also insert a + caption and a label. 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> + </procedure> + + </sect1> + + <sect1 id="wizard_array"> + + <title>Array Wizard</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 <guimenu>Wizard</guimenu> menu. It contains + <guimenuitem>Tabular</guimenuitem> and <guimenuitem>Array</guimenuitem> (used in math environments). + You will then have a matrix-formed 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>The <guimenuitem>Tabbing</guimenuitem> option will display a simpler menu + to set up a tabbing environment. In all these environments, you can easily set the + number of rows and columns, along with other specific options.</para> + </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> will suggest the most + popular rearrangements, but you are free to do your own choice. Work is done + by the programs <command>pstops</command> and <command>psselect</command>, which + you will find 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 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 + &kghostview; 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 portrait 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 even 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="statistics"> + <title>Document Statistics</title> + + <para>The statistics dialog gives you an statistical overview for a selection, + a document or an hole project. It includes the number of words, &latex; + commands/environments and also includes the number of characters for each type. + The statistical numbers can be copied as text or as a nice formatted &latex; tabular + to the clipboard. If you want to get statistics for the hole project you can use + <menuchoice><guimenu>File</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, e. g. K\"uhler gives one word and one command, + with six resp. two characters. But there are other combinations in which parts of commands + are counted as words and vice versa. It has also to be beared in mind that the algorithm + was developed and tested for languages similiar to english or german. + So don't take the numbers for granted. If you have to make an report with an + exact numbers of words or characters, make some tests 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, + 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 avaible:</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. Similiar 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 + would exceed 30 items, the item wit the lowest count will get 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 definitions.tex from the kile source package. + Additionaly 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 so 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 calles &latex; and &dvipng;) create the icons. After copying them to + <userinput>$HOME/.trinity/share/apps/kile/mathsymbols/user/</userinput> and restarting kile you can use your own symbols. + </para> + <para> + The following commands are defined in definitions.tex: + <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: + <screen><userinput> + \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} + </userinput></screen> + </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> + + <screen><userinput> + \begin{thebibliography}{50} + \bibitem{Simpson} Homer J. Simpson. \textsl{Mmmmm...donuts}. + Evergreen Terrace Printing Co., Springfield, SomewhereUSA, 1998 + \end{thebibliography)</userinput></screen> + + <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> + + <screen><userinput> + My thesis, about the philosophy of The Simpsons\copyright + comes from my favorite book \cite{Simpson}.</userinput></screen> + + <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. On the <guilabel>Edit</guilabel> + toolbar click on the second drop-down box (usually it reads <guilabel>label</guilabel>) and select + <guilabel>cite</guilabel>. 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,<menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh + Structure</guimenuitem></menuchoice> or press <keycap>F12</keycap>.</para> + + <para>The final product 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>The easiest way to work with <userinput>\bibitem</userinput> and + <userinput>\cite</userinput> is to use the toolbar drop-down box marked + <guilabel>cite</guilabel>. When you select a citation to insert, you will be given the list of + <userinput>bibitem</userinput>s you have created so far, and will be able to select the + reference from the list. &kile; can also work together with &bibtex; editor applications, + such as &kbibtex; to help make citations easier.</para> + + </sect1> + + <sect1 id="latex_usertags"> + + <title>User-Defined Tags</title> + + <para>&kile; gives you the ability to make your own tags. A tag is similar + to a shortcut that launches some command or writes frequently-used text. + For example, Joe Sixpack uses often the sentences <userinput>I prefer \LaTeX\ + to \TeX\</userinput> and <userinput>What would I do without Linux?</userinput>. + To create user-defined tags to write these sentences, he would access + <menuchoice><guimenu>LaTeX</guimenu><guisubmenu>User Tags</guisubmenu><guimenuitem>Edit + User Tags...</guimenuitem></menuchoice>; this will present him a dialog where he can create + his own user-defined tags.</para> + <screenshot> + <screeninfo>The Edit User Tags Dialog</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="snap_editusertag.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>The Edit User Tags Dialog</phrase> + </textobject> + <caption><para>The Edit User Tags Dialog</para></caption> + </mediaobject> + </screenshot> + + <screenshot> + <screeninfo>Invoking a User-Defined Tag</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="snap_usertag.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Invoking a User Defined Tag</phrase> + </textobject> + <caption><para>Invoking a User Defined Tag</para></caption> + </mediaobject> + </screenshot> + + <para>He would probably give each tag a name that can clearly identify it. The name you give your tag + is entered in the section marked <guilabel>Menu item</guilabel>, and the text of frequently-used command + should be entered into the section labeled <guilabel>Value</guilabel>. Once the commands are entered, + he can use them quickly using the shortcut <keycombo>&Ctrl;&Shift;<keycap>1</keycap></keycombo> for + the first tag to enter <userinput>I prefer \LaTeX\ to \TeX\</userinput> and <keycombo>&Ctrl;&Shift; + <keycap>2</keycap></keycombo> to enter <userinput>What would I do without Linux?</userinput>.</para> + + <sect2 id="latex_usertags_uc"> + + <title>Placeholders in User-Defined Tags</title> + + <para>There are some placeholders you can use in user-defined tags: + they are <userinput>%B</userinput>, <userinput>%C</userinput>, <userinput>%M</userinput> and + <userinput>%S</userinput>.</para> + + <itemizedlist> + <listitem><para><userinput>%B</userinput>: will be replaced by a bullet.</para></listitem> + <listitem><para><userinput>%C</userinput>: this is where the cursor will be placed after the insertion of a + user-defined tag.</para></listitem> + <listitem><para><userinput>%M</userinput>: this stands for marked text; the selected text is + inserted in its place when inserting user-defined tags.</para></listitem> + <listitem><para><userinput>%S</userinput>: will be replaced by the source file's name without file extension.</para></listitem> + </itemizedlist> + + <para>To show you how this works let's say for example that we have a user-defined tag, + which contains the value <userinput>\bfseries{%M}%C</userinput>, and I have a selection of text + highlighted in my document that we want to turn into bold text. So, we highlight the + phrase <userinput>I love Fridays</userinput>, apply our user-defined tag by pressing + <keycombo>&Ctrl;&Shift;<keycap>1</keycap></keycombo>, and we get the text + <userinput>\bfseries{I love Fridays}</userinput>, with the cursor + placed at the end of the text.</para> + + </sect2> + + </sect1> + +</chapter> + +<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 &kdvi;, &kghostview;, &kpdf; 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 by default turned on 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> + + <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>Other</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 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 directly a + DVI 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 program 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 seven predefined configurations:</para> + + <itemizedlist> + <listitem><para><application>LaTeX+DVI (embedded viewer)</application></para></listitem> + <listitem><para><application>LaTeX+DVI (KDVI)</application></para></listitem> + <listitem><para><application>LaTeX+PS (embedded viewer)</application></para></listitem> + <listitem><para><application>LaTeX+PS (KGhostView)</application></para></listitem> + <listitem><para><application>PDFLaTeX+PDF (embedded viewer)</application></para></listitem> + <listitem><para><application>PDFLaTeX+PDF (KGhostView)</application></para></listitem> + <listitem><para><application>PDFLaTeX+PDF (KPDF)</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 mathematic + environments, which sometimes may be difficult to write. &kile; offers a very fast way + to do this. No selection is needed, only 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 compile correctly 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 of 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, in case 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 + 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 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 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 graphic 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 graph is made of; it looks good even when magnified beyond its + default size, and suits best diagrams and vectorial graphic 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 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 proceed 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 its 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, + like 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 systems 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 file. See the yours &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> like 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 separated 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 open 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>Presently, &kdvi; supports continuous updating of the viewed DVI file, but + &kghostview; is not as perfect: to update the document after compiling, you will have + to change page, and the number of pages will not be changed in &kghostview;'s visualization.</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 in + it will make &kile; bring up the included file in the editor window.</para> + + <para>The hierarchy tree has also 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_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>Bookmark</guimenu><guimenuitem>Toggle + Bookmark</guimenuitem></menuchoice>.</para> + + <para>To remove all your bookmarks, select <menuchoice><guimenu>Bookmarks</guimenu> + <guimenuitem>Clear Bookmarks</guimenuitem></menuchoice>.</para> + + <para>Please note that currently the bookmarks are not saved after exiting &kile;.</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>Build</guimenu><guisubmenu>Other</guisubmenu><guimenuitem>Archive</guimenuitem></menuchoice></para></listitem> + <listitem><para>The <guilabel>Files and Project</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 highlightning.</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> + + </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>. You will be + asked to give the following information to create your project:</para> + <itemizedlist> + <listitem><para>Title of your project.</para></listitem> + <listitem><para>Name of the project file with <literal role="extension">.kilepr</literal> extension.</para></listitem> + <listitem><para>Filename.</para></listitem> + <listitem><para>Type of file creating: Empty Document, Article, Book, Letter, Report, ....</para></listitem> + </itemizedlist> + + <para>When you fill out the <guilabel>filename</guilabel> box, you have to include a relative + path from where the <literal role="extension">.kilepr</literal> project file is stored to the file.</para> + + </sect1> + + <sect1 id="projects_view"> + + <title>The File and Project View</title> + + <para>The <guilabel>File and Project</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>File and Projects</guilabel> view.</para> + + <screenshot> + <screeninfo>The File and Project View</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="snap_projectview.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>The File and Project View</phrase> + </textobject> + <caption><para>The File and Project 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 Project</guilabel> view, and select <guilabel>Add to + Project</guilabel>. If you have multiple projects open, a dialog box will ask + you which project the file has to be added to.</para> + + <para>If you have multiple files to be added to a project, you can select the + project from the <guilabel>Files and Project</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 + Project</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> + + </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>The Master document.</para></listitem> + <listitem><para>The Quickbuild command.</para></listitem> + <listitem><para>The &makeidx; options.</para></listitem> + </itemizedlist> + + <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 <emphasis>tarball</emphasis>). To archive your project + right-click on its name in the <guilabel>Files and Project</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 Project</guilabel> + view, and uncheck the <guilabel>Include in Archive</guilabel> option.</para> + + <para>Archive commands are simple shell commands that are executed from the project + folder (where the <literal role="extension">.kilepr</literal> file is located).</para> + + </sect2> + +<!-- 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 Project</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 set the text to the encoding + your document needs. This allows you to use non-standard letters and symbols; + you can use, for example, accented characters for Italian or French. + Selecting the encoding for your document can be done in three ways:</para> + + <itemizedlist> + <listitem><para>One way to set the encoding is to use the <guilabel>Set encoding</guilabel> combo + box, located at the bottom of the <guilabel>Open File</guilabel> sidebar view.</para></listitem> + <listitem><para>Another way is 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 third way to set the encoding for a document is to set the option + when you use the wizard to create a new document.</para></listitem> + </itemizedlist> + + <para>&latex; itself understands only ASCII, a very limited set of characters, so you could not use + accented or special letters directly. To use accented letters, a special syntax was created: + such as for example <userinput>\"e</userinput> for <computeroutput>ë</computeroutput>. + There is a package to help you with this, called <application>inputenc</application>, and is included + in the preamble using <userinput>\usepackage[latin1]{inputenc}</userinput>, where the optional argument + is the encoding you would like to use (nowadays in most cases <userinput>utf8x</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> documents directly for more + information on <application>inputenc</application>. Last but not least: remember to make sure that + your file is <emphasis>actually</emphasis> encoded in the same encoding you told + <application>inputenc</application>!</para> + + <screenshot> + <screeninfo>Choosing the source file's encoding</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="snap_encoding.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Choosing the source file's encoding</phrase> + </textobject> + <caption><para>Choosing the source file's encoding</para></caption> + </mediaobject> + </screenshot> + + <para>This host of different character coding tables has been creating problems on + many applications: 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® relies instead on the more cumbersome and + less flexible <abbrev>UCS-2</abbrev>. Some distributions, as RedHat, have already + begun setting their default encoding to <abbrev>UTF-8</abbrev>, and therefore you + may be very interested in using of the <userinput>utf8x</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 the home page of + <ulink url="http://www.unruh.de/DniQ/latex/unicode/">Unicode support for + &latex;</ulink>, by Dominique Unruh from the University of Karlsruhe.</para></listitem> + <listitem> + <para>To install it, unpack the downloaded file and place it in a directory listed + in your $<envar>TEXINPUTS</envar> envirnoment variable. This can also be set inside kile.</para> + </listitem> + </itemizedlist> + <screen><userinput> + \usepackage{ucs} + \usepackage[utf8x]{inputenc}</userinput></screen> + + </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. We will instead 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 like you did with the &ucs; package + before (see <xref linkend="ucs"/>). 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 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.netscape.com/pub/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 reasons, sometimes this does not produce the hundreds + of files it should. Should that be 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> in a folder like + <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 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. Add the line <userinput>cyberbit@Unicode@ cyberbit.ttf</userinput> + into 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 setting &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> by 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> + +<chapter id="scripting"> + + <title>Scripting</title> + + <sect1 id="scripting_test"> + + <title>Scripting in &kile;</title> + + <para> + &kile;'s scripting feature allows for the execution of ECMAScript code. Scripts can be managed through the + scripting panel in the sidebar. + </para> + + </sect1> + + <sect1 id="scripting_api"> + + <title>API Reference</title> + + <para>In this section we describe &kile;'s scripting programming interface.</para> + + <important> + <para> + Please note that the scripting API has not been finalized yet. The API described below might change in + future versions of &kile;. + </para> + </important> + + <para> + First of all, &kile;'s script execution environment provides a global object called "kile", which owns the following + methods: + </para> + + <variablelist> + <varlistentry> + <term>(kile).<function>currentTextDocument()</function></term> + <listitem> + <para> + Returns a <classname>KileTextDocument</classname> object which reflects the currently active + text document. Returns <constant>null</constant> if no text document is active. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>(kile).<function>getInputValue(<parameter>caption</parameter>, <parameter>label</parameter>)</function></term> + <listitem> + <para> + Opens a dialog with the given caption and label. Returns the value that user has entered. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Objects of the type <classname>KileTextDocument</classname> represent text documents in &kile;. They have the following + properties: + </para> + + <variablelist> + <varlistentry> + <term>(KileTextDocument).<function>backspace()</function></term> + <listitem> + <para> + Deletes the character that is located immediately before the current cursor position and moves the cursor + one position backward in the text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>cursorLeft()</function></term> + <listitem> + <para>Moves the cursor one position backward in the text.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>cursorRight()</function></term> + <listitem> + <para>Moves the cursor one position forward in the text.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>insertText(<parameter>text</parameter>)</function></term> + <listitem> + <para> + Inserts the text contained in the variable <parameter>text</parameter> into the document at the current + cursor location. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>insertBullet()</function></term> + <listitem> + <para>Inserts a bullet into the document at the current cursor position.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>nextBullet()</function></term> + <listitem> + <para> + Selects the first bullet located in the document immediately after the + current cursor location. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>previousBullet()</function></term> + <listitem> + <para> + Selects the first bullet located in the document immediately before the + current cursor location. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>up()</function></term> + <listitem> + <para>Moves the cursor one line up in the document.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>down()</function></term> + <listitem> + <para>Moves the cursor one line down in the document.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>cursorLine()</function></term> + <listitem> + <para>Returns the line which the cursor is currently located at.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>cursorColumn()</function></term> + <listitem> + <para>Returns the column which the cursor is currently located at.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>setCursorLine(<parameter>line</parameter>)</function></term> + <listitem> + <para>Moves the cursor to the line denoted by <parameter>line</parameter>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>(KileTextDocument).<function>setCursorColumn(<parameter>column</parameter>)</function></term> + <listitem> + <para>Moves the cursor to the column denoted by <parameter>line</parameter>.</para> + </listitem> + </varlistentry> + </variablelist> + + </sect1> + +</chapter> + +<chapter id="help"> + + <title>Help</title> + + <sect1 id="help_documents"> + + <title>Help Documents</title> + + <para>&latex; is a rather sophisticated system, where the basic features + can be expanded by a great variety of additional packages. + &kile; provides a lot of different help to support the user.</para> + + <variablelist> + + <varlistentry> + <term><guimenu>LaTeX Reference</guimenu></term> + <listitem><para>An alphabetical index of the most + common &latex; commands.</para></listitem> + </varlistentry> + + <varlistentry> + <term><guimenu>TeX Documentation</guimenu></term> + <listitem><para>&tetex;/&texlive; comes with a huge amount of documents. + This includes a documentation for all included packages and an additional &latex; + reference.</para></listitem> + </varlistentry> + + <varlistentry> + <term><guimenu>LaTeX</guimenu></term> + <listitem><para>A full reference for &tex; and friends. This is not + only a description of all programs, some important packages are also + mentioned. And it includes a full reference manual of &latex; + commands—ideal for looking up a particular piece of formatting + while writing a document. As this document is really extensive, + &kile; separates it with three important bookmarks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><guimenu>LaTeX Command</guimenu></term> + <listitem><para>Another alphabetical index of the most common + &latex; commands.</para></listitem> + </varlistentry> + + <varlistentry> + <term><guimenu>LaTeX Subject</guimenu></term> + <listitem><para>A description of important &latex; + subjects.</para></listitem> + </varlistentry> + + <varlistentry> + <term><guimenu>LaTeX Env</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 support 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; + comes with a huge amount of documents. As one possible help, &tetex;/&texlive; + provides a tiny program <application>texdoctk</application>. + It comes with a database of all documents that &kile; uses to offer + an interface to it.</para> + + <screenshot> + <screeninfo>Bullets</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="dialog-docbrowser1.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Bullets</phrase> + </textobject> + </mediaobject> + </screenshot> + + <para>All documents are grouped into some categories, and the main + advantage is that you can search for packages names or keywords. + &kile; will then show only the results.</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 the + viewer for this document. This can be a arbitrary document, not only a + DVI, PS, PDF or HTML document. &kile; will take &konqueror; settings to + start a appropriate viewer.</para> + + + </sect1> + + <sect1 id="help_userdefined"> + + <title>User Defined Help</title> + + <para>Beside this static &tetex;/&texlive; documentation, &kile; supports also + another variable way for user-help documents. In <guimenu>Help</guimenu> + menu &kile; has a special <guimenu>User help</guimenu> + submenu, where the user can add documents of his own choice. + These can be the most important documents of &tetex;/&texlive; documentation, or even + self written documents. It is even possible to choose some Web URLs.</para> + + <para>Go to + <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> + <guimenuitem>Kile</guimenuitem><guilabel>Help</guilabel></menuchoice> + and choose <guibutton>Configure</guibutton> button + to configure this <guimenu>User help</guimenu> menu. You can add, + remove or navigate menu entries, and also insert separators to get + a better structure.</para> + + <para>Pressing the <guibutton>Add</guibutton> button will open + another dialog, where you must edit the name of the menu entry, + and choose the corresponding file or Web &url;. If you choose a Web &url;, + &konqueror; is started and you should copy the final &url;.</para> + + <screenshot> + <screeninfo>Bullets</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="dialog-addhelp.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Bullets</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 will run on systems + with the &kde; Desktop Environment installed. &kde; is available for several architectures + with Linux and other Unix-like systems installed. &kile; is also part of the Fink project, + which means you can run &kile; on a Mac with OS-X.</para> + + <para>Many thanks are owed to those who strive to continue the &kile; project, and the many + hours of contributions made by those who sacrifice their time to develop tools we can all + use under the <acronym>GNU</acronym> 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>Contributions among others from: Rob Lensen, Roland Schulz, Michael Margraf, Holger Danielsson</para> + + <para>Many thanks to all those involved!</para> + + &underFDL; <!-- FDL: do not remove --> + &underGPL; <!-- GPL License --> + +</chapter> + + +&documentation.index; + +</book> |