1<?xml version="1.0" ?> 2<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ 3 <!ENTITY kile "<application>Kile</application>"> 4 <!ENTITY latex "L<superscript>A</superscript>T<subscript>E</subscript>X"> 5 <!ENTITY pdflatex "PDFL<superscript>A</superscript>T<subscript>E</subscript>X"> 6 <!ENTITY tex "T<subscript>E</subscript>X"> 7 <!ENTITY tetex "<application>teT<subscript>E</subscript>X</application>"> 8 <!ENTITY texlive "<application>TeX Live</application>"> 9 <!ENTITY bibtex "BibT<subscript>E</subscript>X"> 10 <!ENTITY makeindex "makeindex"> 11 <!ENTITY kbibtex "KBibT<subscript>E</subscript>X"> 12 <!ENTITY kbib "KBib"> 13 <!ENTITY asymptote "Asymptote"> 14 <!ENTITY imagemagick "<application>ImageMagick</application>"> 15 <!ENTITY dvipng "<application>dvipng</application>"> 16 <!ENTITY makeidx "<application>makeidx</application>"> 17 <!ENTITY cjk "<abbrev>CJK</abbrev>"> 18 <!ENTITY ucs "<abbrev>ucs</abbrev>"> 19 <!ENTITY % addindex "IGNORE"> 20 <!ENTITY % English "INCLUDE"> 21 <!ENTITY javascript "<application>JavaScript</application>"> 22 <!ENTITY include-section-scripting SYSTEM "scripting.docbook"> 23 <!ENTITY include-section-usermenu SYSTEM "usermenu.docbook"> 24]> 25 26<book id="kile" lang="&language;"> 27 28<bookinfo> 29<title>The &kile; Handbook</title> 30 31<authorgroup> 32 <author><firstname>Jonathan</firstname><surname>Pechta</surname></author> 33 <author><firstname>Federico</firstname><surname>Zenith</surname> 34 <affiliation><address><email>federico.zenith@member.fsf.org</email></address></affiliation></author> 35 <author><firstname>Holger</firstname><surname>Danielsson</surname> 36 <affiliation><address><email>holger.danielsson@versanet.de</email></address></affiliation></author> 37 <author><firstname>Thomas</firstname><surname>Braun</surname></author> 38 <author><firstname>Michel</firstname><surname>Ludwig</surname> 39 <affiliation><address><email>michel.ludwig@kdemail.net</email></address></affiliation></author> 40 <author><firstname>Felix</firstname><surname>Mauch</surname> 41 <affiliation><address><email>felix_mauch@web.de</email></address></affiliation></author> 42 <!-- TRANS:ROLES_OF_TRANSLATORS --> 43</authorgroup> 44 45<copyright> 46<year>2003</year> 47<holder>Jonathan Pechta</holder> 48</copyright> 49 50<copyright> 51<year>2003</year><year>2005</year><year>2006</year> 52<holder>Federico Zenith</holder> 53</copyright> 54 55<copyright> 56<year>2005</year><year>2006</year><year>2012</year> 57<holder>Holger Danielsson</holder> 58</copyright> 59 60<copyright> 61<year>2007</year> 62<holder>Thomas Braun</holder> 63</copyright> 64 65<copyright> 66<year>2007</year><year>2011</year> 67<holder>Michel Ludwig</holder> 68</copyright> 69 70<copyright> 71<year>2011</year> 72<holder>Felix Mauch</holder> 73</copyright> 74 75<date>2011-05-22</date> 76<releaseinfo>2.1</releaseinfo> 77 78<legalnotice> 79&FDLNotice; 80</legalnotice> 81 82<abstract> 83<para> 84&kile; is a &tex; and &latex; source editor and shell. 85</para> 86</abstract> 87 88<keywordset> 89<keyword>KDE</keyword> 90<keyword>kdenonbeta</keyword> 91<keyword>Kile</keyword> 92<keyword>LaTeX</keyword> 93<keyword>TeX</keyword> 94</keywordset> 95 96</bookinfo> 97 98<chapter id="preface"> 99 100<title>Preface</title> 101 102 <sect1 id="preface_sect"> 103 104 <title>Requirements</title> 105 106 <para>To run &kile;, you need to have the following components 107 installed on your system:</para> 108 109 <itemizedlist> 110 <listitem><para><ulink url="http://www.kde.org/">K Desktop environment (&kde;)</ulink>: 111 &kde; is a popular open-source desktop environment.</para></listitem> 112 <listitem><para><ulink url="https://qt.io/">&Qt;</ulink>: &Qt; is a C++ 113 &GUI; and network library needed to compile &kile;.</para></listitem> 114 <listitem><para><ulink url="http://www.ctan.org/">&latex;</ulink>: high-quality document 115 typesetting program. Most likely you want the &texlive; (or on older systems the &tetex;) package, if you are on a 116 &UNIX;-like system.</para></listitem> 117 </itemizedlist> 118 119 <para>Most of these items might be included in your &Linux; distribution; please refer to your 120 distribution documentation, or refer to your installation &CD; or DVD, for adding these 121 packages to your computer.</para> 122 123 <para>&kile; might also be available as a pre-compiled package for your &Linux; distribution already. Please check with the 124 package manager of your distribution.</para> 125 126 </sect1> 127 128 <sect1 id="preface_audience"> 129 130 <title>Intended Audience</title> 131 132 <para>This manual is intended for any individual, regardless of her or his experience with 133 &latex;, &kde;, &kile; or &Linux;.</para> 134 135 <para>Advanced users are not likely to read this manual, but all suggestions on 136 documentation will be considered. If you would like to contribute to this project or the 137 documentation, please consult the <ulink url="http://kile.sourceforge.net/">&kile; web page</ulink>.</para> 138 139 <para>Do you need answers about &kile;? Are you stuck with the compilation process? Do you want to see a new 140 feature implemented? The preferred way to ask technical questions or to start a discussion is to 141 use our mailing list: <email>kile-devel@lists.sourceforge.net</email>.</para> 142 143 </sect1> 144 145</chapter> 146 147<chapter id="introduction"> 148 149 <title>Introduction</title> 150 151 <sect1 id="intro_about"> 152 153 <title>Basic facts</title> 154 155 <sect2> 156 157 <title>About &kile;</title> 158 159 <para>&kile; is an integrated &latex; environment for the &kde; desktop. &kile; gives you the 160 ability to use all the functionality of &latex; in a graphical interface, giving you easy, 161 immediate, and customized access to all programs for &latex; code-completion, compiling, postprocessing, 162 debugging, conversion and viewing tools; you also get very handy wizards, a &latex; 163 reference and a powerful project manager.</para> 164 165 </sect2> 166 167 <sect2> 168 169 <title>&kile; and the &kate; Editor Component</title> 170 171 <para>&kile; is based on the &kate; editor component, &ie; a lot of its editing capabilities stem from the &kate; 172 editor component itself. &kile; extends these capabilities with features to edit &latex; documents. To learn more 173 about the &kate; editor component and its capabilities, see the <ulink url="http://kate-editor.org">&kate; 174 webpage</ulink>.</para> 175 176 </sect2> 177 178 <sect2> 179 180 <title>What is &latex;?</title> 181 182 <para>&latex; is a text-processing system derived from &tex;, a program developed originally in 183 1977 by Donald Knuth to help layout text in a professional way and obtain a layout quality that 184 is on a par with the work of a professional typesetter. 185 &latex; was created by Leslie Lamport to give authors an automatic typesetter, especially to ease 186 the expensive and painstaking process of typesetting of mathematical formulas and expressions, 187 which are enclosed within dollar signs in &latex; <emphasis>for a reason</emphasis>. 188 Today, word-processing programs let any user act as typesetter, but what is often needed 189 is a document that simply looks good without having to spend hours to bring it into shape. 190 &latex; takes that burden on its shoulders, and lets you concentrate on the document instead of on the layout. 191 And yes, it <emphasis>will</emphasis> look good!</para> 192 193 </sect2> 194 195 <sect2> 196 197 <title>How do you pronounce it? Why that strange typesetting?</title> 198 199 <para>There is a funny tradition of &tex;-related packages to have the strangest pronunciation 200 and typesetting possible. &tex; was supposed to be brought in from the Greek <emphasis>τεχ</emphasis>, 201 in Latin letters <emphasis>tech</emphasis>. There are a lot of explanations why, but most likely it is because 202 &tex; was originally conceived for technical reports, and indeed its foremost ability was the correct and 203 easy typesetting of mathematical formulae, then an extremely expensive, time-consuming and 204 frustrating business.</para> 205 <para>The pronunciation is supposed to be as follows: <emphasis>T</emphasis> as you would expect, 206 <emphasis>E</emphasis> as in <emphasis>get</emphasis>, and <emphasis>X</emphasis> as in the 207 German i<emphasis>ch</emphasis>. If you do not know what <emphasis>ch</emphasis> sounds like, 208 it is more or less like the sound a hissing cat produces; the IPA symbol is /ç/. Many people report a different pronunciation 209 of <emphasis>ach</emphasis> (IPA symbol /x/), but according to some Greeks, the first version is indeed correct. 210 You should be aware that a lot of people mispronounce &tex; as /teks/ or /tek/.</para> 211 <para>Last, in &latex; the first L<superscript>A</superscript> is pronounced as 212 <emphasis>lay</emphasis>: the idea being, while raw &tex; is difficult, even a <emphasis>lay</emphasis>man 213 can use &latex; macros. A less inspiring, but more realistic explanation is that it stems from the surname of 214 Leslie Lamport, the creator of &latex;. Now you know!</para> 215 216 </sect2> 217 218 </sect1> 219 220 <sect1 id="intro_latexbasics"> 221 222 <title>&latex; 101</title> 223 224 <para>The &latex; typesetting system is similar to other markup languages such as &XML;, which is used in 225 many types of documents (including the one you are reading), or &HTML;, which is used for web 226 pages. The general idea behind markup languages is to have special keywords, called <emphasis> 227 tags</emphasis>, that tell a program (a word processor, a web browser, or the &latex; 228 compiler) how the text enclosed within the tags is to be interpreted. &kile; offers a number of such tags in the 229 <guimenu>LaTeX</guimenu> menu in the menu bar.</para> 230 231 <para>While we will try to give you a good idea of what &latex; is, this document is, of course, not The Definitive 232 Book on &latex;. If you want to learn &latex; in depth, you may want to borrow a specialized book from your local library.</para> 233 234 <para>As with any other markup language, &latex; documents contain a <emphasis>preamble</emphasis>, which 235 defines global properties, such as paper size, page numbering, dimensions of the text on the page, 236 and a document <emphasis>body</emphasis>, which contains the text of the document. The preamble is composed 237 at least of the <userinput>\documentclass</userinput> command. It precedes the document body, which 238 starts with the command <userinput>\begin{document}</userinput> and is concluded with the command 239 <userinput>\end{document}</userinput>.</para> 240 241 </sect1> 242 243 <sect1 id="intro_mainfeat"> 244 245 <title>&kile;'s Main Features</title> 246 247 <sect2 id="intro_docwizard"> 248 249 <title>QuickStart Wizard</title> 250 251 <para>The QuickStart wizard built into &kile; is a useful feature to quickly start creating documents 252 in &kile;. Choosing the wizard from the menubar gives you several choices 253 for the creation of your document. 254 You can also specify some options related to the document right away.</para> 255 256 <para>Class options:</para> 257 258 <itemizedlist> 259 <listitem><para><guilabel>Document Class</guilabel>: choose the type of document you want to create: 260 article, book, letter, report, scrartcl, scrreprt, scrbook, prosper, beamer or other 261 custom-defined.</para></listitem> 262 <listitem><para><guilabel>Typeface Size</guilabel>: tell &kile; what point size (pt) 263 you want to use.</para></listitem> 264 <listitem><para><guilabel>Paper Size</guilabel>: choose the size or style of sheets.</para></listitem> 265 <listitem><para><guilabel>Encoding</guilabel>: In general it is a good idea to use your system's standard 266 encoding. Modern systems now move more and more to UTF-8 as the standard encoding. 267 If you can, use utf8 or utf8x (which is indeed the correct spelling for &latex; documents). 268 </para></listitem> 269 <listitem><para><guilabel>Other options</guilabel>: this allows you to set further options such as printing, 270 draft, and others.</para></listitem> 271 </itemizedlist> 272 273 <para>Packages</para> 274 <para>This lists some of the most common additional packages used in &latex;. Select the check box to include it.</para> 275 276 <para>Document Properties:</para> 277 <itemizedlist> 278 <listitem><para><guilabel>Author</guilabel>: put your name here.</para></listitem> 279 <listitem><para><guilabel>Title</guilabel>: add the document title here.</para></listitem> 280 <listitem><para><guilabel>Date</guilabel>: specify the date.</para></listitem> 281 </itemizedlist> 282 283 </sect2> 284 285 <sect2 id="intro_templates"> 286 287 <title>Predefined Templates</title> 288 289 <para>The predefined templates in &kile; are:</para> 290 291 <itemizedlist> 292 <listitem><para>Empty document: real freaks start from scratch!</para></listitem> 293 <listitem><para>Article: sets the article format, for a document short enough not to 294 be broken down to chapters.</para></listitem> 295 <listitem><para>Report: sets the report format, for a middle-sized document, with, for 296 example, page numbering on the page's outer edge.</para></listitem> 297 <listitem><para>Book: sets the book format, a full-fledged flavor, so powerful that 298 it is used to write many university textbooks.</para></listitem> 299 <listitem><para>Letter: sets the letter format.</para></listitem> 300 <listitem><para>Beamer, HA-Prosper: create nice presentations in PDF with a superior look and all 301 &latex; power.</para></listitem> 302 <listitem><para>Powerdot: Powerdot is the follower of the packages <userinput>seminar</userinput> 303 and <userinput>HA-Prosper</userinput>. It does not have as many options as Beamer, 304 but it is easy to use and it can create really nice presentations in PDF.</para></listitem> 305 <listitem><para>Scrartcl, Scrbook, Scrreprt, Scrlttr2: the KOMA-Script document classes, 306 especially adapted to German typography. Use them whenever you write German 307 texts.</para></listitem> 308 <listitem><para>Xelatex: a modified <userinput>Article</userinput> template to use with 309 <userinput>XeLaTeX</userinput>.</para></listitem> 310 </itemizedlist> 311 312 <para>Note that all of these templates can be adjusted to the user's requirements.</para> 313 314 <para>New users need not worry: this list is just a brief description of the available features, 315 and a more detailed description can be found in <xref linkend="quickstart" role="select: title pageabbrv"/>.</para> 316 317 </sect2> 318 319 <sect2 id="intro_highlight"> 320 321 <title>Syntax Highlighting</title> 322 323 <para>&kile; is similar to other programs that deal with source code and editing, and will 324 automatically highlight commands, options and items that are used (and abused). 325 &kile; makes it possible to easily spot problematic areas: for example, if you see major 326 areas of text turn green, it is likely that you forgot to close a math environment somewhere.</para> 327 328 </sect2> 329 330 <sect2 id="intro_autocoml"> 331 332 <title>Auto-Completion of Environments</title> 333 334 <para>The auto-completion of environments means that, when you begin a new environment by typing 335 <userinput>\begin{environment}</userinput>, &kile; will automatically insert a matching 336 <userinput>\end{environment}</userinput> command, with a line in between them 337 for your text. You can of course deactivate it if you want in 338 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 339 <guimenuitem>LaTeX</guimenuitem><guilabel>Environments</guilabel></menuchoice>.</para> 340 341 </sect2> 342 343 <sect2 id="intro_jump"> 344 345 <title>Jump to Structure Element</title> 346 347 <para>All documents are normally structured in a hierarchy of some type. 348 &latex; allows you to break up documents into the following hierarchy 349 (part being highest in the hierarchy, and subparagraph being lowest):</para> 350 351 <itemizedlist> 352 <listitem><para>\part</para></listitem> 353 <listitem><para>\chapter</para></listitem> 354 <listitem><para>\section</para></listitem> 355 <listitem><para>\subsection</para></listitem> 356 <listitem><para>\subsubsection</para></listitem> 357 <listitem><para>\paragraph</para></listitem> 358 <listitem><para>\subparagraph</para></listitem> 359 </itemizedlist> 360 361 <para>When viewing a document in the <guilabel>Structure</guilabel> view, you can jump 362 between elements by clicking on the element you would like to view.</para> 363 364 </sect2> 365 366 <sect2 id="intro_inverse"> 367 368 <title>Inverse Search</title> 369 370 <para>When creating your own &latex; files, inverse search can be very helpful. Once you 371 have created a &DVI; file (DeVice Independent File) or PDF file, you can click the left 372 mouse button while pressing &Shift; in the viewer and &kile; will jump to the corresponding line in the 373 &latex; source code.</para> 374 375 <para>A &DVI; is a type of file containing a 376 description of a formatted document, along with other 377 information including character font, and is besides PDF the usual output of 378 &tex; or &latex;. A number of utilities exist to view, convert and print &DVI; files on 379 various systems and devices.</para> 380 381 </sect2> 382 383 <sect2 id="intro_forward"> 384 385 <title>Forward Search</title> 386 387 <para>When using inverse search, the selection of items in the &DVI; or PDF file is associated with 388 the editor, so when you click on the &DVI; or PDF file, the main window jumps to the 389 corresponding section of &latex; code in the editor. Forward search is the exact 390 opposite of this. Forward search will allow you to click on a specific section of text 391 in the &latex; code, and jump to the associated position in the viewer window.</para> 392 393 </sect2> 394 395 </sect1> 396 397 <sect1 id="intro_toolbar"> 398 399 <title>The Toolbar</title> 400 401 <itemizedlist> 402 <listitem><para><guibutton>New</guibutton>: begin a new document.</para></listitem> 403 <listitem><para><guibutton>Open</guibutton>: open a new document.</para></listitem> 404 <listitem><para><guibutton>Close</guibutton>: close your document.</para></listitem> 405 <!-- following toolbar items are different in default master/2.1--> 406 <listitem><para><guibutton>Define document as master</guibutton>: this is used when working with multiple files. 407 Having a master document will let you work more easily with other <literal role="extension">.tex</literal> files included 408 in your document. If you are using projects, you can also set in <menuchoice><guimenu>Project</guimenu><guisubmenu>Project 409 Options</guisubmenu></menuchoice> a project-wide master document.</para></listitem> 410 <listitem><para><guibutton>Quickbuild</guibutton>: compiles your &latex; source code and displays the results 411 automatically unless there are errors contained in the document.</para></listitem> 412 <listitem><para><guibutton>Watch file mode</guibutton>: this mode will "watch" the &DVI; file for changes, and 413 will not launch a new session of &okular; after <guibutton>Quickbuild</guibutton>.</para></listitem> 414 <listitem><para><guibutton>View logfile</guibutton>: views the <literal role="extension">.log</literal> file, 415 so you can spot errors.</para></listitem> 416 <listitem><para><guibutton>Previous error</guibutton>: jumps backward through the 417 <literal role="extension">.log</literal> file 418 and highlights errors in the source.</para></listitem> 419 <listitem><para><guibutton>Next error</guibutton>: jumps forward through the 420 <literal role="extension">.log</literal> file and 421 highlights errors in the source.</para></listitem> 422 <listitem><para><guibutton>Stop</guibutton>: halts current tool.</para></listitem> 423 <listitem><para><guibutton>LaTeX</guibutton>: runs &latex; on the active document.</para></listitem> 424 <listitem><para><guibutton>ViewDVI</guibutton>: launches &DVI; viewer.</para></listitem> 425 <listitem><para><guibutton>DVItoPS</guibutton>: converts a &DVI; to a &PostScript; (PS).</para></listitem> 426 <listitem><para><guibutton>ViewPS</guibutton>: launches &PostScript; (PS) viewer.</para></listitem> 427 <listitem><para><guibutton>PDFLaTeX</guibutton>: runs &pdflatex; on the active document.</para></listitem> 428 <listitem><para><guibutton>ViewPDF</guibutton>: launches the PDF viewer.</para></listitem> 429 <listitem><para><guibutton>DVItoPDF</guibutton>: converts a &DVI; to a PDF.</para></listitem> 430 <listitem><para><guibutton>PStoPDF</guibutton>: converts a PS to a PDF.</para></listitem> 431 <listitem><para><guibutton>ViewHTML</guibutton>: views &HTML; created.</para></listitem> 432 <listitem><para><guibutton>ForwardDVI</guibutton>: jump to the page of the &DVI; file that corresponds to the current line in the editor.</para></listitem> 433 <listitem><para><guibutton>ForwardPDF</guibutton>: jump to the page of the PDF file that corresponds to the current line in the editor.</para></listitem> 434 </itemizedlist> 435 436 <para>If you look at the <guilabel>Edit</guilabel> toolbar, you will notice three large 437 drop-down menus. The drop-down menus were designed for you to be able to quickly add 438 certain common features into your document. The first drop down box 439 is used for quickly dividing your document by parts, chapter, sections and so on; the 440 available commands to add segments to your &latex; source code are:</para> 441 442 <itemizedlist> 443 <listitem><para><guilabel>part</guilabel>: highest level of sectioning for a document.</para></listitem> 444 <listitem><para><guilabel>chapter</guilabel>: starts a new chapter.</para></listitem> 445 <listitem><para><guilabel>section</guilabel>: create a new section.</para></listitem> 446 <listitem><para><guilabel>subsection</guilabel>: create a new subsection.</para></listitem> 447 <listitem><para><guilabel>subsubsection</guilabel>: a secondary section between subsection and 448 paragraph.</para></listitem> 449 <listitem><para><guilabel>paragraph</guilabel>: create a new paragraph.</para></listitem> 450 <listitem><para><guilabel>subparagraph</guilabel>: create a new subparagraph.</para></listitem> 451 </itemizedlist> 452 453 <para>The drop down box named <guilabel>Other</guilabel> is used to insert items into your document such as 454 indexes, footnotes, and references; the available commands are:</para> 455 456 <itemizedlist> 457 <listitem><para><guilabel>label</guilabel>: a command that produces a label for a chapter, 458 a figure or another element.</para></listitem> 459 <listitem><para><guilabel>index</guilabel>: creates an entry for the index.</para></listitem> 460 <listitem><para><guilabel>footnote</guilabel>: creates a footnote in your document.</para></listitem> 461 <listitem><para><guilabel>ref</guilabel>: used to refer to a predefined label, which 462 you can choose from a drop-down list.</para></listitem> 463 <listitem><para><guilabel>pageref</guilabel>: just like <guilabel>ref</guilabel>, but refers to 464 a page instead of a structure element.</para></listitem> 465 <listitem><para><guilabel>cite</guilabel>: create a reference with data from a bibliography.</para></listitem> 466<!-- The next feature is currently disabled (see 'kile.cpp'). --> 467<!-- <listitem><para><guilabel>cite from ViewBib</guilabel>: ask the ViewBib tool for all selected references and insert them. 468 Currently this is only available with <ulink url="http://user.digisurf.com.au/~thachly/kbib/">&kbib;</ulink> as ViewBib tool.</para></listitem>--> 469 </itemizedlist> 470 471 <screenshot> 472 <screeninfo>The <guilabel>Other</guilabel> drop-down menu</screeninfo> 473 <mediaobject> 474 <imageobject> 475 <imagedata fileref="snap_ref_choose.png" format="PNG" /> 476 </imageobject> 477 <textobject> 478 <phrase>The <guilabel>Other</guilabel> drop-down menu</phrase> 479 </textobject> 480 <caption><para>The <guilabel>Other</guilabel> drop-down menu</para></caption> 481 </mediaobject> 482 </screenshot> 483 484 <screenshot> 485 <screeninfo>Selecting the label for a reference</screeninfo> 486 <mediaobject> 487 <imageobject> 488 <imagedata fileref="snap_ref_select.png" format="PNG" /> 489 </imageobject> 490 <textobject> 491 <phrase>Selecting the label for a reference</phrase> 492 </textobject> 493 <caption><para>Selecting the label for a reference</para></caption> 494 </mediaobject> 495 </screenshot> 496 497 <para>When using <guilabel>cite</guilabel>, you are presented with a drop-down 498 list of bibitems, but if you are using &bibtex; this will only work if the file 499 belongs to a Project. For editing &bibtex; files the usage of specialized editors is recommended. 500 The author has had good results with &kbibtex;. Of course you can also write the &bibtex; files by hand inside &kile;.</para> 501 502 <para>The last drop down box labeled <guilabel>tiny</guilabel> is used to set the size of the text. You can 503 set the size of the main text, of footnotes, and so on. The available commands are:</para> 504 505 <itemizedlist> 506 <listitem><para><guilabel>tiny</guilabel>: smallest.</para></listitem> 507 <listitem><para><guilabel>scriptsize</guilabel>: very small.</para></listitem> 508 <listitem><para><guilabel>footnotesize</guilabel>: smaller.</para></listitem> 509 <listitem><para><guilabel>small</guilabel>: small.</para></listitem> 510 <listitem><para><guilabel>normalsize</guilabel>: normal.</para></listitem> 511 <listitem><para><guilabel>large</guilabel>: large.</para></listitem> 512 <listitem><para><guilabel>Large</guilabel>: larger.</para></listitem> 513 <listitem><para><guilabel>LARGE</guilabel>: even larger.</para></listitem> 514 <listitem><para><guilabel>huge</guilabel>: still larger.</para></listitem> 515 <listitem><para><guilabel>Huge</guilabel>: largest.</para></listitem> 516 </itemizedlist> 517 518 </sect1> 519 520</chapter> 521<chapter id="quickstart"> 522 523 <title>Quickstart</title> 524 525 <sect1 id="quick_begin"> 526 527 <title>Writing a &latex; Document with &kile; for Beginners</title> 528 529 <para>Users of &kile; have two choices when starting a new document: they can use the 530 <guimenu>Wizard</guimenu> to begin a new document, select the type of document they 531 would like to create and options such as font size, paper size, and so on; otherwise, 532 they can write the code by hand.</para> 533 534<programlisting>\documentclass[12pt]{article} 535\begin{document} 536 Here is a bunch of text coded in \LaTeX. 537\end{document}</programlisting> 538 539 <para>Every document in &latex; begins with the command <userinput> 540 \documentclass[optional argument]{class}</userinput>, where class specifies the document type.</para> 541 542 <para>Typing in the code example above from the text box gives you the following output:</para> 543 544 <screenshot> 545 <screeninfo>Compiled text in &DVI; output</screeninfo> 546 <mediaobject> 547 <imageobject> 548 <imagedata fileref="latex_example.png" format="PNG" /> 549 </imageobject> 550 <textobject> 551 <phrase>Compiled text in &DVI; output</phrase> 552 </textobject> 553 <caption><para>Compiled text in &DVI; output</para></caption> 554 </mediaobject> 555 </screenshot> 556 557 <para>The brackets that come after the command <userinput>\documentclass</userinput> 558 contain the options for the command. The option <userinput>[12pt]</userinput> sets the size 559 of the font for your article; if you do not set the font size in the beginning, you can set 560 it later in the text.</para> 561 562 <para>Once you have typed in the code example from the box above, you will need to 563 compile your &latex; source code. The easiest way for you to compile &latex; is to 564 use the <guimenu>Build</guimenu> menu, or using the <guilabel>Quickbuild</guilabel> button.</para> 565 566 <para><keycombo>&Alt;<keycap>2</keycap></keycombo> 567 is the keyboard shortcut to compile your source code.</para> 568 569 <para>You have to save your source code before you can compile; &kile; will do this automatically for you.</para> 570 571 <para>If your document did not compile, check the log for errors. When using the <guilabel>Quickbuild</guilabel> 572 key, the &okular; viewer should be launched automatically; if it does not, look at the log.</para> 573 574 </sect1> 575 576 <sect1 id="quick_env"> 577 <title>Environments</title> 578 579 <para>An environment is a segment of text that is managed differently 580 from the rest of the document. For example, you create a report with font size 12, 581 but you need to change your font size for a few sentences. The commands 582 <userinput>\begin{environment}</userinput>, <userinput>\huge</userinput> and 583 <userinput>\end{environment}</userinput> will let you temporarily alter the text inside 584 the environment commands to be size huge.</para> 585 586 <para>Changes are only effective from <userinput>\begin{environment}</userinput> to 587 <userinput>\end{environment}</userinput>. There are no limits as to how many changes 588 you can make inside an environment.</para> 589 590 <para>There are many features you can add to your document that will make it more 591 readable and user-friendly. You can add features such as specific fonts, bold, italics, 592 underline &etc; to your document, and these commands will end with either an 593 <userinput>\end</userinput> command, or at the end of your environment.</para> 594 595 <itemizedlist> 596 <listitem><para><userinput>\begin{emph}</userinput>: this command makes 597 text italicized, and is valid until the code comes across a <userinput>\end{emph}</userinput>, 598 or another environment. To italicize one word in a sentence, you 599 can use the syntax: this is <userinput>\emph{my}</userinput> sentence.</para></listitem> 600 <listitem><para><userinput>\textbf{I am making this text inside the brackets bold}</userinput>: this 601 command makes your text bold.</para></listitem> 602 <listitem><para><userinput>\quote</userinput>: to create a quote inside your document; begin your quote 603 with <userinput>\begin{quote}</userinput> and end it with <userinput>\end{quote}</userinput>.</para></listitem> 604 <listitem><para><userinput>\center</userinput>: centers the text.</para></listitem> 605 <listitem><para><userinput>\verse</userinput>: creates offset text for poems.</para></listitem> 606 <listitem><para><userinput>\itemize</userinput>: makes an itemized list.</para></listitem> 607 </itemizedlist> 608 609 </sect1> 610 611 <sect1 id="quick_using"> 612 613 <title>Using &kile;</title> 614 615 <para>Now that we have given you some background about how to write code using the 616 &latex; markup language, we will show you how to create a document 617 using &kile; step-by-step.</para> 618 619 <procedure> 620 <step><para>Start &kile;.</para></step> 621 <step><para>Select <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Quick Start</guimenuitem></menuchoice>, 622 then choose a format, and set your preferences in the wizard.</para></step> 623 <step><para>Once the wizard has entered text, do some customization to make the 624 document more readable, add a minimum of one quote, some bold text, 625 italics, and a verse to see the difference between the commands.</para></step> 626 <step><para>Save your file, and give it the name <filename>intro.tex</filename>.</para></step> 627 <step><para>Build your document using <keycombo>&Alt;<keycap>2</keycap></keycombo>, or the 628 button labeled <guilabel>LaTeX</guilabel>.</para></step> 629 <step><para>Select <guibutton>ViewDVI</guibutton>.</para></step> 630 <step><para>Check out all your new text.</para></step> 631 <step><para>When you are done viewing your document, click the <guibutton>Editor View</guibutton> 632 button or press <keycombo>&Ctrl;<keycap>E</keycap></keycombo> 633 to return to the editor if you are using the embedded 634 viewer, or close the viewer window if you are using a separate viewer.</para></step> 635 </procedure> 636 637 <para>That's it! You have just created your first &latex; document!</para> 638 639 <para>Once you have created your &DVI;, you will be able to print your document, or change 640 it into a &PostScript; or PDF file if you want. Experiment and have fun!</para> 641 642 </sect1> 643 644 <sect1 id="quick_dvi"> 645 646 <title>&DVI; Files</title> 647 648 <para>&DVI; stands for <emphasis>DeVice Independent</emphasis> file. These files are produced 649 by &tex; or &latex; to be read by a driver of some sort on your computer. There are many different types of output that 650 a <literal role="extension">.dvi</literal> can be sent to, such as a printer, &PostScript; or PDF file converter, or your computer screen.</para> 651 652 <sect2 id="quick_viewdvi"> 653 654 <title>Viewing a &DVI;</title> 655 656 <para>You have already seen how to view a &DVI; file on the screen by using the <guibutton>ViewDVI</guibutton> button in the toolbar.</para> 657 658 </sect2> 659 660 <sect2 id="quick_printdvi"> 661 662 <title>Printing a &DVI;</title> 663 664 <para>To print a &DVI;, you can use the same process that you used to create your 665 document earlier (see <xref linkend="quick_using" role="select: title pageabbrv"/>). At step 7, after 666 clicking <guibutton>ViewDVI</guibutton>, select 667 <menuchoice><guimenu>File</guimenu><guimenuitem>Print</guimenuitem></menuchoice> 668 in the viewer, and if you have your printer properly configured, you will be able 669 to print the &DVI;.</para> 670 671 </sect2> 672 673 <sect2 id="quick_exportdvi"> 674 675 <title>Converting &DVI; files</title> 676 677 <para>The toolbar gives the options of Converting a &DVI; to other formats. Once you 678 have created a &DVI; from your &latex; source code, you will be able to export it 679 to a format of your choice using the toolbar buttons.</para> 680 681 </sect2> 682 683 </sect1> 684 685 <sect1 id="quick_forward"> 686 687 <title>Forward Search between &kile; and &okular;</title> 688 689 <para>The forward search functions allow you to jump from your 690 editor directly to the associated position of the &DVI; or PDF 691 file. </para> 692 <para>&kile; offers a configuration with this option for all &latex; binaries. 693 Go to <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 694 <guimenuitem>Tools</guimenuitem><guilabel>Build</guilabel></menuchoice> 695 and always choose the <guilabel>Modern</guilabel> configuration.</para> 696 697 <para>To execute a forward search, position the cursor on a line of source code, and click 698 <guilabel>Forward Search</guilabel> to jump to the associated position 699 in the &DVI; or PDF viewer window.</para> 700 </sect1> 701 702 <sect1 id="quick_inverse"> 703 704 <title>Inverse Search between &kile; and &okular;</title> 705 706 <para>Inverse search is a very useful feature when you are writing 707 a &latex; document yourself. If everything is set up properly, you can 708 click into &okular;'s window with the <mousebutton>left</mousebutton> mouse button while pressing &Shift;. After that &kile; loads the &latex; source file and jumps to 709 the proper paragraph. To use inverse search, you have to compile your &latex; file with the <guilabel>Modern</guilabel> configuration.</para> 710 711 <para>Inverse search cannot work unless:</para> 712 713 <itemizedlist> 714 <listitem><para>The source file has been compiled successfully.</para></listitem> 715 <listitem><para>&okular; knows which editor you would like to use.</para></listitem> 716 </itemizedlist> 717 718 <para>With this feature of &okular;, a left mouse click while pressing &Shift; in the &DVI; or PDF document will 719 result in &kile; opening the corresponding &latex; document and attempt to go to the 720 corresponding line. Remember to tell &okular; to use &kile; as a text editor, in &okular;'s 721 menu item <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Okular...</guimenuitem></menuchoice> 722 (on the page <guimenuitem>Editor</guimenuitem>).</para> 723 724 <screenshot> 725 <screeninfo>Configuring &okular;</screeninfo> 726 <mediaobject> 727 <imageobject> 728 <imagedata fileref="snap_okular_settings.png" format="PNG" /> 729 </imageobject> 730 <textobject> 731 <phrase>Configuring &okular;</phrase> 732 </textobject> 733 <caption><para>Configuring &okular;</para></caption> 734 </mediaobject> 735 </screenshot> 736 </sect1> 737 738 <sect1 id="quick_errors"> 739 740 <title>Resolving Errors</title> 741 742 <para>If you are trying to use quickbuild, and the &DVI; viewer does not open, chances are 743 you have an error. If you have an error, it will be visible in the log file / message area, 744 and the summary of the error will be given.</para> 745 746 <para>The log file will explain the source of the error in your code. In the 747 editor, you can use the buttons in the toolbar labeled <guibutton>Previous LaTeX Error</guibutton> 748 and <guibutton>Next LaTeX Error</guibutton> to jump to and from errors. The log file always states 749 in which line the error occurred. To view the line where an error occurred, click on the error 750 in the log window, and &kile; will take you to the error's line.</para> 751 752 </sect1> 753 754</chapter> 755<chapter id="startnew"> 756 757 <title>Starting a New Document</title> 758 759 <para>When you click the button in the toolbar to begin a new document a dialog appears, 760 asking which type of template you would like to use to write your document. The 761 default choices are:</para> 762 763 <itemizedlist> 764 <listitem><para>Empty document</para></listitem> 765 <listitem><para>Article</para></listitem> 766 <listitem><para>Beamer</para></listitem> 767 <listitem><para>Book</para></listitem> 768 <listitem><para>HA-Prosper</para></listitem> 769 <listitem><para>Powerdot</para></listitem> 770 <listitem><para>Letter</para></listitem> 771 <listitem><para>Report</para></listitem> 772 <listitem><para>Scrartcl (from the KOMA-Script package)</para></listitem> 773 <listitem><para>Scrbook (from the KOMA-Script package)</para></listitem> 774 <listitem><para>Scrlttr2 (from the KOMA-Script package)</para></listitem> 775 <listitem><para>Scrreprt (from the KOMA-Script package)</para></listitem> 776 <listitem><para>PDF</para></listitem> 777 <listitem><para>XeLaTeX</para></listitem> 778 </itemizedlist> 779 780 <para>If you selected an <guilabel>Empty document</guilabel>, you can either start 781 writing a document from scratch, or you can use the wizard to quickly start a new 782 document (see <xref linkend="intro_docwizard" role="select: title pageabbrv"/>).</para> 783 784 785 <sect1 id="startnew_templates"> 786 787 <title>Templates</title> 788 789 <para>Frequent users of &latex; typically use the same preamble for almost every document they use. 790 Templates can be created, saved and loaded within &kile; to make it easier to start a new document.</para> 791 792 793 <sect2> 794 <title>Create a New Template</title> 795 796 <para>To create a new template, you must first either open a &tex; / &latex; file, or create a file 797 of your own. &kile; can generate a template from an existing document by opening the desired document and selecting 798 <menuchoice><guimenu>File</guimenu><guimenuitem>Create Template from Document</guimenuitem></menuchoice>.</para> 799 800 </sect2> 801 802 <sect2> 803 804 <title>Configuring Automatic Substitutions</title> 805 806 <para>When creating a new document by selecting a template from 807 <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>, 808 certain character combinations will be replaced by data such as your name, 809 or the character encoding you are using. These variables can be configured in 810 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 811 <guimenuitem>Settings</guimenuitem><guilabel>General</guilabel></menuchoice>.</para> 812 813 <para>When designing your own template, it is useful to know which character 814 combinations are replaced by which template variables:</para> 815 816 <itemizedlist> 817 <listitem><para><userinput>$$AUTHOR$$</userinput>: This string 818 will be replaced by the author variable.</para></listitem> 819 <listitem><para><userinput>$$DOCUMENTCLASSOPTIONS$$</userinput>: This string will be replaced 820 by the documentclass options variable. Typically this is used as follows: 821 <userinput>\documentclass[$$DOCUMENTCLASSOPTIONS$$]{article}</userinput>.</para></listitem> 822 <listitem><para><userinput>$$INPUTENCODING$$</userinput>: If the 823 inputencoding variable is set to, say, <userinput>latin1</userinput> this string is replaced by 824 <userinput>\input[latin1]{inputenc}</userinput>.</para></listitem> 825 </itemizedlist> 826 827 </sect2> 828 829 <sect2 id="templ_wiz"> 830 831 <title>Create a Template from the Wizard</title> 832 833 <para>The easiest way to create a new template is to start the wizard, 834 and then add commands in the editor. Once you have your 835 document set up the way you like:</para> 836 837 <procedure> 838 <step><para>Save your file;</para></step> 839 <step><para>Go to <guimenu>File</guimenu>;</para></step> 840 <step><para>Choose <guimenuitem>Create Template from Document</guimenuitem>;</para></step> 841 <step><para>Make any corrections necessary to the template;</para></step> 842 <step><para>Enter a name for your new template;</para></step> 843 <step><para>Click <guibutton>OK</guibutton> to add your template to the menu.</para></step> 844 </procedure> 845 846 <para>Next time you start up a new document, you will be able to choose 847 your customized template instead of the default ones.</para> 848 849 </sect2> 850 851 <sect2> 852 853 <title>Creating a Template from any File</title> 854 855 <para>A template can be created from any &latex; file. If you are looking for an easy way to 856 configure a template, go find one you like on the Internet and follow the same steps as 857 listed in <xref linkend="templ_wiz" role="select: title pageabbrv"/>.</para> 858 859 <para>For instance, you may want to create a full-fledged A0 poster. These posters are usually seen 860 at scientific conferences, and &latex; will help you make an attractive, catchy poster. You can get a 861 template for A0 posters at <ulink url="http://www.stats.ox.ac.uk/~marchini/a0poster.html">Jonathan Marchini's 862 home page</ulink>, but many more are available. Remember that you will need the <filename>a0poster</filename> 863 package, which is normally not included in standard &tex; distributions. Download it from 864 <ulink url="http://www.ctan.org/tex-archive/macros/latex/contrib/a0poster/">here</ulink> and place it in the same folder as your &latex; file.</para> 865 </sect2> 866 867 <sect2 id="templ_rem"> 868 869 <title>Removing a Template</title> 870 871 <para>To remove a template from &kile;, do as follows:</para> 872 873 <procedure> 874 <step><para>Go to <menuchoice><guimenu>File</guimenu><guimenuitem>Remove 875 Template...</guimenuitem></menuchoice>;</para></step> 876 <step><para>A dialog box will appear with all templates listed: select a template;</para></step> 877 <step><para>Click <guilabel>OK</guilabel>, and your template will be removed.</para></step> 878 </procedure> 879 880 <para>Templates marked with an asterisk (*) cannot be removed without the proper permission.</para> 881 882 </sect2> 883 884 </sect1> 885 886</chapter> 887<chapter id="editing"> 888 889 <title>Editing &latex; Documents</title> 890 891 <para>The internal editor that &kile; uses is &kate;. 892 &kate; is a text editor created for programmers, which incorporates the ability to read 893 and highlight many different types of text files, among which are &latex; and &bibtex;; you can access 894 many options for &kate; directly from &kile;'s <guimenu>Tools</guimenu> menu.</para> 895 896 <para>To learn more about &kate; and its capabilities, see the <ulink url="help:/kate">&kate; Handbook</ulink>. 897 &kile; users can start reading from the chapter <quote>Working with the &kate; Editor</quote>.</para> 898 899 <sect1 id="editing_sect"> 900 901 <title>The &latex; Reference</title> 902 903 <para>&kile; features a very practical &latex; tag reference, which you can access 904 by choosing <menuchoice><guimenu>Help</guimenu><guimenuitem>LaTeX 905 Reference</guimenuitem></menuchoice>. It contains a thorough description 906 of almost all the commands that you may use in &latex; and their syntax.</para> 907 908 </sect1> 909 910 <sect1 id="editing_cursor"> 911 912 <title>Cursor Movements</title> 913 914 <para>To select text, you have the following options:</para> 915 916 <itemizedlist> 917 <listitem><para>Hold left mouse button, and drag mouse to highlight text.</para></listitem> 918 <listitem><para>Click once on a word to move the cursor to a new area.</para></listitem> 919 <listitem><para>Click twice on a word to select the whole word.</para></listitem> 920 <listitem><para>Click twice on a word and pressing <keycombo>&Ctrl;</keycombo> to select the whole &tex; word. 921 This means clicking in this way on <userinput>\par</userinput> from <userinput>\par\bigskip</userinput> only select \par.</para></listitem> 922 <listitem><para>Click three times to select the whole sentence.</para></listitem> 923 </itemizedlist> 924 925 <para>Holding the left mouse button, and dragging the text you want to select, 926 automatically copies the selected text to the clipboard.</para> 927 928 <para>Holding &Shift; and using the arrow keys allows you to select portions of the source 929 code in the editor window.</para> 930 931 </sect1> 932 933 <sect1 id="editing_bracket"> 934 935 <title>Brackets</title> 936 937 <para>Bracket completion is a visual tool that the editor view uses to indicate to you 938 which bracket matches which. If you open any <literal role="extension">.tex</literal> file, 939 and select any bracket, whether it be a parenthesis (), square brackets [] or braces {}, the 940 editor will highlight the bracket and its match in yellow (this default color can be changed). 941 So, for example, if you position the cursor on the braces in 942 <userinput>\section{Introduction}</userinput>, you would see 943 <userinput>\section{Introduction}</userinput> in the default yellow highlight, 944 showing you the location of the beginning and ending brackets.</para> 945 946 </sect1> 947 948 <sect1 id="editing_highlight"> 949 950 <title>Highlighting</title> 951 952 <para>&kile; has the ability to look for and highlight different types of code. For example, &latex; commands 953 are distinguished from normal text, and math formulas are also highlighted in a different color.</para> 954 955 </sect1> 956 957 <sect1 id="editing_bullets"> 958 959 <title>Bullets</title> 960 961 <para>Many wizards can insert optional bullets, a special kind of bookmark within the text. The 962 menu entries <menuchoice><guimenu>Edit</guimenu><guisubmenu>Bullets</guisubmenu></menuchoice> or 963 the corresponding keyboard shortcuts will allow you to jump to the next or last bullet. 964 This will also highlight this bullet so that it will be deleted automatically, 965 when you enter your first letter.</para> 966 967 <screenshot> 968 <screeninfo>Bullets</screeninfo> 969 <mediaobject> 970 <imageobject> 971 <imagedata fileref="bullets.png" format="PNG" /> 972 </imageobject> 973 <textobject> 974 <phrase>Bullets</phrase> 975 </textobject> 976 </mediaobject> 977 </screenshot> 978 979 <variablelist> 980 981 <varlistentry><term><menuchoice> 982 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>Right</keycap></keycombo></shortcut> 983 <guimenuitem>Next Bullet</guimenuitem></menuchoice></term> 984 <listitem><para>Jump to the next bullet in the text if there is one.</para></listitem> 985 </varlistentry> 986 987 <varlistentry><term><menuchoice> 988 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>Left</keycap></keycombo></shortcut> 989 <guimenuitem>Last Bullet</guimenuitem></menuchoice></term> 990 <listitem><para>Jump to the previous bullet in the text if there is one.</para></listitem> 991 </varlistentry> 992 993 </variablelist> 994 995 </sect1> 996 997 <sect1 id="editing_select"> 998 999 <title>Select</title> 1000 1001 <para>Editing is of course one of the main aspects when you use a program like &kile;. 1002 Although &kate; already has great capabilities, &kile; adds some important features, 1003 which are especially needed to write &latex; source. &latex; always needs a lot of 1004 environments and groups, so &kile; supports very special commands to select them. 1005 Under <menuchoice><guimenu>Edit</guimenu><guisubmenu>Select</guisubmenu></menuchoice> 1006 you will find the following commands to select text.</para> 1007 1008 <screenshot> 1009 <screeninfo>Edit->Select items</screeninfo> 1010 <mediaobject> 1011 <imageobject> 1012 <imagedata fileref="select.png" format="PNG" /> 1013 </imageobject> 1014 <textobject> 1015 <phrase>Edit->Select items</phrase> 1016 </textobject> 1017 </mediaobject> 1018 </screenshot> 1019 1020 <variablelist> 1021 <varlistentry><term><menuchoice> 1022 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1023 <keycap>,E</keycap></shortcut> 1024 <guimenuitem>Environment (inside)</guimenuitem></menuchoice></term> 1025 <listitem><para>Select an environment 1026 without the surrounding tags. If this command is called, when an environment 1027 is already selected, &kile; will expand the selection to the next surrounding 1028 environment.</para></listitem> 1029 </varlistentry> 1030 1031 <varlistentry><term><menuchoice> 1032 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1033 <keycap>,F</keycap></shortcut> 1034 <guimenuitem>Environment (outside)</guimenuitem></menuchoice></term> 1035 <listitem><para>Select an environment 1036 including the surrounding tags. This selection can also be expanded with a 1037 second call of this command. </para></listitem> 1038 </varlistentry> 1039 1040 <varlistentry><term><menuchoice> 1041 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1042 <keycap>,T</keycap></shortcut> 1043 <guimenuitem>TeX Group (inside)</guimenuitem></menuchoice></term> 1044 <listitem><para>Select a &tex; group 1045 inside the surrounding braces.</para></listitem> 1046 </varlistentry> 1047 1048 <varlistentry><term><menuchoice> 1049 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1050 <keycap>,U</keycap></shortcut> 1051 <guimenuitem>TeX Group (outside)</guimenuitem></menuchoice></term> 1052 <listitem><para>Select a &tex; group 1053 including the surrounding braces.</para></listitem> 1054 </varlistentry> 1055 1056 <varlistentry><term><menuchoice> 1057 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1058 <keycap>,M</keycap></shortcut> 1059 <guimenuitem>Math Group</guimenuitem></menuchoice></term> 1060 <listitem><para>Select the current math group including the math commands.</para></listitem> 1061 </varlistentry> 1062 1063 <varlistentry><term><menuchoice> 1064 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1065 <keycap>,P</keycap></shortcut> 1066 <guimenuitem>Paragraph</guimenuitem></menuchoice></term> 1067 <listitem><para>Select a whole paragraph, 1068 &ie; a group of text lines separated on both sides by empty lines. 1069 A paragraph does not mean just continuous lines of text, as it is 1070 in other text editors. This extended meaning also includes tables, &latex; 1071 commands and all other lines of source. The only important thing for &kile; 1072 is that this kind of paragraph is separated by two empty lines.</para></listitem> 1073 </varlistentry> 1074 1075 <varlistentry><term><menuchoice> 1076 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1077 <keycap>,L</keycap></shortcut> 1078 <guimenuitem>Line</guimenuitem></menuchoice></term> 1079 <listitem><para>Select the text line of the 1080 current cursor position.</para></listitem> 1081 </varlistentry> 1082 1083 <varlistentry><term><menuchoice> 1084 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> 1085 <keycap>,W</keycap></shortcut> 1086 <guimenuitem>TeX Word</guimenuitem></menuchoice></term> 1087 <listitem><para>Select the word under 1088 the current cursor position. This selection has also en extended meaning, 1089 because this command can also select &latex; commands, which begin with a 1090 backslash and may also have an optional star at the 1091 end.</para></listitem> 1092 </varlistentry> 1093 1094 </variablelist> 1095 1096 <sect2 id="editing_select_latex_commands"> 1097 1098 <title>Select &latex; commands</title> 1099 1100 <para>&kile; has an extended feature to select &latex; commands. If you for example 1101 have typed</para> 1102 1103 <programlisting>text \bfseries\itshape more text</programlisting> 1104 1105 <para> and double click on one of the &latex; commands, both will be selected. 1106 But often you only want to select one of two or more commands. This can be done using 1107 the <keycombo>&Ctrl;</keycombo> key. You only have to press the <keycombo>&Ctrl;</keycombo> key 1108 and a double click will only select the desired command.</para> 1109 1110 </sect2> 1111 1112 </sect1> 1113 1114 <sect1 id="editing_delete"> 1115 1116 <title>Delete</title> 1117 1118 <para>To delete some parts of a document you can of course select them, and then 1119 use the <keycombo><keycap>Delete</keycap></keycombo> key. &kate; also offers the command 1120 <keycombo>&Ctrl;<keycap>K</keycap></keycombo> which deletes the whole line. But &kile; offers a 1121 faster way with its own delete commands. 1122 Under <menuchoice><guimenu>Edit</guimenu><guisubmenu>Delete</guisubmenu></menuchoice> 1123 you will find the following commands to delete text.</para> 1124 1125 <screenshot> 1126 <screeninfo>Edit->Delete items</screeninfo> 1127 <mediaobject> 1128 <imageobject> 1129 <imagedata fileref="delete.png" format="PNG" /> 1130 </imageobject> 1131 <textobject> 1132 <phrase>Edit->Delete items</phrase> 1133 </textobject> 1134 </mediaobject> 1135 </screenshot> 1136 1137 <variablelist> 1138 <varlistentry><term><menuchoice> 1139 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1140 <keycap>,E</keycap></shortcut> 1141 <guimenuitem>Environment (inside)</guimenuitem></menuchoice></term> 1142 <listitem><para>Delete an environment without the surrounding tags.</para></listitem> 1143 </varlistentry> 1144 1145 <varlistentry><term><menuchoice> 1146 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1147 <keycap>,F</keycap></shortcut> 1148 <guimenuitem>Environment (outside)</guimenuitem></menuchoice></term> 1149 <listitem><para>Delete an environment including the surrounding tags.</para></listitem> 1150 </varlistentry> 1151 1152 <varlistentry><term><menuchoice> 1153 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1154 <keycap>,T</keycap></shortcut> 1155 <guimenuitem>TeX Group (inside)</guimenuitem></menuchoice></term> 1156 <listitem><para>Delete a &tex; group inside the surrounding braces.</para></listitem> 1157 </varlistentry> 1158 1159 <varlistentry><term><menuchoice> 1160 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1161 <keycap>,U</keycap></shortcut> 1162 <guimenuitem>TeX Group (outside)</guimenuitem></menuchoice></term> 1163 <listitem><para>Delete a &tex; group including the surrounding braces.</para></listitem> 1164 </varlistentry> 1165 1166 <varlistentry><term><menuchoice> 1167 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1168 <keycap>,M</keycap></shortcut> 1169 <guimenuitem>Math Group</guimenuitem></menuchoice></term> 1170 <listitem><para>Delete the current math group including the math commands.</para></listitem> 1171 </varlistentry> 1172 1173 <varlistentry><term><menuchoice> 1174 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1175 <keycap>,P</keycap></shortcut> 1176 <guimenuitem>Paragraph</guimenuitem></menuchoice></term> 1177 <listitem><para>Delete a whole paragraph. Look at the 1178 <menuchoice><guisubmenu>Select</guisubmenu><guimenuitem>Paragraph</guimenuitem></menuchoice> 1179 command, how a paragraph is 1180 defined in &kile;.</para></listitem> 1181 </varlistentry> 1182 1183 1184 <varlistentry><term><menuchoice> 1185 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1186 <keycap>,I</keycap></shortcut> 1187 <guimenuitem>To End of Line</guimenuitem></menuchoice></term> 1188 <listitem><para>Delete the text from the current cursor position to the end of the line. 1189 </para></listitem> 1190 </varlistentry> 1191 1192 <varlistentry><term><menuchoice> 1193 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo> 1194 <keycap>,W</keycap></shortcut> 1195 <guimenuitem>TeX Word</guimenuitem></menuchoice></term> 1196 <listitem><para>Delete the word or &latex; 1197 command under the current cursor position.</para></listitem> 1198 </varlistentry> 1199 1200 </variablelist> 1201 1202 </sect1> 1203 1204 <sect1 id="editing_environment"> 1205 1206 <title>Environment</title> 1207 1208 <para>It has already been mentioned that environments are a central point in &latex;. 1209 So &kile; offers five other commands to make the work with &latex; as easy as possible 1210 under submenus <menuchoice><guimenu>Edit</guimenu><guisubmenu>Environment</guisubmenu></menuchoice>.</para> 1211 1212 <screenshot> 1213 <screeninfo>Edit->Environment items</screeninfo> 1214 <mediaobject> 1215 <imageobject> 1216 <imagedata fileref="environment.png" format="PNG" /> 1217 </imageobject> 1218 <textobject> 1219 <phrase>Edit->Environment items</phrase> 1220 </textobject> 1221 </mediaobject> 1222 </screenshot> 1223 1224 <variablelist> 1225 1226 <varlistentry><term><menuchoice> 1227 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo> 1228 <keycap>,B</keycap></shortcut> 1229 <guimenuitem>Go to Begin</guimenuitem></menuchoice></term> 1230 <listitem><para>This command will jump to the beginning of the current environment, 1231 wherever your current position is. The cursor will be placed directly 1232 in front of the opening environment tag.</para></listitem> 1233 </varlistentry> 1234 1235 <varlistentry><term><menuchoice> 1236 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo> 1237 <keycap>,E</keycap></shortcut> 1238 <guimenuitem>Go to End</guimenuitem></menuchoice></term> 1239 <listitem><para>This command will jump to the end of the current environment, 1240 wherever your current position is. The cursor will be placed directly 1241 behind the closing environment tag.</para></listitem> 1242 </varlistentry> 1243 1244 <varlistentry><term><menuchoice> 1245 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo> 1246 <keycap>,M</keycap></shortcut> 1247 <guimenuitem>Match</guimenuitem></menuchoice></term> 1248 <listitem><para>When your cursor is placed in front of or above the 1249 <userinput>\begin{environment}</userinput> tag, it will be moved to the 1250 opposite end of the environment and vice versa.</para></listitem> 1251 </varlistentry> 1252 1253 <varlistentry><term><menuchoice> 1254 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo> 1255 <keycap>,C</keycap></shortcut> 1256 <guimenuitem>Close</guimenuitem></menuchoice></term> 1257 <listitem><para>Typing a lot of nested environment tags, you may lose 1258 control of all those environments. This command will close the last 1259 opened environment, so that the nested structure of environments 1260 will not be broken.</para></listitem> 1261 </varlistentry> 1262 1263 <varlistentry><term><menuchoice> 1264 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo> 1265 <keycap>,A</keycap></shortcut> 1266 <guimenuitem>Close All</guimenuitem></menuchoice></term> 1267 <listitem><para>This closes all open environments, not only the last opened environment.</para></listitem> 1268 </varlistentry> 1269 1270 </variablelist> 1271 1272 </sect1> 1273 1274 <sect1 id="editing_texgroup"> 1275 1276 <title>&tex; Group</title> 1277 1278 <para>&kile; also offers some special commands for &latex; groups, 1279 which are determined by braces <userinput>{...}</userinput>. In submenu 1280 <menuchoice><guimenu>Edit</guimenu><guisubmenu>TeX Group</guisubmenu></menuchoice> 1281 you will find some important commands, which correspond to those from 1282 <menuchoice><guimenu>Edit</guimenu><guisubmenu>Environment</guisubmenu></menuchoice>. 1283 </para> 1284 1285 <screenshot> 1286 <screeninfo>Edit->TeX Group</screeninfo> 1287 <mediaobject> 1288 <imageobject> 1289 <imagedata fileref="texgroup.png" format="PNG" /> 1290 </imageobject> 1291 <textobject> 1292 <phrase>Edit->TeX Group</phrase> 1293 </textobject> 1294 </mediaobject> 1295 </screenshot> 1296 1297 <variablelist> 1298 <varlistentry><term><menuchoice> 1299 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo> 1300 <keycap>,B</keycap></shortcut> 1301 <guimenuitem>Go to Begin</guimenuitem></menuchoice></term> 1302 <listitem><para>This command will jump to the beginning of the current group, 1303 wherever your current position is. The cursor will be placed directly in front 1304 of the opening brace.</para></listitem> 1305 </varlistentry> 1306 1307 <varlistentry><term><menuchoice> 1308 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo> 1309 <keycap>,E</keycap></shortcut> 1310 <guimenuitem>Go to End</guimenuitem></menuchoice></term> 1311 <listitem><para>This command will jump to the end of the current group, 1312 wherever your current position is. The cursor will be placed directly 1313 behind the closing brace.</para></listitem> 1314 </varlistentry> 1315 1316 <varlistentry><term><menuchoice> 1317 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo> 1318 <keycap>,M</keycap></shortcut> 1319 <guimenuitem>Match</guimenuitem></menuchoice></term> 1320 <listitem><para>When your cursor is placed in front of or behind an 1321 opening brace of a &tex; group, it will be moved to the opposite end of 1322 the group and vice versa.</para></listitem> 1323 </varlistentry> 1324 1325 <varlistentry><term><menuchoice> 1326 <shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo> 1327 <keycap>,C</keycap></shortcut> 1328 <guimenuitem>Close</guimenuitem></menuchoice></term> 1329 <listitem><para>Typing a lot of nested group braces may be hard work. 1330 This command will close the last opened group, so that the nested 1331 structure of &tex; groups will not be broken.</para></listitem> 1332 </varlistentry> 1333 1334 </variablelist> 1335 1336 </sect1> 1337 1338 <sect1 id="editing_dblquotes"> 1339 1340 <title>Double Quotes</title> 1341 1342 <para>In &latex;, two single quotes are used as double quotes. To 1343 help you insert these efficiently, &kile; allows you to press 1344 <keycap>"</keycap> to insert two opening 1345 single quotes. Furthermore, if you want to close a quotation, you also 1346 have to press <keycap>"</keycap>. &kile; will 1347 be smart enough to recognize this situation and inserts two closing quotes 1348 for &latex;.</para> 1349 1350 <para>To get a literal double quote on the other side, press 1351 <keycap>"</keycap> twice.</para> 1352 1353 <para>You can enable or disable this auto insertion of opening and 1354 closing double quotes in section 1355 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure 1356 Kile...</guisubmenu><guimenuitem>LaTeX</guimenuitem></menuchoice>.</para> 1357 1358 <screenshot> 1359 <screeninfo>Double Quotes</screeninfo> 1360 <mediaobject> 1361 <imageobject> 1362 <imagedata fileref="config-dblquotes.png" format="PNG" /> 1363 </imageobject> 1364 <textobject> 1365 <phrase>Double Quotes</phrase> 1366 </textobject> 1367 </mediaobject> 1368 </screenshot> 1369 1370 <para>If you also include language-specific options 1371 like <userinput>ngerman</userinput> or <userinput>french</userinput>, 1372 you will also be able to use German or French double quotes. Many more languages are available. 1373 </para> 1374 1375 </sect1> 1376 1377 <sect1 id="editing_smartnewline"> 1378 1379 <title>Smart Newline</title> 1380 1381 <para>If you press <keycombo>&Ctrl;<keycap>Return</keycap></keycombo>, 1382 &kile; inserts an intelligent newline. If your current position 1383 is inside a list environment, like <userinput>enumerate</userinput> 1384 or <userinput>itemize</userinput>, &kile; will not only insert 1385 a newline, but also add a <userinput>\item</userinput> command.</para> 1386 1387 <para>If you are inside a tabular environment, &kile; will finish the 1388 current line with <userinput>\\</userinput>, followed by the newline.</para> 1389 1390 <para>If you are inside a &latex; comment, &kile; will start the next line with a 1391 <userinput>%</userinput>.</para> 1392 1393 <para>Even better, &kile; is smart enough to support predefined &latex; 1394 and user defined environments, which can be added in section 1395 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure 1396 Kile...</guisubmenu><guimenuitem>LaTeX</guimenuitem></menuchoice>.</para> 1397 1398 </sect1> 1399 1400 <sect1 id="editing_tabulator"> 1401 1402 <title>Smart Tabulator</title> 1403 1404 <para>Some users like to arrange columns in tabular environments and 1405 put all ampersand characters <keycap>&</keycap> beneath each other. &kile; tries 1406 to support this. If you press <keycombo>&Alt;&Shift;<keycap>&</keycap></keycombo>, 1407 &kile; will look for the next tab in the row above. Although this tab may not be the 1408 corresponding tab, &kile; will add some spaces to adjust the column position with 1409 the current tab.</para> 1410 1411 </sect1> 1412 1413</chapter> 1414 1415<chapter id="completion"> 1416 1417 <title>Code Completion</title> 1418 1419 <para>Although &kate; already offers a good completion mode, &kile; extends 1420 code completion to support some special methods especially for &latex;. Five different 1421 modes are integrated. Three of them work on demand, the other two are autocompletion 1422 modes. All modes can be configured to work very differently at 1423 <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Kile...</guimenuitem></menuchoice>.</para> 1424 1425 <sect1 id="complete_autoenvironment"> 1426 1427 <title>Automatic Environment Completion</title> 1428 1429 <para>When you begin a new environment, typing <userinput>\begin{environment}</userinput>, 1430 &kile; will automatically add an <userinput>\end{environment}</userinput> command, with a 1431 line in between for your text.</para> 1432 1433 <para>Autocompletion can be turned off in the &latex; section of 1434 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 1435 <guimenuitem>LaTeX</guimenuitem><guilabel>Environments</guilabel></menuchoice>.</para> 1436 1437 <screenshot> 1438 <screeninfo>Completing an Equation Environment</screeninfo> 1439 <mediaobject> 1440 <imageobject> 1441 <imagedata fileref="snap_autocomplete.png" format="PNG" /> 1442 </imageobject> 1443 <textobject> 1444 <phrase>Completing an Equation Environment</phrase> 1445 </textobject> 1446 <caption><para>Completing an Equation Environment</para></caption> 1447 </mediaobject> 1448 </screenshot> 1449 1450 </sect1> 1451 1452 <sect1 id="complete_command"> 1453 1454 <title>&latex; Commands</title> 1455 1456 <para>When you type some letters, you can activate this completion mode for &latex; commands 1457 and normal words with <menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>(La)TeX Command</guimenuitem></menuchoice> or the keyboard shortcut 1458 <keycombo>&Ctrl;&Shift;<keycap>Space</keycap></keycombo>. 1459 &kile; first reads the letters from the current cursor position to the 1460 left and stops at the first non-letter character or a backslash. If this 1461 pattern begins with a backslash, &kile; will enter completion mode for &tex; or &latex; 1462 commands. Otherwise it enters normal dictionary mode, where you will not find any 1463 &latex; commands. Depending on the chosen mode, a completion box will be opened. 1464 You will see all commands or words whose beginning matches the current pattern. 1465 You can navigate with the cursor keys through this list and select one entry with 1466 &Enter; or a double click with the mouse.</para> 1467 1468 <screenshot> 1469 <screeninfo>Completing a LaTeX Command</screeninfo> 1470 <mediaobject> 1471 <imageobject> 1472 <imagedata fileref="complete_cmd1.png" format="PNG" /> 1473 </imageobject> 1474 <textobject> 1475 <phrase>Completing a LaTeX Command</phrase> 1476 </textobject> 1477 </mediaobject> 1478 </screenshot> 1479 1480 <para>When you push the &Backspace; key, the last letter of your 1481 pattern will be deleted, and the completion list may grow. On the other hand, if 1482 you type another letter it will expand the pattern and the 1483 visible word list may shrink.</para> 1484 1485 <para>If you decide not to select any of the suggestions, you can leave this 1486 dialog with &Esc;.</para> 1487 1488 <para>You will see that all commands are written with a short description of 1489 their parameters. These descriptions are of course stripped when you select a command. 1490 Optionally you can let &kile; insert bullets at these places, so that you can easily 1491 jump to these positions with <menuchoice><guimenu>Edit</guimenu><guisubmenu>Bullets</guisubmenu><guimenuitem>Next Bullet</guimenuitem></menuchoice> 1492 and insert the parameter you want.</para> 1493 1494 <screenshot> 1495 <screeninfo>Completing a LaTeX Command</screeninfo> 1496 <mediaobject> 1497 <imageobject> 1498 <imagedata fileref="complete_cmd2.png" format="PNG" /> 1499 </imageobject> 1500 <textobject> 1501 <phrase>Completing a LaTeX Command</phrase> 1502 </textobject> 1503 </mediaobject> 1504 </screenshot> 1505 1506 <para>Go to 1507 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 1508 <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice> 1509 to configure one or more of these lists. You can choose different word lists 1510 for &tex; and &latex; commands and dictionary mode for normal words.</para> 1511 1512 <para>If you choose the option <guimenuitem>Show Latex commands</guimenuitem>, 1513 the entries of all chosen compressed word list (cwl) files for &latex; command completion are shown in a 1514 separate view of &kile;'s sidebar. You will see 1515 which commands are available and what parameters and options must or can be 1516 given for a completion. You can also simply select one entry with a mouse click 1517 and it will be inserted into the document, with all named parameters and 1518 options stripped.</para> 1519 1520 <screenshot> 1521 <screeninfo>LaTeX commands in the sidebar</screeninfo> 1522 <mediaobject> 1523 <imageobject> 1524 <imagedata fileref="command-view.png" format="PNG" /> 1525 </imageobject> 1526 <textobject> 1527 <phrase>LaTeX commands in the sidebar</phrase> 1528 </textobject> 1529 </mediaobject> 1530 </screenshot> 1531 1532 <para>As each chosen word list will be shown in a separate view of its own, 1533 there could be too many views, so that &kile;'s main window may be larger 1534 than a small screen allows. As this looks very ugly, &kile; works with a maximum 1535 number of allowed views, which by default is set to 10. If this value is too big 1536 for your screen, you should reduce it.</para> 1537 1538 </sect1> 1539 1540 <sect1 id="complete_environment"> 1541 1542 <title>Environments</title> 1543 1544 <para>The <emphasis>command mode</emphasis> is not useful for code completion of environments. 1545 You always have to type some letters of <userinput>\begin</userinput>, and invoking 1546 the completion mode will result in a huge list of environment tags. On the other 1547 hand, environments are so often used that &kile; offers a special mode for code completion of 1548 environments. Forget the opening tag and write, for example, <userinput>al</userinput>.</para> 1549 1550 <para>When you call the completion mode with 1551 <menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>Environment</guimenuitem></menuchoice> or keyboard shortcut <keycombo>&Alt;&Shift;<keycap>Space</keycap></keycombo>, 1552 the opening tag is automatically added and you will see <userinput>\begin{al}</userinput>. 1553 After this change, the completion list is much less cluttered.</para> 1554 1555 <screenshot> 1556 <screeninfo>Completing a LaTeX Command</screeninfo> 1557 <mediaobject> 1558 <imageobject> 1559 <imagedata fileref="complete_env1.png" format="PNG" /> 1560 </imageobject> 1561 <textobject> 1562 <phrase>Completing a LaTeX Command</phrase> 1563 </textobject> 1564 </mediaobject> 1565 </screenshot> 1566 1567 <para>Now select an environment, and you will see that it is also automatically closed. 1568 Even more, if &kile; recognizes it as a list environment, it will also insert a first 1569 <userinput>\item</userinput> tag.</para> 1570 1571 <screenshot> 1572 <screeninfo>Completing a LaTeX Command</screeninfo> 1573 <mediaobject> 1574 <imageobject> 1575 <imagedata fileref="complete_env2.png" format="PNG" /> 1576 </imageobject> 1577 <textobject> 1578 <phrase>Completing a LaTeX Command</phrase> 1579 </textobject> 1580 </mediaobject> 1581 </screenshot> 1582 1583 <para>Go to 1584 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 1585 <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice> 1586 to configure one or more of these lists. This mode uses the same word lists as the 1587 completion mode for &tex; and &latex; commands.</para> 1588 1589 </sect1> 1590 1591 <sect1 id="complete_abbreviation"> 1592 1593 <title>Abbreviations</title> 1594 1595 <para>&kile; supports user defined lists of abbreviations, which are replaced 1596 on demand by longer text strings. Look at 1597 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 1598 <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice> 1599 to configure one or more of these lists. For the example given here, the 1600 abbreviation list in <filename>example.cwl</filename> must be chosen. 1601 In this file you will find, for example, the entry <userinput>L=\LaTeX</userinput>.</para> 1602 1603 <para>For example, type only the letter <userinput>L</userinput>. Now invoke 1604 the abbreviation mode of word completion with 1605 <menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>Abbreviation</guimenuitem></menuchoice> or keyboard shortcut <keycombo>&Ctrl;&Alt;<keycap>Space</keycap></keycombo>, 1606 and the letter <userinput>L</userinput> is replaced by the string 1607 <userinput>\LaTeX</userinput>.</para> 1608 1609 <para>Abbreviation completion also supports newline <userinput>%n</userinput> and <userinput>%C</userinput> 1610 to place the cursor, if these characters are present in the expansion text. 1611 So if you have the entry</para> 1612 1613 <programlisting>en1=\begin{enumerate}%n\item %C%n\end{enumerate}%n</programlisting> 1614 1615 <para>in the completion file, and invoke the abbreviation completion, 1616 the expansion looks as below, where <userinput>x</userinput> shows the final cursor position.</para> 1617 1618<programlisting>\begin{enumerate} 1619 \item x 1620\end{enumerate}</programlisting> 1621 1622 <sect2 id="complete_abbrev_view"> 1623 1624 <title>Abbreviations</title> 1625 1626 <para>If you choose <guimenuitem>Show abbreviations</guimenuitem>, all possible 1627 abbreviations are shown in a view of the sidebar. So you will have a good survey 1628 of all possible abbreviations.</para> 1629 1630 </sect2> 1631 1632 </sect1> 1633 1634 <sect1 id="complete_auto"> 1635 1636 <title>Autocompletion Modes</title> 1637 1638 <sect2 id="complete_autolatex"> 1639 1640 <title>&latex; Commands</title> 1641 1642 <para>You can also enable an autocompletion mode for &latex; commands. 1643 When a given threshold of letters (default: 3) is entered, a popup window opens 1644 with a list of all matching &latex; commands. You can select one of these commands, 1645 or ignore this window and type further letters. The entries of the completion box 1646 will always change and match your currently typed word.</para> 1647 1648 <para>Go to 1649 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 1650 <guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice> 1651 to enable or disable this mode or to change the threshold.</para> 1652 1653 <screenshot> 1654 <screeninfo>Completing an Equation Environment</screeninfo> 1655 <mediaobject> 1656 <imageobject> 1657 <imagedata fileref="config-complete.png" format="PNG" /> 1658 </imageobject> 1659 <textobject> 1660 <phrase>Completing an Equation Environment</phrase> 1661 </textobject> 1662 </mediaobject> 1663 </screenshot> 1664 1665 </sect2> 1666 1667 <sect2 id="complete_autotext"> 1668 1669 <title>Document Words</title> 1670 1671 <para>Large dictionaries are not useful in autocompletion mode. But, we have seen 1672 that a lot of words in a document are typed more than once. So &kile; offers a 1673 completion for all words from the document that the user has already typed. 1674 You can manually invoke this completion, if you press 1675 <keycombo>&Ctrl;<keycap>Space</keycap></keycombo>. Note that 1676 this mode is different from the completion mode for &latex; commands.</para> 1677 1678 <para>If you want to turn this mode on or off, go to 1679 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 1680 <guimenuitem>Editor</guimenuitem><guimenuitem>Editing</guimenuitem><guilabel>Auto Completion</guilabel></menuchoice>. 1681 In this dialog you can configure if completion mode for 1682 document words should be enabled. There is also an additional autocompletion mode, 1683 where a completion box pops up, when a certain threshold is reached.</para> 1684 1685 </sect2> 1686 1687 </sect1> 1688 1689 <sect1 id="complete_own_files"> 1690 1691 <title>Writing Own Completion Files</title> 1692 1693 <para>The latest specification of the completion file format can found in the 1694 <ulink url="https://commits.kde.org/kile?path=README.cwl"> 1695 CWL file format specification</ulink>. 1696 </para> 1697 1698 <para> 1699 Completion files can be installed in a user's home folder under the <filename>~/.kde/share/apps/kile/complete/<mode>/</filename> 1700 subdirectory, where <parameter><mode></parameter> either stands for <constant>abbreviation</constant>, <constant>dictionary</constant> or <constant>tex</constant>. 1701 </para> 1702 1703 </sect1> 1704</chapter> 1705 1706<chapter id="wizard"> 1707 1708 <title>Wizards and Dialogs</title> 1709 1710 <sect1 id="wizard_quickstart"> 1711 1712 <title>QuickStart Wizard</title> 1713 1714 <para>This wizard has already been described in the section <xref linkend="intro_docwizard" role="select: title pageabbrv"/>.</para> 1715 1716 </sect1> 1717 1718 <sect1 id="wizard_graphics"> 1719 1720 <title>Include Graphics</title> 1721 1722 <para>The <guilabel>Include Graphics</guilabel> dialog makes insertion of 1723 graphics as easy as possible. You can reach it via the menubar with <menuchoice><guimenu>LaTeX</guimenu><guimenuitem>Image 1724 Insertion</guimenuitem></menuchoice>. Please take a look at 1725 <xref linkend="build_graphics" role="select: title pageabbrv"/> and <xref linkend="build_epsgraphics" role="select: title pageabbrv"/> to 1726 get an overview of some basic facts concerning graphic formats.</para> 1727 1728 <screenshot> 1729 <screeninfo>Including a graphics element</screeninfo> 1730 <mediaobject> 1731 <imageobject> 1732 <imagedata fileref="includegraphics.png" format="PNG" /> 1733 </imageobject> 1734 <textobject> 1735 <phrase>Including a graphics element</phrase> 1736 </textobject> 1737 </mediaobject> 1738 </screenshot> 1739 1740 <procedure> 1741 <step><para>Choose a graphics file. This can be a JPEG, PNG, PDF, EPS 1742 or even a zipped or gzipped EPS file. If you have installed 1743 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink> 1744 and also configured &kile; to use it 1745 (<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 1746 <guimenuitem>LaTeX</guimenuitem><guilabel>Graphics</guilabel></menuchoice>), 1747 the width and the height of the graphic is automatically shown. 1748 If &imagemagick; can determine a resolution, the size of the graphics 1749 is also shown in centimeters.</para></step> 1750 1751 <step><para>Decide whether your image shall be centered on the page.</para></step> 1752 1753 <step><para>Choose whether you want the <userinput>\graphicspath</userinput> 1754 notation for your graphics file.</para> 1755 1756 <para>By default graphics files have to be in the same 1757 folder as your master document. However, 1758 it is possible to put them in other folders to make 1759 things tidier. Without a <userinput>\graphicspath</userinput> 1760 command, &kile; would include the path for the graphics file. 1761 But if you use <userinput>\graphicspath</userinput> in your 1762 preamble like this:</para> 1763 1764 <programlisting>\graphicspath{{/path/to/my/graphics}{other/path/to/more/graphics}}</programlisting> 1765 1766 <para>and check this option, &kile; will only use the 1767 base name of the graphics file.</para> 1768 1769 <para>Another example: if you set <userinput>\graphicspath</userinput> 1770 command like:</para> 1771 1772 <programlisting>\graphicspath{{./}{camera/}{images/}}</programlisting> 1773 1774 <para>&latex; will search in the current folder, then in 1775 <filename>camera</filename> and finally in 1776 <filename>images</filename> to find your graphics file.</para></step> 1777 1778 <step><para>If you choose either a width or a height, the whole graphics 1779 will be proportionally scaled. If you set two values for width and height 1780 at the same time, width and height may be scaled with different factors, 1781 and this could not be what you want. See also the information near the top 1782 of the dialog to know the original size of the graphics.</para></step> 1783 1784 <step><para>Insert an angle by which to rotate the graphics counterclockwise.</para></step> 1785 1786 <step><para>The bounding-box information is set automatically 1787 when you choose a graphics file. This information is only needed 1788 when you work with traditional &latex; and bitmapped graphics. 1789 See the discussion of <link linkend="build_epsgraphics">EPS graphics</link>. 1790 </para> 1791 1792 <para>If &latex; needs a bounding box and you do not want to generate a bb file, 1793 &kile; supports this option. On the other hand, &pdflatex; will give a warning 1794 when you want to include a png or jpg graphics with this option. This checkbox 1795 enables or disables the bounding-box option.</para></step> 1796 1797 <step><para>Scale the image by the desired scale factor. ⪚, 0.5 to reduce by half, 1798 or 2 to double. When you use this option, you do not have to set a width or height for 1799 the image.</para></step> 1800 1801 <step><para>In the <guilabel>Trim Image</guilabel> tab you can crop your 1802 image in all four directions.</para></step> 1803 1804 <step> 1805 <para>Finally, you have to specify whether you want to embed this image into a 1806 figure environment. When you want the text to wrap around the figure, use the wrapfigure environment instead. 1807 </para> 1808 <note> 1809 <para>When you choose the wrapfigure environment, you need to include the wrapfig package in your preamble.</para> 1810 </note> 1811 <para>In either case you can insert a 1812 caption and a label for your image. Generally, it is a good idea to add a different prefix to 1813 each kind of label. It is common to use the prefix <userinput>fig:</userinput> for images. 1814 </para> 1815 </step> 1816 1817 <step><para>If you pick the figure environment, you can choose where &latex; should preferably position the figure. 1818 </para></step> 1819 <step> 1820 <para>In the wrapfigure environment you can:</para> 1821 <substeps> 1822 <step><para> 1823 Pick a placement rule for the figure and decide whether the figure should float or not. 1824 In a two-sided document you can define whether the figure should be on the inside or outside edge of the page. 1825 </para></step> 1826 <step><para> 1827 Define how many shortened lines of the text are set alongside the figure. If you leave this empty, &latex; will determine this itself as 1828 well as is possible. 1829 </para></step> 1830 <step><para> 1831 Define an overhang to the chosen side. This is especially useful when you have columns in your document and you want 1832 a figure to span over more than just one column or you want shortened text on both sides of the figure. 1833 </para></step> 1834 <step><para> 1835 Choose a width for the figure. This should be a bit bigger than the actual image width, so there will be some empty 1836 space between the figure and the text. 1837 </para></step> 1838 </substeps> 1839 </step> 1840 </procedure> 1841 1842 </sect1> 1843 1844 <sect1 id="wizard_array"> 1845 1846 <title>Arrays and tabulars</title> 1847 1848 <para>One of the most boring jobs one can do in &latex; is to write a matrix or a 1849 tabular environment. One has to keep track of all the elements, ensure that the environment 1850 is well formed, and that all things are where they are supposed to be. Good indentation helps, 1851 but there is a simpler way: using &kile;'s <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Array</guimenuitem></menuchoice> 1852 or 1853 <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Tabular</guimenuitem></menuchoice> menu entries. 1854 You will then have a matrix-style input form that you can easily fill in with your entries. This dialog also 1855 offers some options to typeset the tabular material.</para> 1856 1857 <screenshot> 1858 <screeninfo>Inserting a tabular environment</screeninfo> 1859 <mediaobject> 1860 <imageobject> 1861 <imagedata fileref="dialog-tabular.png" format="PNG" /> 1862 </imageobject> 1863 <textobject> 1864 <phrase>Inserting a tabular environment</phrase> 1865 </textobject> 1866 </mediaobject> 1867 </screenshot> 1868 1869 <para> 1870 Using the toolbar on top of the dialog you can set the <userinput>align</userinput> of a cell, define a certain <userinput>font style</userinput>, 1871 <userinput>join</userinput> and <userinput>split</userinput> cells, choose a <userinput>border</userinput>, and specify background and font 1872 <userinput>colors</userinput>. 1873 On the extreme right there is a <guilabel>Paste</guilabel> button. With this button you can insert a table 1874 from the clipboard into the dialog, which allows you to copy and paste tables from a spreadsheet program, for example. 1875 </para> 1876 1877 <para> 1878 Below you can choose how many rows and columns you want, and you can tweak some more details about your array: 1879 </para> 1880 1881 <itemizedlist> 1882 <listitem><para> 1883 With the <guilabel>Name</guilabel> option you can select which environment should be used for your array or tabular material. 1884 </para></listitem> 1885 <listitem><para> 1886 You can select the vertical cell alignment with the <guilabel>Parameter</guilabel> option. This is only enabled for 1887 environments which support that feature. 1888 </para></listitem> 1889 <listitem><para> 1890 If it exists for the selected environment, you can select <guilabel>use starred version</guilabel>. When you select this option, 1891 you also have to specify a <guilabel>table width</guilabel>. 1892 </para></listitem> 1893 <listitem><para> 1894 Tables sometimes look nicer when you select the <guilabel>use booktabs package</guilabel> option. 1895 </para></listitem> 1896 <listitem><para> 1897 Of course, you can also <guilabel>Center</guilabel> your whole array. 1898 </para></listitem> 1899 <listitem><para> 1900 <guilabel>Inserting bullets</guilabel> helps you when you want to fill in your content in the editor. With this option 1901 checked, &kile; will insert bullet placeholders for each element of your array. 1902 </para></listitem> 1903 </itemizedlist> 1904 1905 <para>The <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Tabbing</guimenuitem></menuchoice> option will display a simpler 1906 dialog to quickly set up a tabbing environment. It allows you to easily specify the 1907 number of rows or columns and the required spacing.</para> 1908 </sect1> 1909 1910 <sect1 id="wizard_float"> 1911 <title>Inserting floating elements</title> 1912 1913 <para>&kile; helps you with inserting your floating elements. With the 1914 <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Floats</guimenuitem></menuchoice> wizard it is very simple to create 1915 a new figure or table environment. 1916 </para> 1917 1918 <screenshot> 1919 <screeninfo>Inserting a floating element</screeninfo> 1920 <mediaobject> 1921 <imageobject> 1922 <imagedata fileref="dialog-float.png" format="PNG" /> 1923 </imageobject> 1924 <textobject> 1925 <phrase>Inserting a floating element</phrase> 1926 </textobject> 1927 </mediaobject> 1928 </screenshot> 1929 1930 <para> 1931 To insert a new floating environment just follow these steps: 1932 </para> 1933 1934 <procedure> 1935 <step> 1936 <para> 1937 Choose whether you want to insert a figure or a table. 1938 </para> 1939 </step> 1940 <step> 1941 <para> 1942 Select the desired positioning rules. 1943 </para> 1944 </step> 1945 <step> 1946 <para> 1947 Enter a caption for your floating element. 1948 </para> 1949 </step> 1950 <step> 1951 <para> 1952 Type in a label for your new floating element. &kile; will automatically suggest an appropriate prefix , ⪚ "fig:" 1953 for figures and "tab:" for tables. 1954 </para> 1955 </step> 1956 </procedure> 1957 </sect1> 1958 1959 <sect1 id="wizard_math"> 1960 <title>Inserting Math environments</title> 1961 1962 <para>Remembering how all the different math elements work can be really annoying. Of course &kile; can do the 1963 magic for you here: <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Math</guimenuitem></menuchoice></para> 1964 1965 <screenshot> 1966 <screeninfo>Inserting a math element</screeninfo> 1967 <mediaobject> 1968 <imageobject> 1969 <imagedata fileref="dialog-math.png" format="PNG" /> 1970 </imageobject> 1971 <textobject> 1972 <phrase>Inserting a math element</phrase> 1973 </textobject> 1974 </mediaobject> 1975 </screenshot> 1976 1977 <para> 1978 Options: 1979 </para> 1980 <itemizedlist> 1981 <listitem><para><guilabel>Name:</guilabel> Choose the type of math element you want to create.</para></listitem> 1982 <listitem><para><guilabel>Without numbering:</guilabel> This can switch numbering off for numbered 1983 elements like equations or aligns.</para></listitem> 1984 <listitem><para><guilabel>Space command to separate groups:</guilabel> In an environment which supports several 1985 groups like alignat, you can define a space separator when you have more than one group. You can enter any space command here, 1986 which exists in mathmode, ⪚ \quad. </para></listitem> 1987 <listitem><para><guilabel>Standard tabulator:</guilabel> Select the tabulator which should be used. 1988 &kile; should automatically pick the right one for you here.</para></listitem> 1989 <listitem><para><guilabel>Displaymath mode:</guilabel> For environments like matrices or arrays you can 1990 choose which math environment your mathematical text should be displayed with. </para></listitem> 1991 <listitem><para><guilabel>Use bullets:</guilabel> With this option checked, &kile; will insert bullet 1992 placeholders for each element of your mathematical text.</para></listitem> 1993 </itemizedlist> 1994 </sect1> 1995 1996 <sect1 id="wizard_postscript"> 1997 1998 <title>&PostScript; Utilities</title> 1999 2000 <para>PS files are not so popular as PDF files, but are an excellent base 2001 for manipulations and rearrangements of pages. If you need PDF 2002 output, you can rearrange pages with some &PostScript; utilities and then 2003 convert it to PDF with <command>ps2pdf</command>.</para> 2004 2005 <para>The <emphasis>&PostScript; Wizard</emphasis> under <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Postscript 2006 Tools</guimenuitem></menuchoice> will suggest the most 2007 popular rearrangement. The conversion is done 2008 by the programs <command>pstops</command> and <command>psselect</command>, which 2009 can be found in most distributions in the package <userinput>psutils</userinput>. 2010 If one of these programs is not available, the corresponding item will not 2011 be visible.</para> 2012 2013 <screenshot> 2014 <screeninfo>Dialog PSTools</screeninfo> 2015 <mediaobject> 2016 <imageobject> 2017 <imagedata fileref="dialog-pstools.png" format="PNG" /> 2018 </imageobject> 2019 <textobject> 2020 <phrase>Dialog PSTools</phrase> 2021 </textobject> 2022 </mediaobject> 2023 </screenshot> 2024 2025 <para>First choose your input file. If &kile; finds a PS file corresponding to your 2026 current master document, it is already filled in as the input file, but you are also free 2027 to choose another file. Then choose an output file, and select one of the tasks. 2028 Finally, you have to decide whether you want to do the conversion only, or also invoke 2029 &okular; to view the result.</para> 2030 2031 <variablelist> 2032 2033 <varlistentry> 2034 <term>1 A5 page + empty page --> A4</term> 2035 <listitem><para>Combine one A5 page together with one empty page 2036 on one A4 page. Whenever two A5 pages are combined together, 2037 they are rotated 90 degrees and will be arranged 2038 on an A4 page in landscape mode.</para> 2039 <screenshot> 2040 <screeninfo>A5 + empty page</screeninfo> 2041 <mediaobject> 2042 <imageobject> 2043 <imagedata fileref="psutils1.png" format="PNG" /> 2044 </imageobject> 2045 <textobject> 2046 <phrase>A5 + empty page</phrase> 2047 </textobject> 2048 </mediaobject> 2049 </screenshot> 2050 </listitem> 2051 </varlistentry> 2052 2053 <varlistentry> 2054 <term>1 A5 page + duplicate --> A4</term> 2055 <listitem><para>Put one A5 page and a duplicate together 2056 on one A4 page.</para> 2057 <screenshot> 2058 <screeninfo>duplicate A5 pages</screeninfo> 2059 <mediaobject> 2060 <imageobject> 2061 <imagedata fileref="psutils2.png" format="PNG" /> 2062 </imageobject> 2063 <textobject> 2064 <phrase>Duplicate an A5 page</phrase> 2065 </textobject> 2066 </mediaobject> 2067 </screenshot> 2068 </listitem> 2069 </varlistentry> 2070 2071 <varlistentry> 2072 <term>2 A5 pages --> A4</term> 2073 <listitem><para>Put two consecutive A5 pages together 2074 on one A4 page.</para> 2075 <screenshot> 2076 <screeninfo>Combine two A5 pages</screeninfo> 2077 <mediaobject> 2078 <imageobject> 2079 <imagedata fileref="psutils3.png" format="PNG" /> 2080 </imageobject> 2081 <textobject> 2082 <phrase>Combine two A5 pages</phrase> 2083 </textobject> 2084 </mediaobject> 2085 </screenshot> 2086 </listitem> 2087 </varlistentry> 2088 2089 <varlistentry> 2090 <term>2 A5L pages --> A4</term> 2091 <listitem><para>Put two consecutive A5 pages in landscape mode together 2092 on one A4 page.</para></listitem> 2093 </varlistentry> 2094 2095 <varlistentry> 2096 <term>4 A5 pages --> A4</term> 2097 <listitem><para>Combine four consecutive A5 pages together on one 2098 A4 page. The A5 pages have to be scaled with factor 0.7 to fit 2099 on the page.</para> 2100 <screenshot> 2101 <screeninfo>4 A5 pages --> A4</screeninfo> 2102 <mediaobject> 2103 <imageobject> 2104 <imagedata fileref="psutils5.png" format="PNG" /> 2105 </imageobject> 2106 <textobject> 2107 <phrase>4 A5 pages --> A4</phrase> 2108 </textobject> 2109 </mediaobject> 2110 </screenshot> 2111 </listitem> 2112 </varlistentry> 2113 2114 <varlistentry> 2115 <term>1 A4 page + empty page --> A4</term> 2116 <listitem><para>Combine one A4 page together with one empty page 2117 on one A4 page. Whenever two A4 pages are combined together on one 2118 resulting A4 page, they have to be scaled with factor 0.7 and will 2119 be arranged in landscape mode.</para> 2120 <screenshot> 2121 <screeninfo>1 A4 page + empty page --> A4</screeninfo> 2122 <mediaobject> 2123 <imageobject> 2124 <imagedata fileref="psutils6.png" format="PNG" /> 2125 </imageobject> 2126 <textobject> 2127 <phrase>1 A4 page + empty page --> A4</phrase> 2128 </textobject> 2129 </mediaobject> 2130 </screenshot> 2131 </listitem> 2132 </varlistentry> 2133 2134 <varlistentry> 2135 <term>1 A4 page + duplicate --> A4</term> 2136 <listitem><para>Put one A4 page and a duplicate together 2137 on one A4 page.</para> 2138 <screenshot> 2139 <screeninfo>1 A4 page + duplicate --> A4</screeninfo> 2140 <mediaobject> 2141 <imageobject> 2142 <imagedata fileref="psutils7.png" format="PNG" /> 2143 </imageobject> 2144 <textobject> 2145 <phrase>1 A4 page + duplicate --> A4</phrase> 2146 </textobject> 2147 </mediaobject> 2148 </screenshot> 2149 </listitem> 2150 </varlistentry> 2151 2152 <varlistentry> 2153 <term>2 A4 pages --> A4</term> 2154 <listitem><para>Put two consecutive A4 pages together 2155 on one A4 page.</para> 2156 <screenshot> 2157 <screeninfo>Combine two A4 pages</screeninfo> 2158 <mediaobject> 2159 <imageobject> 2160 <imagedata fileref="psutils8.png" format="PNG" /> 2161 </imageobject> 2162 <textobject> 2163 <phrase>Combine two A4 pages</phrase> 2164 </textobject> 2165 </mediaobject> 2166 </screenshot> 2167 </listitem> 2168 </varlistentry> 2169 2170 <varlistentry> 2171 <term>2 A4L pages --> A4</term> 2172 <listitem><para>Put two consecutive A4 pages in landscape mode together 2173 on one A4 page.</para></listitem> 2174 </varlistentry> 2175 2176 <varlistentry> 2177 <term>select even pages</term> 2178 <listitem><para>Select all even pages of a document.</para></listitem> 2179 </varlistentry> 2180 2181 <varlistentry> 2182 <term>select odd pages</term> 2183 <listitem><para>Select all odd pages of a document.</para></listitem> 2184 </varlistentry> 2185 2186 <varlistentry> 2187 <term>select even pages (reverse order)</term> 2188 <listitem><para>Select all even pages of a document and reverse the order.</para></listitem> 2189 </varlistentry> 2190 2191 <varlistentry> 2192 <term>select odd pages (reverse order)</term> 2193 <listitem><para>Select all odd pages of a document and reverse the order.</para></listitem> 2194 </varlistentry> 2195 2196 <varlistentry> 2197 <term>reverse all pages</term> 2198 <listitem><para>Reverse all pages of a document.</para></listitem> 2199 </varlistentry> 2200 2201 <varlistentry> 2202 <term>copy all pages (sorted)</term> 2203 <listitem><para>Copy all pages of a document. You have to 2204 choose the number of sorted copies.</para> 2205 <screenshot> 2206 <screeninfo>Copy all pages (sorted)</screeninfo> 2207 <mediaobject> 2208 <imageobject> 2209 <imagedata fileref="psutils15.png" format="PNG" /> 2210 </imageobject> 2211 <textobject> 2212 <phrase>Copy all pages (sorted)</phrase> 2213 </textobject> 2214 </mediaobject> 2215 </screenshot> 2216 </listitem> 2217 </varlistentry> 2218 2219 <varlistentry> 2220 <term>copy all pages (unsorted)</term> 2221 <listitem><para>Copy all pages of a document. You have to 2222 choose the number of non-sorted copies.</para> 2223 <screenshot> 2224 <screeninfo>Copy all pages (unsorted)</screeninfo> 2225 <mediaobject> 2226 <imageobject> 2227 <imagedata fileref="psutils16.png" format="PNG" /> 2228 </imageobject> 2229 <textobject> 2230 <phrase>Copy all pages (unsorted)</phrase> 2231 </textobject> 2232 </mediaobject> 2233 </screenshot> 2234 </listitem> 2235 </varlistentry> 2236 2237 <varlistentry> 2238 <term>pstops: choose parameter</term> 2239 <listitem><para>There are many options for &PostScript; utilities 2240 <command>pstops</command> and <command>psselect</command>. If you 2241 need a very special one, you can invoke <command>pstops</command> with 2242 an option of your choice. Please read the manual for all possible 2243 options.</para></listitem> 2244 </varlistentry> 2245 2246 <varlistentry> 2247 <term>psselect: choose parameter</term> 2248 <listitem><para>You can invoke <command>psselect</command> with 2249 an option of your choice. Please read the manual for all possible 2250 options.</para></listitem> 2251 </varlistentry> 2252 2253 </variablelist> 2254 2255 </sect1> 2256 2257 <sect1 id="wizard_pdf"> 2258 2259 <title>PDF Utilities</title> 2260 2261 <para>Many people think of PDFs as frozen files, which cannot be modified. But this is not true, as there exist excellent tools</para> 2262 2263 <itemizedlist> 2264 <listitem><para>for manipulations and rearrangements of pages</para></listitem> 2265 <listitem><para>to read and update document info</para></listitem> 2266 <listitem><para>to read, set or change some permissions</para></listitem> 2267 </itemizedlist> 2268 2269 <para>of an existing PDF document.</para> 2270 2271 <para>&kile;'s <emphasis>PDF wizard</emphasis> under <menuchoice><guimenu>Wizard</guimenu><guimenuitem>PDF Tools</guimenuitem></menuchoice> uses two different methods to manipulate and rearrange PDF documents:</para> 2272 2273 <itemizedlist> 2274 <listitem><para>&latex; package <command>pdfpages</command>, which is part of each &latex; distribution. <command>pdfpages</command> doesn't work with encrypted pages.</para></listitem> 2275 <listitem><para><command>pdftk</command>, which is an excellent command line tool for doing everyday things with PDF documents (see <ulink url="http://www.pdflabs.com/tools/pdftk-the-pdf-toolkit">The PDF Toolkit</ulink>).</para></listitem> 2276 </itemizedlist> 2277 2278 <para>If one of these helpers, <command>pdfpages</command> or <command>pdftk</command>, is not present in your system, the corresponding items will not be visible. Furthermore, remember that only <command>pdftk</command> can work with encrypted files.</para> 2279 2280 <sect2 id="pdf_rearrangements"> 2281 2282 <title>Rearrangements</title> 2283 2284 <para>If &kile;'s PDF wizard is called, it starts with the <userinput>Rearrangements</userinput> register card.</para> 2285 2286 <screenshot> 2287 <screeninfo>Dialog PDF Tools</screeninfo> 2288 <mediaobject> 2289 <imageobject> 2290 <imagedata fileref="dialog-pdftools1.png" format="PNG" /> 2291 </imageobject> 2292 <textobject> 2293 <phrase>Dialog PDF Tools</phrase> 2294 </textobject> 2295 </mediaobject> 2296 </screenshot> 2297 2298 <para>First choose your input file. If &kile; finds a PDF file corresponding to your current master document, it will already be filled in as the input file, but you are also free to choose another file. Then choose an output file or overwrite the existing PDF file, and select one of the tasks. Finally, you have to decide whether you want to do the conversion only, or also invoke the viewer (⪚ &okular;) to show the resulting document.</para> 2299 2300 <para>If the PDF file is encrypted, only <command>pdftk</command> will work and you have to give the password of this document to execute tasks.</para> 2301 2302 <variablelist> 2303 2304 <varlistentry> 2305 <term>1 page + empty page --> A4</term> 2306 <listitem><para>Combine one page together with an empty page on one A4 page. Whenever two A5 pages are combined together, they are rotated by 90 degrees and arranged on an A4 page in landscape mode.</para> 2307 <screenshot> 2308 <screeninfo>A5 + empty page</screeninfo> 2309 <mediaobject> 2310 <imageobject> 2311 <imagedata fileref="psutils1.png" format="PNG" /> 2312 </imageobject> 2313 <textobject> 2314 <phrase>A5 + empty page</phrase> 2315 </textobject> 2316 </mediaobject> 2317 </screenshot> 2318 <para>Whenever two A4 pages are combined together, they are scaled, rotated by 90 degrees and arranged on an A4 page in landscape mode.</para> 2319 <screenshot> 2320 <screeninfo>A4 + empty page --> A4</screeninfo> 2321 <mediaobject> 2322 <imageobject> 2323 <imagedata fileref="psutils6.png" format="PNG" /> 2324 </imageobject> 2325 <textobject> 2326 <phrase>A4 + empty page</phrase> 2327 </textobject> 2328 </mediaobject> 2329 </screenshot> 2330 </listitem> 2331 </varlistentry> 2332 2333 <varlistentry> 2334 <term>1 page + duplicate --> A4</term> 2335 <listitem><para>Put one page and a duplicate together on one A4 page.</para> 2336 <screenshot> 2337 <screeninfo>Duplicate a page</screeninfo> 2338 <mediaobject> 2339 <imageobject> 2340 <imagedata fileref="psutils2.png" format="PNG" /> 2341 </imageobject> 2342 <textobject> 2343 <phrase>Duplicate a page</phrase> 2344 </textobject> 2345 </mediaobject> 2346 </screenshot> 2347 <para>If the page to be duplicated has A4 size, it will be scaled to fit on the page.</para> 2348 <screenshot> 2349 <screeninfo>Duplicate a page</screeninfo> 2350 <mediaobject> 2351 <imageobject> 2352 <imagedata fileref="psutils7.png" format="PNG" /> 2353 </imageobject> 2354 <textobject> 2355 <phrase>Duplicate a page</phrase> 2356 </textobject> 2357 </mediaobject> 2358 </screenshot> 2359 </listitem> 2360 </varlistentry> 2361 2362 <varlistentry> 2363 <term>2 pages --> A4</term> 2364 <listitem><para>Combine two consecutive pages together on one A4 page. Whenever two A5 pages are combined together, they are rotated by 90 degrees and arranged on an A4 page in landscape mode.</para> 2365 <screenshot> 2366 <screeninfo>Combine two A5 pages</screeninfo> 2367 <mediaobject> 2368 <imageobject> 2369 <imagedata fileref="psutils3.png" format="PNG" /> 2370 </imageobject> 2371 <textobject> 2372 <phrase>Combine two A5 pages</phrase> 2373 </textobject> 2374 </mediaobject> 2375 </screenshot> 2376 <para>Whenever two A4 pages are combined together, they are scaled, rotated by 90 degrees and arranged on an A4 page in landscape mode.</para> 2377 <screenshot> 2378 <screeninfo>Combine two A4 pages</screeninfo> 2379 <mediaobject> 2380 <imageobject> 2381 <imagedata fileref="psutils8.png" format="PNG" /> 2382 </imageobject> 2383 <textobject> 2384 <phrase>Combine two A4 pages</phrase> 2385 </textobject> 2386 </mediaobject> 2387 </screenshot> 2388 </listitem> 2389 </varlistentry> 2390 2391 <varlistentry> 2392 <term>2 pages (landscape) --> A4</term> 2393 <listitem><para>Put two consecutive pages in landscape mode together on one A4 page.</para> 2394 <screenshot> 2395 <screeninfo>Combine two pages (in landscape mode)</screeninfo> 2396 <mediaobject> 2397 <imageobject> 2398 <imagedata fileref="pdftools1.png" format="PNG" /> 2399 </imageobject> 2400 <textobject> 2401 <phrase>Combine two pages (in landscape mode)</phrase> 2402 </textobject> 2403 </mediaobject> 2404 </screenshot> 2405 </listitem> 2406 </varlistentry> 2407 2408 <varlistentry> 2409 <term>4 pages --> A4</term> 2410 <listitem><para>Combine four consecutive pages together on one 2411 A4 page. The pages have to be scaled to fit on the page.</para> 2412 <screenshot> 2413 <screeninfo>4 pages --> A4</screeninfo> 2414 <mediaobject> 2415 <imageobject> 2416 <imagedata fileref="psutils5.png" format="PNG" /> 2417 </imageobject> 2418 <textobject> 2419 <phrase>4 pages --> A4</phrase> 2420 </textobject> 2421 </mediaobject> 2422 </screenshot> 2423 </listitem> 2424 </varlistentry> 2425 2426 <varlistentry> 2427 <term>4 pages (landscape) --> A4</term> 2428 <listitem><para>Combine four consecutive pages in landscape mode together on one A4 page. The pages have to be scaled to fit on the page.</para> 2429 <screenshot> 2430 <screeninfo>Combine four pages (in landscape mode)</screeninfo> 2431 <mediaobject> 2432 <imageobject> 2433 <imagedata fileref="pdftools2.png" format="PNG" /> 2434 </imageobject> 2435 <textobject> 2436 <phrase>Combine four pages (in landscape mode)</phrase> 2437 </textobject> 2438 </mediaobject> 2439 </screenshot> 2440 </listitem> 2441 </varlistentry> 2442 2443 <varlistentry> 2444 <term>select even pages</term> 2445 <listitem><para>Select all even pages of a document.</para></listitem> 2446 </varlistentry> 2447 2448 <varlistentry> 2449 <term>select odd pages</term> 2450 <listitem><para>Select all odd pages of a document.</para></listitem> 2451 </varlistentry> 2452 2453 <varlistentry> 2454 <term>select even pages (reverse order)</term> 2455 <listitem><para>Select all even pages of a document and reverse the order.</para></listitem> 2456 </varlistentry> 2457 2458 <varlistentry> 2459 <term>select odd pages (reverse order)</term> 2460 <listitem><para>Select all odd pages of a document and reverse the order.</para></listitem> 2461 </varlistentry> 2462 2463 <varlistentry> 2464 <term>reverse all pages</term> 2465 <listitem><para>Reverse all pages of a document.</para></listitem> 2466 </varlistentry> 2467 2468 <varlistentry> 2469 <term>decrypt a file</term> 2470 <listitem><para>If the PDF file is encrypted, you can decrypt it.</para></listitem> 2471 </varlistentry> 2472 2473 <varlistentry> 2474 <term>select pages</term> 2475 <listitem><para>Add a comma separated list of pages or page ranges, ⪚ 1,4-7,9. Only these pages will appear in the resulting PDF file.</para></listitem> 2476 </varlistentry> 2477 2478 <varlistentry> 2479 <term>delete pages</term> 2480 <listitem><para>Add a comma separated list of pages or page ranges, which should be removed from the chosen PDF file.</para></listitem> 2481 </varlistentry> 2482 2483 <varlistentry> 2484 <term>apply a background watermark</term> 2485 <listitem><para>Applies a PDF watermark to the background of a single input PDF. The wizard only uses the first page from the background PDF and applies it to every page of the input PDF. This page is scaled and rotated as needed to fit the input page.</para></listitem> 2486 </varlistentry> 2487 2488 <varlistentry> 2489 <term>apply a background color</term> 2490 <listitem><para>Applies a background color to all pages of the current document. This can only be done once, as the second color will be put behind the first color and will not then be visible.</para></listitem> 2491 </varlistentry> 2492 2493 <varlistentry> 2494 <term>apply a foreground stamp</term> 2495 <listitem><para>Applies a foreground stamp on top of the input PDF document's pages. The wizard uses only the first page from the stamp PDF and applies it to every page of the input PDF. This page is scaled and rotated as needed to fit the input page. This works best if the stamp PDF page has a transparent background.</para></listitem> 2496 </varlistentry> 2497 2498 <varlistentry> 2499 <term>pdftk: choose parameter</term> 2500 <listitem><para>You can invoke <command>pdftk</command> with an option of your choice. Please read the manual for all possible options.</para></listitem> 2501 </varlistentry> 2502 2503 <varlistentry> 2504 <term>pdfpages: choose parameter</term> 2505 <listitem><para>You can invoke <command>pdfpages</command> with an option of your choice. Please read the manual for all possible options.</para></listitem> 2506 </varlistentry> 2507 2508 </variablelist> 2509 2510 </sect2> 2511 2512 <sect2 id="pdf_properties"> 2513 2514 <title>Properties</title> 2515 2516 <para>The setting, changing and removing of properties will only be possible if <command>pdftk</command> is installed and if additionally &kile; was compiled with the <userinput>libpoppler</userinput> library.</para> 2517 2518 <screenshot> 2519 <screeninfo>Dialog PDF Properties</screeninfo> 2520 <mediaobject> 2521 <imageobject> 2522 <imagedata fileref="dialog-pdftools2.png" format="PNG" /> 2523 </imageobject> 2524 <textobject> 2525 <phrase>Dialog PDF Properties</phrase> 2526 </textobject> 2527 </mediaobject> 2528 </screenshot> 2529 2530 <para>Traditional PDF metadata includes the document's title, author, subject, keywords, creator, producer and the dates of creation and last modification.</para> 2531 2532 </sect2> 2533 2534 <sect2 id="pdf_permissions"> 2535 2536 <title>Permissions</title> 2537 2538 <para>Also, the setting, changing and removing of permissions will be only possible if <command>pdftk</command> is installed.</para> 2539 2540 <screenshot> 2541 <screeninfo>Dialog PDF Permissions</screeninfo> 2542 <mediaobject> 2543 <imageobject> 2544 <imagedata fileref="dialog-pdftools3.png" format="PNG" /> 2545 </imageobject> 2546 <textobject> 2547 <phrase>Dialog PDF Permissions</phrase> 2548 </textobject> 2549 </mediaobject> 2550 </screenshot> 2551 2552 <para>A password is necessary to set or change these document settings. Additionally, PDF encryption is done to lock the file's content behind this password or to enforce lighter restrictions imposed by the author. So the author can allow or restrict:</para> 2553 2554 <itemizedlist> 2555 <listitem><para>printing pages</para></listitem> 2556 <listitem><para>modifying pages</para></listitem> 2557 <listitem><para>copying text and graphics from pages</para></listitem> 2558 <listitem><para>changing or adding annotations</para></listitem> 2559 <listitem><para>filling form fields with data.</para></listitem> 2560 </itemizedlist> 2561 2562 <para>Changing permissions always forces encryption associated with 128-bit security of <userinput>Acrobat</userinput> 5 and 6, and also needs a password.</para> 2563 2564 <para>But always remember: encryption and a password do not provide any real PDF security. The content is encrypted, but the key is known. You should see it more as a polite but firm request to respect the author's wishes.</para> 2565 2566 </sect2> 2567 2568 </sect1> 2569 2570 <sect1 id="statistics"> 2571 <title>Document Statistics</title> 2572 2573 <para>The statistics dialog in <menuchoice><guimenu>File</guimenu><guimenuitem>Statistics</guimenuitem></menuchoice> gives you 2574 a statistical overview for a selection, 2575 a document or a whole project. It includes the number of words, &latex; 2576 commands/environments and also includes the number of characters for each type.</para> 2577 2578 <para>The statistics obtained can be copied as text or as a nicely formatted &latex; table 2579 to the clipboard. </para> 2580 <para>When you select a text and open the statistics dialog, you get the statistics for the currently selected text. If 2581 you open the dialog without any text selected, the statistics for all opened files are shown. 2582 If you want to get statistics for the whole project, you can use 2583 <menuchoice><guimenu>Project</guimenu><guisubmenu>Open All Project Files</guisubmenu></menuchoice> 2584 for an easy and quick way to open all source files of your project.</para> 2585 2586 <para>A note of caution has to be sounded about the accuracy of the numbers. 2587 We have included some logic to get a good estimate, ⪚ K\"uhler gives one word and one command, 2588 with six and two characters respectively. But there are other combinations in which parts of commands 2589 are counted as words and vice versa. Please note that the algorithm 2590 was developed and tested for languages similar to English or German. 2591 So don't take the numbers for granted. If you write a report whose length has to be of a certain 2592 numbers of words or characters, please make some tests first in order to check whether &kile;'s accuracy satisfies your needs.</para> 2593 </sect1> 2594 2595</chapter> 2596 2597 2598<chapter id="latex"> 2599 2600 <title>Special Tags in &latex;</title> 2601 2602 <sect1 id="latex_library"> 2603 <title>Using the &latex; Tag Library</title> 2604 2605 <para>&latex; has thousands of tags for symbols and special characters. 2606 The easiest way to insert these tags is to use the sidebar menu, 2607 to the left of the editor window.</para> 2608 2609 <screenshot> 2610 <screeninfo>The Sidebar Menu</screeninfo> 2611 <mediaobject> 2612 <imageobject> 2613 <imagedata fileref="snap_sidebarmenu.png" format="PNG" /> 2614 </imageobject> 2615 <textobject> 2616 <phrase>The Sidebar Menu</phrase> 2617 </textobject> 2618 <caption><para>The Sidebar Menu</para></caption> 2619 </mediaobject> 2620 </screenshot> 2621 <para>The following types are available:</para> 2622 2623 <itemizedlist> 2624 <listitem><para>Most Frequently Used</para></listitem> 2625 <listitem><para>Relation</para></listitem> 2626 <listitem><para>Operators</para></listitem> 2627 <listitem><para>Arrows</para></listitem> 2628 <listitem><para>Miscellaneous Math</para></listitem> 2629 <listitem><para>Miscellaneous Text</para></listitem> 2630 <listitem><para>Delimiters</para></listitem> 2631 <listitem><para>Greek</para></listitem> 2632 <listitem><para>Special Characters</para></listitem> 2633 <listitem><para>Cyrillic Characters</para></listitem> 2634 <listitem><para>User Defined</para></listitem> 2635 </itemizedlist> 2636 <para>The tooltips of the icons show the &latex; commands and additionally needed packages.</para> 2637 <para>Pressing <keycombo>&Shift;</keycombo> and clicking a symbol will result in 2638 <userinput>$\symbolcmd$</userinput> being inserted. Similarly, pressing <keycombo>&Ctrl;</keycombo> 2639 inserts it in curly brackets.</para> 2640 <para>If you insert a command which requires a package which is not included in your &latex; document, 2641 you will see a warning message in the logview window.</para> 2642 <para>The first list of symbols holds the <guilabel>Most Frequently Used</guilabel> symbols. Inserted symbols will be 2643 added to this list, for quick and easy reference. The ordering of the symbols will not be changed 2644 upon addition of new symbols, instead a reference counter is incremented. If the number of items 2645 exceeds 30 items, the item with the lowest count is removed.</para> 2646 <para>The <guilabel>User Defined</guilabel> symbol list can hold your own symbols. 2647 To create your own symbols you need the program gesymb and the file <filename>definitions.tex</filename> from the kile source package. 2648 Additionally you need a &latex; compiler (what a surprise) and 2649 <ulink url="http://www.dvipng.sourceforge.net">&dvipng;</ulink> (version 1.7 or later). 2650 The procedure is that you create a &latex; file with <userinput>\input{definitions}</userinput>, 2651 which makes the commands listed below available, and let <userinput>gesymb mysymbols.tex user</userinput> 2652 (which calls &latex; and &dvipng;) create the icons. After copying them to 2653 <userinput>$HOME/.kde/share/apps/kile/mathsymbols/user/</userinput> and restarting kile you can use your own symbols. 2654 </para> 2655 <para> 2656 The following commands are defined in <filename>definitions.tex</filename>: 2657 <itemizedlist> 2658 <listitem> 2659 <para> 2660 <userinput>\command[\optarg]{\symbol}</userinput>: Include the symbol <userinput>\symbol</userinput> in the 2661 symbol list, the optional argument <userinput>\optarg</userinput> specifies the command which kile should insert. 2662 If it is not given the command in the mandatory argument is used. 2663 </para> 2664 </listitem> 2665 <listitem> 2666 <para> 2667 <userinput>\mathcommand[\optarg]{\symbol}</userinput>: Same as above, except that the command in the mandatory 2668 argument is inserted in math mode. 2669 </para> 2670 </listitem> 2671 <listitem> 2672 <para> 2673 <userinput>\pkgs[arg]{pkg}</userinput>: Declare that the command given in this line needs the &latex; package 2674 <userinput>pkg</userinput> with the optional argument <userinput>arg</userinput>. This command has to be in 2675 front of the <userinput>\command</userinput> command and overrides any package specification by the neededpkgs 2676 enviroment. 2677 </para> 2678 </listitem> 2679 <listitem> 2680 <para> 2681 <userinput>\begin{neededpkgs}[pkgs-args]{pkgs} ... \end{neededpkgs}</userinput>: Has the same effect as 2682 above, but for all enclosed commands. 2683 </para> 2684 </listitem> 2685 </itemizedlist> 2686 </para> 2687 <para> 2688 An example for completeness is given here: 2689<programlisting>\documentclass[a4paper,10pt]{article} 2690\usepackage{amssymb} 2691\input{definitions} 2692% 2693\begin{document} 2694\pagestyle{empty} 2695% 2696\begin{neededpkgs}{amssymb} 2697\mathcommand{\surd} 2698\pkgs{amsmath}\mathcommand[\ddddot{}]{\ddddot{a}} 2699\mathcommand{\angle} 2700\end{neededpkgs} 2701\command{\"A} 2702\mathcommand{\exists} 2703\mathcommand[\stackrel{}{}]{\stackrel{abc}{=}} 2704 2705%\begin{neededpkgs}[russian,koi8-r,T2C,]{babel,inputenc,fontenc,mathtext} 2706% 2707% \end{neededpkgs} 2708% this would need to include the packages 2709% \usepackage{mathtext} 2710% \usepackage[T2C]{fontenc} 2711% \usepackage[russian]{babel} 2712% \usepackage[koi8-r]{inputenc} 2713% just to explain the format 2714\end{document}</programlisting> 2715 </para> 2716 </sect1> 2717 2718 <sect1 id="latex_bib"> 2719 2720 <title>Using Bibitems</title> 2721 2722 <para><userinput>\bibitem</userinput> is a command used to enter a reference in a 2723 <userinput>thebibliography</userinput> environment in your document. The syntax for using 2724 <userinput>\bibitem</userinput> is <userinput>\bibitem[label]{key}</userinput>.</para> 2725 2726 <para>The optional <userinput>[label]</userinput> is for you to add your own 2727 labeling system for the bibliography entry. If no label is set, the entries 2728 will be set in numerical order: [1], [2], [3], &etc;</para> 2729 2730 <para>The argument <userinput>{key}</userinput> is used to reference and link the commands 2731 <userinput>\bibitem</userinput> and <userinput>\cite</userinput> to 2732 each other and the information they contain. The command <userinput>\cite</userinput> contains the 2733 label associated with the intended <userinput>\bibitem</userinput>, which is located inside a 2734 <userinput>thebibliography</userinput> environment, and contains the reference data. 2735 Both corresponding <userinput>\bibitem</userinput> and <userinput>\cite</userinput> must 2736 have the same <userinput>{key}</userinput>; the easiest way to organize keys is by 2737 the author's last name. The secondary braces in the <userinput>thebibliography</userinput> 2738 environment denote the longest bibliography label you expect to have. 2739 So, inserting <userinput>{<replaceable>foo</replaceable>}</userinput> means 2740 you can have any label shorter or as large as the expression 2741 <userinput><replaceable>foo</replaceable></userinput>. Failure to set this parameter correctly 2742 may result in a not so attractive indentation of your bibliography.</para> 2743 2744 <para>The bibliography is a section apart from your main document, and an example of 2745 code for the bibliography would look like the following:</para> 2746 2747<programlisting>\begin{thebibliography}{50} 2748 \bibitem{Simpson} Homer J. Simpson. \textsl{Mmmmm...donuts}. Evergreen Terrace Printing Co., 2749 Springfield, SomewhereUSA, 1998 2750\end{thebibliography}</programlisting> 2751 2752 <para>Then, your main source code would contain the location of the information relating to 2753 the <userinput>\bibitem</userinput> using <userinput>\cite</userinput>. That source code would look similar to this:</para> 2754 2755 <programlisting>My thesis, about the philosophy of The Simpsons\copyright comes from my favorite book \cite{Simpson}.</programlisting> 2756 2757 <para>As it is often difficult to remember the exact citation key once you have many 2758 references, &kile; provides an easy way to insert a citation. Using <menuchoice><guimenu>LaTeX 2759 </guimenu><guimenuitem>References</guimenuitem><guimenuitem>Cite</guimenuitem></menuchoice> 2760 a list with all the citation keys pops up. Select the correct 2761 reference and a citation will be inserted into your document. To update the list of keys, 2762 either save the file, or <menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh 2763 Structure</guimenuitem></menuchoice>, or press <keycap>F12</keycap>. 2764 With code completion enabled, &kile; will show you a list of all the <userinput>bibitem</userinput>-labels 2765 as soon as you open up a <userinput>\cite</userinput> command.</para> 2766 2767 <para>The final result in your document's bibliography would then look like this:</para> 2768 2769 <para><computeroutput>[1] Homer J. Simpson. Mmmmm...donuts. Evergreen Terrace Printing Co., 2770 Springfield, SomewhereUSA, 1998.</computeroutput></para> 2771 2772 <para>&kile; can also work together with &bibtex; editors, 2773 such as &kbibtex; to make it easier to enter citations. When a &bibtex; file is added to the project, 2774 &kile; will help you complete citation commands, just as described above.</para> 2775 2776 </sect1> 2777 2778</chapter> 2779 2780&include-section-usermenu; 2781 2782<chapter id="build"> 2783 2784 <title>The Build Tools</title> 2785 2786 <sect1 id="build_sect"> 2787 2788 <title>Compiling, converting and viewing</title> 2789 2790 <para>To view the result of your work, you first need to compile the source. All the build 2791 tools are grouped closely together in the 2792 <menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu></menuchoice>, 2793 <menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu></menuchoice>, 2794 and <menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu></menuchoice> 2795 menus.</para> 2796 2797 <para>To compile your source code for screen viewers like &okular; or 2798 further conversion, you can use the shortcut <keycombo>&Alt;<keycap>2</keycap></keycombo>. 2799 Then you can view the &DVI; file using your default viewer with 2800 <keycombo>&Alt;<keycap>3</keycap></keycombo>, convert 2801 the &DVI; to a PS file with <keycombo>&Alt;<keycap>4</keycap></keycombo>, 2802 and view the PS file with <keycombo>&Alt;<keycap>5</keycap></keycombo>.</para> 2803 2804 <sect2> 2805 2806 <title>&bibtex;</title> 2807 2808 <para>If you are using <ulink url="http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html">&bibtex;</ulink> 2809 for your bibliography entries, you usually have to follow a special compiling scheme. 2810 This means calling &latex; and then &bibtex; and then &latex; twice again. Fortunately &kile; is clever enough to 2811 detect automatically if it is necessary to call additional tools like &bibtex;, &makeidx; and &asymptote;. 2812 This logic is turned on by default and can be changed in <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure 2813 Kile...</guisubmenu><guisubmenu>Tools</guisubmenu><guilabel>Build</guilabel></menuchoice> in the <guilabel>General</guilabel> tab in the &latex; and &pdflatex; tools. 2814 </para> 2815 2816 </sect2> 2817 2818<!-- Already stated in last paragraph 2819 <sect2> 2820 2821 <title>&makeidx;</title> 2822 2823 <para>If you are using the <ulink url="http://ipagwww.med.yale.edu/latex/makeindex.pdf">&makeidx;</ulink> 2824 package to make a final, alphabetical index for your document, you have also to follow a certain 2825 compilation pattern or let &kile; do this for you in the same way as with &bibtex; files.</para> 2826 2827 </sect2> 2828--> 2829 <sect2> 2830 2831 <title>MetaPost and &asymptote;</title> 2832 2833 <para>If you want to compile your document with <application>MetaPost</application> or <application>&asymptote;</application>, picture drawing programs, you can do it with 2834 <menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu><guimenuitem>Metapost</guimenuitem></menuchoice>, 2835 or <menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu><guimenuitem>&asymptote;</guimenuitem></menuchoice>.</para> 2836 2837 </sect2> 2838 2839 <sect2> 2840 2841 <title>&pdflatex;</title> 2842 2843 <para>There is also another way to compile your document, if you want a PDF: you can run 2844 &pdflatex;, that will compile the source directly into a PDF file, with 2845 <keycombo>&Alt;<keycap>6</keycap></keycombo>: you can then view the compiled 2846 file by pressing <keycombo>&Alt;<keycap>7</keycap></keycombo>.</para> 2847 2848 <para>Alternatively, you can convert a PS into a PDF with 2849 <keycombo>&Alt;<keycap>8</keycap></keycombo>, or a 2850 &DVI; directly into a PDF with <keycombo>&Alt;<keycap>9</keycap></keycombo>.</para> 2851 2852 <para>Using &pdflatex; instead of &latex; may be just a matter of simplicity or habit, 2853 but sometimes the behavior of the two programs can differ.</para> 2854 2855 </sect2> 2856 2857 <sect2> 2858 2859 <title>&latex; to Web</title> 2860 2861 <para>Finally, you may want to publish your work on the web and not just on paper. You may 2862 then use the <application>latex2html</application> program, that can be called from &kile;'s menu 2863 <menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu><guimenuitem>LaTeX 2864 to Web</guimenuitem></menuchoice>. The result will be placed in a subfolder of the work folder, 2865 and you will be able to see the result of the conversion choosing the menu item 2866 <menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu><guimenuitem>View 2867 &HTML;</guimenuitem></menuchoice>.</para> 2868 2869 </sect2> 2870 2871 <sect2 id="build_cl"> 2872 2873 <title>Passing Command Line Parameters</title> 2874 2875 <para>If you want to pass some specific command line parameters to the compile, convert 2876 or view tools, you can configure their call in <menuchoice><guimenu>Settings</guimenu> 2877 <guisubmenu>Configure Kile...</guisubmenu><guisubmenu>Tools</guisubmenu><guilabel>Build</guilabel></menuchoice>.</para> 2878 2879 </sect2> 2880 2881 </sect1> 2882 2883 <sect1 id="build_preview"> 2884 <title>Quick Preview</title> 2885 2886 <para>You will always need some time to view the result, when working with &latex;. 2887 &latex; has to compile the source and the viewer has to be called. This can be 2888 annoying if you only changed some letters in an equation difficult to typeset. 2889 &kile; offers a <emphasis>Quick Preview</emphasis> mode, where you can compile 2890 only a part of a document and save a lot of time. It supports four different modes, 2891 which can be combined with seven configurations.</para> 2892 2893 <screenshot> 2894 <screeninfo>Quick Preview</screeninfo> 2895 <mediaobject> 2896 <imageobject> 2897 <imagedata fileref="quickpreview.png" format="PNG" /> 2898 </imageobject> 2899 <textobject> 2900 <phrase>Quick Preview</phrase> 2901 </textobject> 2902 </mediaobject> 2903 </screenshot> 2904 2905 <para>All settings must be done in 2906 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 2907 <guimenuitem>Tools</guimenuitem><guilabel>Preview</guilabel></menuchoice>.</para> 2908 2909 <screenshot> 2910 <screeninfo>Quick Preview Configuration</screeninfo> 2911 <mediaobject> 2912 <imageobject> 2913 <imagedata fileref="config-quickpreview.png" format="PNG" /> 2914 </imageobject> 2915 <textobject> 2916 <phrase>Quick Preview Configuration</phrase> 2917 </textobject> 2918 </mediaobject> 2919 </screenshot> 2920 2921 <sect2 id="build_qp_selection"> 2922 2923 <title>Selection Mode</title> 2924 2925 <para>The user has to select a part of the document. Menu entry <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Selection</guimenuitem></menuchoice> 2926 or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>S</keycap> 2927 will start the selected programs. &kile; takes the preamble of the original text, so that 2928 all packages and user defined commands are included. The user can choose one 2929 of eight predefined configurations:</para> 2930 2931 <itemizedlist> 2932 <listitem><para><application>LaTeX+&DVI; (embedded viewer)</application></para></listitem> 2933 <listitem><para><application>LaTeX+&DVI; (&okular;)</application></para></listitem> 2934 <listitem><para><application>LaTeX+PS (embedded viewer)</application></para></listitem> 2935 <listitem><para><application>LaTeX+PS (&okular;)</application></para></listitem> 2936 <listitem><para><application>PDFLaTeX+PDF (embedded viewer)</application></para></listitem> 2937 <listitem><para><application>PDFLaTeX+PDF (&okular;)</application></para></listitem> 2938 <listitem><para><application>XeLaTeX+PDF (embedded viewer)</application></para></listitem> 2939 <listitem><para><application>XeLaTeX+PDF (&okular;)</application></para></listitem> 2940 </itemizedlist> 2941 2942 <para>This should be sufficient for all situations for which a quick preview is needed.</para> 2943 2944 </sect2> 2945 2946 <sect2 id="build_qp_environment"> 2947 2948 <title>Environment Mode</title> 2949 2950 <para>Very often you want to preview the current environment, and especially mathematical 2951 environments, which sometimes may be difficult to write. &kile; offers a very fast way 2952 to do this. No selection is needed, just choose 2953 <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Environment</guimenuitem></menuchoice> 2954 or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>E</keycap> 2955 and the current environment will be compiled and shown.</para> 2956 2957 </sect2> 2958 2959 <sect2 id="build_qp_subdocument"> 2960 2961 <title>Subdocument Mode</title> 2962 2963 <para>If you have a large project with a lot of documents, compiling the whole 2964 project is not a great idea, if you have made changes only in one single document. 2965 &kile; is able to compile and show a preview of the current subdocument. It 2966 takes the preamble from the master document and only compiles the current part 2967 when you choose <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Subdocument</guimenuitem></menuchoice> 2968 or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>D</keycap>.</para> 2969 2970 </sect2> 2971 2972 <sect2 id="build_qp_mathgroup"> 2973 2974 <title>Mathgroup Mode</title> 2975 2976 <para>The mathgroup preview mode allows you to preview the mathgroup you are currently editing. &kile; 2977 takes the preamble from the master document and only compiles the mathgroup the cursor is currently in 2978 when you choose <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Mathgroup</guimenuitem></menuchoice> 2979 or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>M</keycap>.</para> 2980 2981 </sect2> 2982 2983 <sect2 id="qp_bottombar"> 2984 2985 <title>Quick Preview in Bottom Bar</title> 2986 2987 <para>Instead of showing the preview in a new document &kile; can also be configured to use the bottom bar for preview 2988 compilations. You can activate this feature in the quick preview configuration panel.</para> 2989 2990 </sect2> 2991 2992 </sect1> 2993 2994 <sect1 id="build_graphics"> 2995 2996 <title>Graphic File Formats</title> 2997 2998 <sect2 id="build_graphics_latex"> 2999 3000 <title>&latex; and &pdflatex;</title> 3001 3002 <para>&pdflatex;, when used with <userinput>graphics</userinput> or 3003 <userinput>graphicx</userinput> packages, can correctly compile PNG and JPG files into 3004 &DVI; or PDF, but is not able to handle EPS files. Conversely, the process of compiling 3005 with &latex; to &DVI; and converting to PS and eventually PDF does support EPS, but does 3006 not support PNG and JPG.</para> 3007 3008 <para>A lot of users want to create PDF documents, but also want to use the excellent 3009 <application>Pstricks</application> package to create &PostScript; graphics, or they want 3010 to use the &PostScript; output of mathematical and scientific software like 3011 <application>Mathematica</application>, <application>Maple</application> or <application>MuPAD</application>. 3012 These &latex; users have to compile first in &PostScript;, even if they want to create 3013 PDF documents, because these programs produce &PostScript; code which cannot be managed 3014 by &pdflatex;. However, it is not so hard as it may sound, because &kile; will help.</para> 3015 3016 </sect2> 3017 3018 <sect2 id="build_graphics_conversion"> 3019 3020 <title>Graphics Conversion</title> 3021 3022 <para>To overcome this frustrating loop, when you want to include both &PostScript; code and PNG or JPG files, 3023 you have a number of workarounds:</para> 3024 3025 <itemizedlist> 3026 <listitem><para>If you need a file in PS format, but have JPG or PNG graphics, you can also 3027 simply use &pdflatex; with &DVI; output first, and then run <application>dvips</application> 3028 to create the PS file. You see that &pdflatex; is a very good choice, if your source contains 3029 no &PostScript; code at all.</para></listitem> 3030 3031 <listitem><para>You can convert EPS files to PNG or other formats with utilities as the 3032 <ulink url="http://www.gimp.org/"><application>Gimp</application></ulink> or 3033 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink> 3034 and use &pdflatex;.</para></listitem> 3035 3036 <listitem><para><anchor id="build_graphics_epstopdf"></anchor>A preferred way 3037 is to convert EPS graphics to PDF graphics with 3038 <command>epstopdf</command>, which comes with every &tex; distribution 3039 and then use &pdflatex;. It produces high quality graphics, 3040 and you can even control the result with some of the following options: 3041 3042<programlisting> 3043 -dAutoFilterColorImages=false 3044 -dAutoFilterGrayImages=false 3045 -sColorImageFilter=FlateEncode 3046 -sGrayImageFilter=FlateEncode 3047 -dPDFSETTINGS=/prepress 3048 -dUseFlateCompression=true 3049</programlisting> 3050 </para> 3051 3052 <para>Even better: if your system allows <userinput>shell-escape</userinput>, conversion 3053 can be done on the fly. All you have to do is to include the <application>epstopdf</application> package, 3054 which is part of all &tex; distributions, with the command <userinput>\usepackage{epstopdf}</userinput>. 3055 Assuming that your code is: 3056 3057<programlisting> 3058 \includegraphics[width=5cm]{test.eps} 3059</programlisting> 3060 3061 When you call &pdflatex; with option <option>--shell-escape</option>, 3062 graphics <filename>test.eps</filename> is automatically converted into <filename>test.pdf</filename>.</para> 3063 3064 <para>This conversion will take place each time you run &pdflatex;. 3065 If your graphics command is given implicitly: 3066 3067<programlisting> 3068 \includegraphics[width=5cm]{test} 3069</programlisting> 3070 3071 <application>epstopdf</application> checks whether <filename>test.pdf</filename> is already 3072 available, so that the conversion step can be skipped.</para></listitem> 3073 3074 <listitem><para>You can convert the other way around, and use &latex; and PS-PDF conversion. 3075 This is not always a good idea, since EPS encapsulation of JPG or PNG can yield larger 3076 files, that in turn yield unnecessarily large documents. This is however <emphasis>highly</emphasis> 3077 dependent on the graphic utility that you use, since EPS can encapsulate other graphics, 3078 but not all applications support this perfectly. Some might actually try to build your JPG image 3079 with vectors and various scripting, which will result in gigantic files. Conversion of 3080 all graphics formats to EPS can be done by 3081 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>. 3082 Another simple program that does this process correctly is 3083 <ulink url="http://www.tex.uniyar.ac.ru/win32/tools/jpg2ps/"><application>jpg2ps</application></ulink>. 3084 </para></listitem> 3085 3086 <listitem><para>You can also use an automatic conversion. All graphics files are 3087 converted on the fly to EPS, and inserted into the PS document. This is a comfortable 3088 way, but you have to set up your system properly. This is discussed in the section 3089 <link linkend="build_epsgraphics">EPS Graphics</link>.</para></listitem> 3090 3091 </itemizedlist> 3092 3093 </sect2> 3094 3095 <sect2 id="build_graphics_type"> 3096 3097 <title>Use the right File for the right Graphic</title> 3098 3099 <itemizedlist> 3100 <listitem><para>EPS is sort of a graphic vector scripting language, describing 3101 all the lines and dots the graphic is made of; it looks good even when magnified beyond its 3102 default size, and suits best diagrams and vectorial graphics natively produced in EPS, 3103 which look very clear and sharp while maintaining a very small byte size.</para></listitem> 3104 <listitem><para>PNG (or the deprecated &GIF;) is a <emphasis>non-lossy</emphasis> file format, 3105 with good compression and quality. It is very good for diagrams, scans of drawings, 3106 or anything whose sharpness you do want to retain. It is sometimes overkill 3107 when used for photos.</para></listitem> 3108 <listitem><para>JPG is a <emphasis>lossy</emphasis> format, that compresses files better than PNG 3109 at the price of some loss in the picture detail. This is usually irrelevant for photos, 3110 but may cause bad quality for diagrams, drawings, and may make some thin lines disappear outright; 3111 in those cases use EPS or PNG.</para></listitem> 3112 </itemizedlist> 3113 3114 <para>But always remember: garbage in, garbage out! No conversion will make a bad picture good.</para> 3115 3116 </sect2> 3117 3118 </sect1> 3119 3120 <sect1 id="build_epsgraphics"> 3121 3122 <title>EPS Graphics</title> 3123 3124 <para>EPS graphics files are the traditional way to insert graphics files into 3125 &latex; documents. As mailing lists are full with questions concerning 3126 EPS graphics, we will discuss some important aspects and 3127 demonstrate how &kile; supports them.</para> 3128 3129 <sect2 id="build_graphics_eps"> 3130 3131 <title>&latex; and EPS Graphics</title> 3132 3133 <para>If you decided to use the traditional &latex; to produce 3134 PS or PDF output, you will probably run into some problems 3135 with graphics. You have to use EPS graphics (Encapsulated &PostScript;); 3136 no JPEG or PNG files. This should be no problem, as there are a lot of 3137 <link linkend="build_graphics_conversion">converters</link> like 3138 <command>convert</command> from the excellent 3139 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink> 3140 package. But, it needs some time of course.</para> 3141 3142 <para>The EPS files are used by both &latex; and the &DVI;-PS converter:</para> 3143 3144 <itemizedlist> 3145 <listitem><para>&latex; scans the EPS file for the bounding-box 3146 line, which tells &latex; how much space to reserve for the 3147 graphics.</para></listitem> 3148 3149 <listitem><para>The &DVI;-PS converter then reads the EPS file and 3150 inserts the graphics in the PS file.</para></listitem> 3151 </itemizedlist> 3152 3153 <para>This has some implications:</para> 3154 3155 <itemizedlist> 3156 <listitem><para>&latex; never reads the EPS file if the bounding-box 3157 parameters are specified in the graphics insertion command.</para></listitem> 3158 3159 <listitem><para>Since &latex; cannot read non-ASCII files, 3160 it cannot read the bounding-box information from compressed or non-EPS 3161 graphics files.</para></listitem> 3162 3163 <listitem><para>The EPS graphics are not included in the &DVI; file. Since the 3164 EPS files must be present when the &DVI; file is converted to 3165 PS, the EPS files must accompany the &DVI; files whenever they are 3166 moved.</para></listitem> 3167 </itemizedlist> 3168 3169 <para>Now you can call &latex;, and a &DVI;-PS converter like <application>dvips</application> 3170 to create your &PostScript; document. If your goal is a PDF document, you should run 3171 <command>dvips</command> with option <option>-Ppdf</option> and then call 3172 <command>ps2pdf</command>. You will find a lot of documents describing this solution.</para> 3173 3174 </sect2> 3175 3176 <sect2 id="build_graphics_epskile"> 3177 3178 <title>The &PostScript; Way of &kile;</title> 3179 3180 <para>&kile; helps you to get the bounding-box information. If you have installed 3181 <ulink url="http://www.imagemagick.org/">&imagemagick;</ulink> 3182 package, &kile; will extract this information from the EPS file and insert it as an 3183 option. This is done automatically when you select the graphics file. 3184 There are two advantages to proceeding like this:</para> 3185 3186 <itemizedlist> 3187 <listitem><para>The information is already scanned in the dialog, and 3188 need not to be done by &latex; later on.</para></listitem> 3189 <listitem><para>Even more important is that the width and height of the picture 3190 can be calculated, when the resolution is known. This information will be shown 3191 near the top of the dialog, and may serve as a clue when you want to scale the 3192 graphics.</para></listitem> 3193 <listitem><para>&kile; can also support zipped or gzipped EPS files, 3194 which are much smaller than uncompressed EPS files. But, this feature can only be used 3195 with a special system setup and a change of your local graphics configuration, 3196 as it is described in the <link linkend="build_graphics_bitmap">Bitmap Graphics</link> 3197 section.</para></listitem> 3198 </itemizedlist> 3199 <!-- FIXME I don't understand the following sentence, tbraun 3200 <para> The <emphasis>&PostScript; Way of &kile;</emphasis> can be turned off or on in 3201 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 3202 <guimenuitem>LaTeX</guimenuitem><guilabel>General</guilabel></menuchoice>.</para> 3203 --> 3204 </sect2> 3205 3206 <sect2 id="build_graphics_bitmap"> 3207 3208 <title>The &PostScript; Way and Bitmap Graphics</title> 3209 3210 <para>If your system allows <userinput>shell-escape</userinput>, &kile; 3211 also supports an easy way to include bitmap graphics, if you set up your &tex; 3212 system properly. There is no need to convert JPEG or PNG graphics, 3213 this can be done automatically when the &DVI; file is converted to PS.</para> 3214 3215 <para>&latex; needs some information about the file suffixes. The package 3216 <userinput>graphicx</userinput> looks for a file <filename>graphics.cfg</filename>, 3217 which must be somewhere in your search path for &latex; documents. Search for 3218 entries like:</para> 3219 3220<programlisting> 3221 \DeclareGraphicsRule{.pz}{eps}{.bb}{}% 3222 \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}% 3223 \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}% 3224 \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}% 3225 \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{}% 3226</programlisting> 3227 3228 <para>and replace these lines with:</para> 3229 3230<programlisting> 3231 \DeclareGraphicsRule{.pz}{eps}{.bb}{}% 3232 \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}% 3233 \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}% 3234 \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}% 3235 % changed or new graphic rules 3236 \DeclareGraphicsRule{.eps.zip}{eps}{.eps.bb}{`unzip -p #1}% zipped EPS 3237 \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c #1}% gzipped EPS 3238 \DeclareGraphicsRule{.jpg}{eps}{}{`convert #1 eps:-}% JPEG 3239 \DeclareGraphicsRule{.gif}{eps}{.bb}{`convert #1 eps:-}% GIF 3240 \DeclareGraphicsRule{.png}{eps}{.bb}{`convert #1 eps:-}% PNG 3241 \DeclareGraphicsRule{.tif}{eps}{.bb}{`convert #1 eps:-}% TIFF 3242 \DeclareGraphicsRule{.pdf}{eps}{.bb}{`convert #1 eps:-}% PDF-graphics 3243</programlisting> 3244 3245 <para>You will find this file, for example in Debian, at 3246 <filename>/etc/texmf/latex/graphics.cfg</filename>. The best way to proceed is to copy this 3247 file to your local texpath and then change this copy. See your &tex; distribution manual 3248 to learn how to get a list of your &tex; folders.</para> 3249 3250 <para>With this configuration file you are able to insert bitmap graphics and 3251 zipped or gzipped EPS files in &latex;. The command for conversion 3252 is given by <command>dvips</command>. When you look 3253 at the conversion command you will see that no extra file is created. 3254 The result of the conversion process is directly piped into the PS file. 3255 The only thing &latex; must know is the size of the graphics, and 3256 therefore we need the bounding box, which is provided by &kile;.</para> 3257 3258 <para>Some say that this way is insecure; you have to decide on how to work. 3259 In any case, you need no bounding box, as &kile; will extract this information 3260 from all types of graphics.</para> 3261 3262 </sect2> 3263 3264 <sect2 id="build_graphics_pdflatex"> 3265 3266 <title>&pdflatex; and EPS Graphics</title> 3267 3268 <para>As already stated, &pdflatex; is not able to handle EPS graphic files, 3269 but converters like <link linkend="build_graphics_epstopdf">epstopdf</link> 3270 will help. The best way is to include package <filename>epstopdf</filename>, 3271 which must follow the <userinput>graphicx</userinput> package.</para> 3272 3273<programlisting> 3274 \usepackage[pdftex]{graphicx} 3275 \usepackage{epstopdf} 3276</programlisting> 3277 3278 <para>Now you can already include EPS graphics, if you run <command>pdflatex</command> 3279 with option <option>--shell-escape</option>, but we can make it even better 3280 and also handle zipped or gzipped EPS files. Again we have to change 3281 the graphics configuration file <filename>graphics.cfg</filename> as above. 3282 This time we search for:</para> 3283 3284<programlisting> 3285 % pdfTeX is running in pdf mode 3286 \ExecuteOptions{pdftex}% 3287</programlisting> 3288 3289 <para>and simply add some lines:</para> 3290 3291<programlisting> 3292 % pdfTeX is running in pdf mode 3293 \ExecuteOptions{pdftex}% 3294 \AtEndOfPackage{% 3295 \g@addto@macro\Gin@extensions{.eps.gz,.eps.zip}% 3296 \@namedef{Gin@rule@.eps.gz}#1{{pdf}{.pdf}{`gunzip -c #1 | epstopdf -f >\Gin@base.pdf}}% 3297 \@namedef{Gin@rule@.eps.zip}#1{{pdf}{.pdf}{`unzip -p #1 | epstopdf -f >\Gin@base.pdf}}% 3298 }% 3299</programlisting> 3300 3301 <para>With these lines, &pdflatex; is able to handle EPS files, 3302 and hopefully there should be no more issues concerning graphics.</para> 3303 3304 </sect2> 3305 3306 </sect1> 3307 3308 <sect1 id="build_master"> 3309 3310 <title>Master Document</title> 3311 3312 <para>Defining your document as a master allows you to work with separate files, 3313 which gives you a parent document (or Master document), and child documents that 3314 make up a complete work. After having defined your Master document, with the 3315 corresponding command in the <guimenu>Settings</guimenu> 3316 menu, all the commands of the <guimenu>Tools</guimenu> 3317 menu will apply only to this document, even when you are working on the child 3318 documents. You can even close the Master document.</para> 3319 </sect1> 3320 3321 <sect1 id="build_errorhandling"> 3322 3323 <title>Error Handling</title> 3324 3325 <para>After you have compiled something, &kile; takes a look at the error messages 3326 that were generated. If there are any errors or warnings, they will be briefly reported 3327 in the <guilabel>Log and Messages</guilabel> window. One can take a closer look at the 3328 messages by selecting <menuchoice><guimenu>Build</guimenu><guimenuitem>View Log File</guimenuitem></menuchoice>, 3329 or by using the keyboard shortcut <keycombo>&Alt;<keycap>0</keycap></keycombo>. 3330 The generated log is then displayed in the <guilabel>Log and Messages</guilabel> view; errors and warnings are highlighted.</para> 3331 3332 <screenshot> 3333 <screeninfo>Viewing the log</screeninfo> 3334 <mediaobject> 3335 <imageobject> 3336 <imagedata fileref="snap_compile_error.png" format="PNG" /> 3337 </imageobject> 3338 <textobject> 3339 <phrase>Viewing the log</phrase> 3340 </textobject> 3341 <caption><para>Viewing the log</para></caption> 3342 </mediaobject> 3343 </screenshot> 3344 3345 <para>You can easily jump from one message in the log file to another by using the 3346 <menuchoice><guimenu>Build</guimenu><guimenuitem>Next / Previous 3347 LaTeX Error / Warning</guimenuitem></menuchoice> menu items, or by using 3348 the corresponding toolbar buttons.</para> 3349 3350 <para>To jump to the line in the &latex; source where the error or warning occurred, 3351 click on the error or warning in the <guilabel>Log and Messages</guilabel> view. 3352 &kile; will take you automatically to the offending line.</para> 3353 3354 </sect1> 3355 3356 <sect1 id="build_watch"> 3357 3358 <title>The Watch File Mode</title> 3359 3360 <para>When you launch the <guibutton>Quickbuild</guibutton> command, a viewer of 3361 some sort will normally be called after the compilation. If you are not using an embedded 3362 viewer, a new window will be opened every time.</para> 3363 3364 <para>If you are adjusting the look of your document, you might launch 3365 <guibutton>Quickbuild</guibutton> very often, and have many viewer windows open on 3366 your desktop; to avoid this confusion, you can activate the <guibutton>Watch file</guibutton> 3367 mode, that will prevent <guibutton>Quickbuild</guibutton> from launching a viewer.</para> 3368 3369 <para>This mode is of course useless with the embedded viewers, as you have to close them 3370 anyway to get back to editing the document and recompiling.</para> 3371 3372 </sect1> 3373 3374</chapter> 3375 3376<chapter id="navigating"> 3377 3378 <title>Navigating the &latex; Source</title> 3379 3380 <sect1 id="navigating_struct"> 3381 3382 <title>Using the Structure View</title> 3383 3384 <para>The <guilabel>Structure</guilabel> view shows the hierarchy of the document 3385 being created in &kile;, and allows you to quickly navigate it, showing its segmentation. 3386 To navigate around your document, all you need to do is to left click on any label, chapter, 3387 section, subsection, etc., and you will be taken to the beginning of 3388 the corresponding area.</para> 3389 3390 <para>If you included a separate &latex; file in your source using 3391 the <userinput>\input</userinput> or <userinput>\include</userinput> tags, these files will 3392 be referred to in the <guilabel>Structure</guilabel> view; double-clicking on their names 3393 will make &kile; bring up the included file in the editor window.</para> 3394 3395 <para>The hierarchy tree also has a separate branch for labels used in the text.</para> 3396 3397<!-- <screenshot> 3398 <screeninfo>Using the Structure View</screeninfo> 3399 <mediaobject> 3400 <imageobject> 3401 <imagedata fileref="snap_structview_label.png" format="PNG" /> 3402 </imageobject> 3403 <textobject> 3404 <phrase>Using the Structure View</phrase> 3405 </textobject> 3406 <caption><para>Using the Structure View</para></caption> 3407 </mediaobject> 3408 </screenshot>--> 3409 3410 <sect2 id="navigating_contextmenu"> 3411 3412 <title>Using the Context Menu</title> 3413 3414 <para>Most of the entries in the structure view have a lot of entries in the context menu, 3415 which you can open with a right mouse click. So look at the structure view in the 3416 following picture.</para> 3417 3418 <screenshot> 3419 <screeninfo>Using the Structure View</screeninfo> 3420 <mediaobject> 3421 <imageobject> 3422 <imagedata fileref="structureview.png" format="PNG" /> 3423 </imageobject> 3424 <textobject> 3425 <phrase>Using the Structure View</phrase> 3426 </textobject> 3427 </mediaobject> 3428 </screenshot> 3429 3430 <para>You will find some labels, some sectioning entries, two figure environments and three 3431 pictures. If you right click on one of the sectioning entries, a menu with some useful 3432 commands will popup. All commands like <guibutton>Select</guibutton>, <guibutton>Delete</guibutton> 3433 or <guibutton>Comment</guibutton> will work with all lines, which belong to this section.</para> 3434 3435 <screenshot> 3436 <screeninfo>Context menu for sectioning entries</screeninfo> 3437 <mediaobject> 3438 <imageobject> 3439 <imagedata fileref="structureview-context1.png" format="PNG" /> 3440 </imageobject> 3441 <textobject> 3442 <phrase>Context menu for sectioning entries</phrase> 3443 </textobject> 3444 </mediaobject> 3445 </screenshot> 3446 3447 <para>Clicking on a figure or table entry will offer some actions with respect to references 3448 and a right click on a graphics entry will offer some programs to open the graphics.</para> 3449 3450 <screenshot> 3451 <screeninfo>Context menu for figure/tables and graphics entries</screeninfo> 3452 <mediaobject> 3453 <imageobject> 3454 <imagedata fileref="structureview-context2.png" format="PNG" /> 3455 </imageobject> 3456 <textobject> 3457 <phrase>Context menu for figure/tables and graphics entries</phrase> 3458 </textobject> 3459 </mediaobject> 3460 </screenshot> 3461 3462 </sect2> 3463 3464 <sect2 id="navigating_update"> 3465 3466 <title>Updating the Structure View</title> 3467 3468 <para>To update your structure view you can either go to 3469 <menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh 3470 Structure</guimenuitem></menuchoice>, hit <keycombo><keycap>F12</keycap></keycombo>, or you can save your document, 3471 which will make &kile; update its <guilabel>Structure</guilabel> view.</para> 3472 3473 </sect2> 3474 3475 </sect1> 3476 3477 <sect1 id="navigating_bookmarks"> 3478 3479 <title>Bookmarks</title> 3480 3481 <para>Bookmarks are your reference to a segment of text or a line inside the &kile; 3482 environment. To use a bookmark, select a specific line of your document 3483 you would like to return to, then press <keycombo>&Ctrl; 3484 <keycap>B</keycap></keycombo>, and &kile; will add a bookmark to this line. 3485 Alternatively, you can also set a bookmark by highlighting a line and choosing 3486 the menu labeled <menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Set 3487 Bookmark</guimenuitem></menuchoice>.</para> 3488 3489 <para>To remove all your bookmarks, select <menuchoice><guimenu>Bookmarks</guimenu> 3490 <guimenuitem>Clear All Bookmarks</guimenuitem></menuchoice>.</para> 3491 3492 </sect1> 3493 3494</chapter> 3495 3496<chapter id="projects"> 3497 3498 <title>Projects</title> 3499 3500 <sect1 id="projects_working"> 3501 3502 <title>Working with Projects</title> 3503 3504 <para>In &kile; you can create and work with <emphasis>projects</emphasis>. A project is a 3505 group of &latex;, graphic, &bibtex;, or other files that contain all the information that is used to build 3506 your complete document. A typical project would be a document consisting of several chapters, 3507 written in different <literal role="extension">.tex</literal> files; all of them could be included in 3508 a project, to make the whole document easier to manage. The specifications of the project are stored in a special file, 3509 with extension <literal role="extension">.kilepr</literal>.</para> 3510 3511 <para>A Project adds the following functionalities:</para> 3512 3513 <itemizedlist> 3514 <listitem><para>You need not set a master document, &kile; does this automatically.</para></listitem> 3515 <listitem><para>Project files can easily be archived together by going to <menuchoice><guimenu>Project</guimenu><guimenuitem>Archive</guimenuitem></menuchoice></para></listitem> 3516 <listitem><para>The <guilabel>Files and Projects</guilabel> view shows which files are included 3517 in the project.</para></listitem> 3518 <listitem><para>After opening a project, any file that was previously opened will be 3519 restored with the original encoding and highlighting.</para></listitem> 3520 <listitem><para> Code completion works across all project files.</para></listitem> 3521 <listitem><para> Reference completion works across all project files.</para></listitem> 3522 <listitem><para> Citation completion works across all project files.</para></listitem> 3523 <listitem><para> Search in all project files.</para></listitem> 3524 <listitem><para> Specify custom quickbuild and &makeidx; command.</para></listitem> 3525 </itemizedlist> 3526 3527 <para>You can find all project related commands in the <guilabel>Project</guilabel>-menu. From there you can open, close and manage your projects.</para> 3528 3529 </sect1> 3530 3531 <sect1 id="projects_creating"> 3532 3533 <title>Creating a Project</title> 3534 3535 <para>To create a project, select <menuchoice><guimenu>Project</guimenu> 3536 <guimenuitem>New Project...</guimenuitem></menuchoice>.</para> 3537 <screenshot> 3538 <screeninfo>Project creation window</screeninfo> 3539 <mediaobject> 3540 <imageobject> 3541 <imagedata fileref="project-creation.png" format="PNG" /> 3542 </imageobject> 3543 <textobject> 3544 <phrase>Project creation window</phrase> 3545 </textobject> 3546 </mediaobject> 3547 </screenshot> 3548 <para>You will be 3549 asked to give the following information to create your project:</para> 3550 <itemizedlist> 3551 <listitem> 3552 <para> 3553 Title of your project (<guilabel>Project title</guilabel> text field). 3554 </para> 3555 <para> 3556 The title of the project will be used to create a name of the project file by transforming to lowercase and adding <filename role="extension">.kilepr</filename> extension. 3557 </para> 3558 </listitem> 3559 <listitem> 3560 <para> 3561 A folder where the project file will be stored (<guilabel>Project folder</guilabel> text field). 3562 </para> 3563 </listitem> 3564 <listitem> 3565 <para> 3566 If you want to create a new main file of the project check the <guilabel>Create a new file and add it to this project</guilabel> item. 3567 </para> 3568 </listitem> 3569 <listitem> 3570 <para> 3571 When you fill out the <guilabel>Filename</guilabel> box, you have to include a relative path from where the <filename role="extension">.kilepr</filename> project file is stored (see the <guilabel>Project folder</guilabel> item). 3572 </para> 3573 </listitem> 3574 <listitem> 3575 <para> 3576 Type of the created file, <guilabel>Empty File</guilabel>, <guilabel>Article</guilabel>, <guilabel>Book</guilabel>, <guilabel>Letter</guilabel>, <guilabel>Report</guilabel>, &etc; can be chosen from a visual list at the bottom of the <guilabel>File</guilabel> panel. 3577 </para> 3578 </listitem> 3579 <listitem> 3580 <para> 3581 Extensions for the default files in the project can be selected using the <guilabel>Extensions</guilabel> panel. Your choice will be used to define the files that should be opened when you choose <menuchoice><guimenu>Project</guimenu><guimenuitem>Open All Project Files</guimenuitem></menuchoice> menu item and in the &kile; wizards. The extensions in the text field should be separated with spaces. 3582 </para> 3583 </listitem> 3584 </itemizedlist> 3585 </sect1> 3586 3587 <sect1 id="projects_view"> 3588 3589 <title>The Files and Projects View</title> 3590 3591 <para>The <guilabel>Files and Projects</guilabel> view is a button of the sidebar menu. 3592 From this view, you can see the structure of your project, its files, 3593 and the name of the <literal role="extension">.kilepr</literal> file that stores the project information. 3594 Adding, removing, or changing options in your project is done via 3595 the <guilabel>Files and Projects</guilabel> view.</para> 3596 3597 <screenshot> 3598 <screeninfo>The Files and Projects View</screeninfo> 3599 <mediaobject> 3600 <imageobject> 3601 <imagedata fileref="snap_projectview.png" format="PNG" /> 3602 </imageobject> 3603 <textobject> 3604 <phrase>The Files and Projects View</phrase> 3605 </textobject> 3606 <caption><para>The Files and Projects View</para></caption> 3607 </mediaobject> 3608 </screenshot> 3609 3610 </sect1> 3611 3612 <sect1 id="projects_adding"> 3613 3614 <title>Adding and Removing Files</title> 3615 3616 <para>To add a file to your project, open any &tex; file, right click on its name in the 3617 <guilabel>Files and Projects</guilabel> view, and select <guilabel>Add to 3618 Project</guilabel>. If you have opened multiple projects, a dialog box will pop up in which 3619 you can specify to which project the file should be added.</para> 3620 <!-- duplicated see next para 3621 <para>If you have multiple files to be added to a project, you can select the 3622 project from the <guilabel>Files and Projects</guilabel> view and right-click then select 3623 <guilabel>Add Files...</guilabel>; you will then be able to select your files in a dialog box.</para> 3624 --> 3625 <para>You can also right-click on the project's name in the <guilabel>Files and 3626 Projects</guilabel> view, and select <guilabel>Add Files...</guilabel> to bring 3627 up a file selection dialog.</para> 3628 3629 <screenshot> 3630 <screeninfo>Adding a file to a project</screeninfo> 3631 <mediaobject> 3632 <imageobject> 3633 <imagedata fileref="snap_projectview_add.png" format="PNG" /> 3634 </imageobject> 3635 <textobject> 3636 <phrase>Adding a file to a project</phrase> 3637 </textobject> 3638 <caption><para>Adding a file to a project</para></caption> 3639 </mediaobject> 3640 </screenshot> 3641 3642 <para>To remove a file from a project, right-click on it and select <guilabel>Remove File</guilabel>. 3643 This does <emphasis>not</emphasis> delete your file (and also does not close it), but only removes it from the list 3644 of files contained in the <literal role="extension">.kilepr</literal> extension.</para> 3645 3646 <sect2 id="projects_archive"> 3647 3648 <title>Archiving your Project</title> 3649 3650 <para>&kile; allows you to easily backup your project by storing all its files 3651 into a single archive (often known as a <emphasis>tarball</emphasis>). To archive your project, 3652 right-click on its name in the <guilabel>Files and Projects</guilabel> view, or select 3653 <menuchoice><guimenu>Project</guimenu><guimenuitem>Archive</guimenuitem></menuchoice>.</para> 3654 3655 <para>By default, all files in a project are added to the archive. If you do not want to include 3656 a certain file in the archive, right-click on it in the <guilabel>Files and Projects</guilabel> 3657 view, and uncheck the <guilabel>Include in Archive</guilabel> option.</para> 3658 3659 <para>The archive operation is currently realized by executing the <command>tar</command> from the project 3660 folder (where the <literal role="extension">.kilepr</literal> file is located).</para> 3661 3662 </sect2> 3663 3664 </sect1> 3665 3666 <sect1 id="projects_options"> 3667 3668 <title>Project Options</title> 3669 3670 <para>&kile; has a few options related to your project that can be set. To change them, 3671 right-click on the title of your project and select <guilabel>Project Options</guilabel>, 3672 and you will have the option of changing:</para> 3673 3674 <itemizedlist> 3675 <listitem><para>The title of your project.</para></listitem> 3676 <listitem><para>Default file extensions.</para></listitem> 3677 <listitem><para>The Master document.</para></listitem> 3678 <listitem><para>The Quickbuild command.</para></listitem> 3679 <listitem><para>The &makeidx; options.</para></listitem> 3680 </itemizedlist> 3681 3682 3683<!-- FIXME not working in kile, tbraun 11/3/2007 3684 <sect2 id="projects_ext"> 3685 3686 <title>Extensions for Non-Source Files</title> 3687 3688 <para>Non-source files are files such as pictures, PDF or &PostScript; files, etc. that are 3689 to be included in the project, but are not source files with the extension <literal role="extension">.tex</literal>. You have 3690 the option to use your own regular expressions to match non-source files.</para> 3691 </sect2> 3692--> 3693 3694 </sect1> 3695 3696 <sect1 id="projects_closing"> 3697 3698 <title>Closing a Project</title> 3699 3700 <para>To close a project, select the <guilabel>Files and Projects</guilabel> view from 3701 the vertical toolbar, right click on your project title, and then select <guimenuitem> 3702 Close</guimenuitem>. This will close your project, all the files associated with your project, 3703 and will also add the name of the project you just closed to <guisubmenu>Open Recent 3704 Project...</guisubmenu> in the <guimenu>Project</guimenu> menu.</para> 3705 3706 </sect1> 3707 3708</chapter> 3709 3710<chapter id="lang"> 3711 3712 <title>Document Encoding</title> 3713 3714 <para>The &kile; editor allows you to read, convert and save text in the character encoding 3715 your document needs. With this it is possible, for example, to use accented characters, such 3716 as are commonly used in Italian or French, directly in &latex; documents. 3717 Selecting the encoding for your document can be done in two ways:</para> 3718 3719 <itemizedlist> 3720 <listitem><para>One way to set the document encoding is by using the submenu 3721 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure 3722 Kile...</guisubmenu><guimenuitem>Editor</guimenuitem></menuchoice>, 3723 where you can set the default character encoding for all files.</para> 3724 <screenshot> 3725 <screeninfo>Set the default character encoding</screeninfo> 3726 <mediaobject> 3727 <imageobject> 3728 <imagedata fileref="config-encoding.png" format="PNG" /> 3729 </imageobject> 3730 <textobject> 3731 <phrase>Set the default character encoding</phrase> 3732 </textobject> 3733 </mediaobject> 3734 </screenshot> 3735 </listitem> 3736 <listitem><para>A second way to set the encoding for a document is to choose the desired encoding 3737 within the wizard to create a new document.</para></listitem> 3738 </itemizedlist> 3739 3740 <para>&latex; itself only understands ASCII, which represents a very limited set of characters. Hence, it is not possible to use 3741 accented characters directly. To use them nevertheless, a special syntax was invented: 3742 such as for example <userinput>\"e</userinput> for <computeroutput>ë</computeroutput>. 3743 The <application>inputenc</application> package is available to help you with this. It is included 3744 in the preamble using <userinput>\usepackage[latin1]{inputenc}</userinput>, where the optional argument 3745 specifies the encoding you would like to use (nowadays in most cases <userinput>utf8</userinput>). This tells &latex; 3746 to translate all of the <userinput>ë</userinput>'s you wrote to <userinput>\"e</userinput>'s before 3747 compiling. Please refer to the <application>inputenc</application> documentation directly for more 3748 information. Last but not least: remember to make sure that your file is <emphasis>actually</emphasis> saved 3749 in the same encoding you specified for the <application>inputenc</application> package!</para> 3750 3751 <para>This multitude of different character coding tables has created numerous problems: for example, 3752 you cannot write a course of Turkish in French without losing one language's special characters. 3753 There is general agreement that, sooner or later, 3754 everybody will switch to <ulink url="http://www.unicode.org">Unicode</ulink>. There 3755 are many implementations of Unicode, and <abbrev>UTF-8</abbrev> is the most 3756 successful in &Linux;; &Windows;® relies instead on the more cumbersome and 3757 less flexible <abbrev>UCS-2</abbrev>. Most distributions have already 3758 begun setting their default encoding to <abbrev>UTF-8</abbrev>, and therefore you 3759 may be very interested in using the <userinput>utf8</userinput> argument to the 3760 <userinput>inputenc</userinput> package.</para> 3761 3762 <sect1 id="ucs"> 3763 3764 <title>The &ucs; Package</title> 3765 <para>If you don't have the &ucs; package installed, you can proceed as follows:</para> 3766 <itemizedlist> 3767 <listitem><para>Get the &ucs; package from 3768 <ulink url="http://www.ctan.org/tex-archive/macros/latex/contrib/unicode/">CTAN</ulink>. 3769 </para></listitem> 3770 <listitem> 3771 <para>To install it, unpack the downloaded file and place it in a folder listed 3772 in your $<envar>TEXINPUTS</envar> environment variable. This can also be set inside &kile;.</para> 3773 </listitem> 3774 </itemizedlist> 3775 3776<programlisting>\usepackage{ucs} 3777\usepackage[utf8]{inputenc}</programlisting> 3778 3779 </sect1> 3780 3781 <sect1 id="xelatex"> 3782 3783 <title>XeLaTeX</title> 3784 3785 <para>If you are using <userinput>XeLaTeX</userinput>, you can simply load the 3786 <userinput>xltxtra</userinput> package. It will additionally load all the required packages.</para> 3787 <programlisting>\usepackage{xltxtra}</programlisting> 3788 3789 </sect1> 3790 3791 <sect1 id="cjk"> 3792 3793 <title>&cjk; Support</title> 3794 3795 <para>Adding support for ideographic languages is quite tricky. However, once 3796 you are done with it, it will work quite well. Other than installing packages, 3797 there is some extra configuration work to do.</para> 3798 3799 <tip><para>Your &Linux; distribution might already have a &cjk; (Chinese, Japanese, 3800 Korean) package ready for you, so you might be saved the hassle of manually 3801 installing everything. Do check before going forward!</para></tip> 3802 3803 <para>There is the possibility of using the &ucs; package in order to write 3804 short snippets of &cjk; text, but that option is seriously limited as it does 3805 not handle, among other things, newlines. Instead, we will install the complete 3806 &cjk;-&latex; package and make it work for both &latex; and &pdflatex;. A lot 3807 of this material has been inspired by <ulink url="http://www.ece.uci.edu/~chou/">Pai 3808 H. Chou</ulink>'s <ulink url="http://www.ece.uci.edu/~chou/unicode-tex.html">page 3809 about how to setup &pdflatex;</ulink>.</para> 3810 3811 <orderedlist> 3812 3813 <listitem><para>Download the <ulink 3814 url="http://www.ctan.org/tex-archive/help/Catalogue/entries/cjk.html">&cjk;</ulink> 3815 package. Copy its unpacked files to an appropriate subfolder of 3816 $<envar>TEXMF</envar>, just as you did with the &ucs; package 3817 before (see <xref linkend="ucs" role="select: title pageabbrv"/>). The files will be unpacked in a 3818 <filename>CJK/X_Y.Z</filename> folder; it is not important that you 3819 take them out, though it will probably be tidier and easier for you to 3820 maintain.</para></listitem> 3821 3822 <listitem><para>Now you have to download a font that supports all the &cjk; characters 3823 you need. You can choose any <literal role="extension">*.ttf</literal> file that 3824 covers them, but in this walkthrough we will use <ulink 3825 url="ftp://ftp.wu-wien.ac.at/pub/www/Netscape/communicator/extras/fonts/windows/Cyberbit.ZIP">Cyberbit</ulink>. 3826 Unzip the file and rename <filename>Cyberbit.ttf</filename> to 3827 <filename>cyberbit.ttf</filename>, since uppercase might confuse your system.</para> 3828 <para>Place <filename>cyberbit.ttf</filename> in a folder together with 3829 <ulink url="http://delloye.free.fr/Unicode.sfd"><filename>Unicode.sfd</filename></ulink>, 3830 and generate the <literal role="extension">*.tfm</literal> and 3831 <literal role="extension">*.enc</literal> files with the command 3832 <userinput><command>$ ttf2tfm cyberbit.ttf -w cyberbit@Unicode@</command></userinput>. 3833 For some reason, sometimes this does not produce the hundreds 3834 of files it should. Should that happen in your case, you can download both 3835 <ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-tfm.tgz"><literal 3836 role="extension">*.tfm</literal></ulink> and 3837 <ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-enc.tgz"><literal 3838 role="extension">*.enc</literal></ulink> files.</para> 3839 <para>Place the <literal role="extension">*.tfm</literal> files in an 3840 appropriate folder, say <filename>$<envar>TEXMF</envar>/fonts/tfm/bitstream/cyberbit/</filename>; 3841 the <literal role="extension">*.enc</literal> files may be installed in 3842 <filename>$<envar>TEXMF</envar>/pdftex/enc/cyberbit/</filename>.</para></listitem> 3843 3844 <listitem><para>Now we need a map file to connect the <literal 3845 role="extension">*.enc</literal> files to the font. Download <ulink 3846 url="http://delloye.free.fr/cyberbit.map"><filename>cyberbit.map</filename></ulink> 3847 and install it in <filename>$<envar>TEXMF</envar>/pdftex/config/</filename>.</para></listitem> 3848 3849 <listitem><para>Download another file, <ulink 3850 url="http://delloye.free.fr/c70cyberbit.fd"><filename>c70cyberbit.fd</filename></ulink>, 3851 and place it in an appropriate folder. You may choose, for example, 3852 <filename>$<envar>TEXMF</envar>/tex/misc/</filename>.</para></listitem> 3853 3854 <listitem><para>The last file we have to generate is a &PostScript; Type 1 3855 font, necessary to read &DVI; files generated with &latex;. Run the command 3856 <userinput><command>$ ttf2pfb cyberbit.ttf -o cyberbit.pfb</command></userinput>, and copy the 3857 resulting <filename>cyberbit.pfb</filename> to a folder such as 3858 <filename>$<envar>TEXMF</envar>/fonts/type1/cyberbit/</filename>.</para></listitem> 3859 3860 <listitem><para>Let's now place <filename>cyberbit.ttf</filename> among the fonts 3861 where &latex; can find it. You could place it in a folder named 3862 <filename>$<envar>TEXMF</envar>/fonts/truetype/</filename>.</para></listitem> 3863 3864 <listitem><para>Check the configuration file you find at 3865 <filename>$<envar>TEXMF</envar>/web2c/texmf.cnf</filename>, and make sure that the 3866 line mentioning <envar>TTFONTS</envar> is uncommented and points to 3867 the folder where you saved <filename>cyberbit.ttf</filename>.</para></listitem> 3868 3869 <listitem><para>To make it possible for &pdflatex; to use your &cjk; 3870 fonts, it is necessary that you add a line in the configuration file 3871 <filename>$<envar>TEXMF</envar>/pdftex/config/pdftex.cfg</filename>. Add 3872 <userinput>map +cyberbit.map</userinput> in the file to complete the 3873 configuration for &pdflatex;.</para></listitem> 3874 3875 <listitem><para>To configure &latex; so that you can produce &DVI; 3876 files with &cjk; characters, you have to add a line in file 3877 <filename>ttfonts.map</filename>. The file might be in a folder named 3878 <filename>$<envar>TEXMF</envar>/ttf2pk/</filename>, but you will probably have to look 3879 for it. Append the line <userinput>cyberbit@Unicode@ cyberbit.ttf</userinput> 3880 to it.</para></listitem> 3881 3882 <listitem><para>Now, you only have to run <userinput><command>texhash</command></userinput> 3883 and the system should be ready.</para></listitem> 3884 3885 </orderedlist> 3886 3887 <para>To test whether your configuration is correct, you can try to compile 3888 <ulink url="http://www.math.nus.edu.sg/aslaksen/cs/sample-utf8.tex">this test 3889 file</ulink>.</para> 3890 3891 <sect2> 3892 <title>&cjk; Troubleshooting</title> 3893 3894 <para>There are many things that can go wrong when adding &cjk; 3895 support manually. If something seems not to work, the following 3896 checklist might help you.</para> 3897 3898 <itemizedlist> 3899 3900 <listitem><para>Obviously, since you run &latex; as a user and 3901 not as root, you must <emphasis>allow</emphasis> ordinary users 3902 to access the new files. Make sure all folders and files are 3903 accessible using the <command>chmod</command> command.</para></listitem> 3904 3905 <listitem><para>If &latex; writes a &DVI; without problems, but you 3906 cannot view it, it is almost certainly because of some problems in the 3907 automatic generation of <literal role="extension">*.pk</literal> 3908 fonts. They are supposed to be generated on the fly when viewing a 3909 &DVI; file, but this might fail for a number of reasons: double-check 3910 <filename>ttfonts.map</filename> for your custom line first. However, 3911 it might happen that your <command>ttf2pk</command> command, which 3912 is usually invoked by the &DVI; viewer, has been compiled 3913 <emphasis>without</emphasis> support for the 3914 <application>kpathsea</application> libraries. If this is the case, 3915 <userinput><command>ttf2pk</command> <option>--version</option></userinput> 3916 will make no mention of <application>kpathsea</application>. As support for 3917 these libraries is necessary, you might have to find a new package, or 3918 recompile <application>FreeType 1</application> yourself.</para></listitem> 3919 3920 </itemizedlist> 3921 3922 </sect2> 3923 3924 3925 <sect2> 3926 3927 <title>How do I input &cjk; in Unicode?</title> 3928 3929 <para>There are a number of different input engines, and the choice can 3930 depend also on personal preference. The author uses <ulink 3931 url="http://www.scim-im.org/projects/skim"><application>Skim</application></ulink>, 3932 a port to &kde; of the <ulink 3933 url="http://www.scim-im.org"><application>Scim</application></ulink> 3934 engine. Refer to your distribution's documentation to learn how to 3935 install these programs. Configuration of such programs can be tricky 3936 too, in the case of <application>Skim</application> you will have to 3937 define an environment variable <userinput><envar>XMODIFIERS</envar>="@im=SCIM"</userinput> 3938 <emphasis>before</emphasis> starting <application>X</application>.</para> 3939 3940 </sect2> 3941 3942 </sect1> 3943 3944</chapter> 3945 3946&include-section-scripting; 3947 3948<chapter id="help"> 3949 3950 <title>Help</title> 3951 3952 <sect1 id="help_documents"> 3953 3954 <title>Help Documents</title> 3955 3956 <para>&latex; is a rather sophisticated system, where basic features 3957 can be expanded by a great variety of additional packages. 3958 &kile; provides numerous different ways to aid the user.</para> 3959 3960 <variablelist> 3961 3962 <varlistentry> 3963 <term><guimenu>LaTeX Reference</guimenu></term> 3964 <listitem><para>An alphabetical index of the most 3965 common &latex; commands.</para></listitem> 3966 </varlistentry> 3967 3968 <varlistentry> 3969 <term><guimenu>TeX Documentation</guimenu></term> 3970 <listitem><para>&tetex;/&texlive; ships with a huge number of help documents. 3971 This includes documentation for all the included packages and an additional &latex; 3972 reference.</para></listitem> 3973 </varlistentry> 3974 3975 <varlistentry> 3976 <term><guimenu>LaTeX</guimenu></term> 3977 <listitem><para>A full reference for &tex; and friends. This is not 3978 only a description of all programs, but some important packages are also 3979 mentioned. It also includes a full reference manual of &latex; 3980 commands—ideal for looking up a particular piece of formatting 3981 while writing a document. As this document is really extensive, 3982 it is referenced in &kile; by three bookmarks.</para></listitem> 3983 </varlistentry> 3984 3985 <varlistentry> 3986 <term><guimenu>LaTeX Command</guimenu></term> 3987 <listitem><para>Another alphabetical index of the most common 3988 &latex; commands.</para></listitem> 3989 </varlistentry> 3990 3991 <varlistentry> 3992 <term><guimenu>LaTeX Subject</guimenu></term> 3993 <listitem><para>A description of important &latex; 3994 subjects.</para></listitem> 3995 </varlistentry> 3996 3997 <varlistentry> 3998 <term><guimenu>LaTeX Env</guimenu></term> 3999 <listitem><para>An alphabetical index of the most common 4000 &latex; environments.</para></listitem> 4001 </varlistentry> 4002 4003 </variablelist> 4004 4005 </sect1> 4006 4007 <sect1 id="help_contextsentitive"> 4008 4009 <title>Context Sensitive Help</title> 4010 4011 <para>&kile; also supports a context sensitive help, which is called 4012 with <keycombo action="simul">&Ctrl;&Alt;<keycap>H</keycap></keycombo>,<keycap>K</keycap>. 4013 In <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 4014 <guimenuitem>Kile</guimenuitem><guilabel>Help</guilabel></menuchoice> 4015 you can choose whether you want to use &kile;'s &latex; reference or the 4016 help system of &tetex;/&texlive;, which is the default setting.</para> 4017 4018 <screenshot> 4019 <screeninfo>Bullets</screeninfo> 4020 <mediaobject> 4021 <imageobject> 4022 <imagedata fileref="config-userhelp.png" format="PNG" /> 4023 </imageobject> 4024 <textobject> 4025 <phrase>Bullets</phrase> 4026 </textobject> 4027 </mediaobject> 4028 </screenshot> 4029 4030 </sect1> 4031 4032 <sect1 id="help_search"> 4033 4034 <title>Searching for Keywords</title> 4035 4036 <para>It is not always easy to find the right document as &tetex;/&texlive; 4037 ships with a huge number of help documents. In order to facilitate this process, &tetex;/&texlive; 4038 provides a tiny program called <application>texdoctk</application>. 4039 It provides a database of all the help documents, for which &kile; offers a user-friendly 4040 interface.</para> 4041 4042 <screenshot> 4043 <screeninfo>Bullets</screeninfo> 4044 <mediaobject> 4045 <imageobject> 4046 <imagedata fileref="dialog-docbrowser1.png" format="PNG" /> 4047 </imageobject> 4048 <textobject> 4049 <phrase>Bullets</phrase> 4050 </textobject> 4051 </mediaobject> 4052 </screenshot> 4053 4054 <para>All the documents are grouped into categories. Additionally, 4055 one can search for package names or keywords. 4056 &kile; will then show only the help documents matching the search string.</para> 4057 4058 <screenshot> 4059 <screeninfo>Bullets</screeninfo> 4060 <mediaobject> 4061 <imageobject> 4062 <imagedata fileref="dialog-docbrowser2.png" format="PNG" /> 4063 </imageobject> 4064 <textobject> 4065 <phrase>Bullets</phrase> 4066 </textobject> 4067 </mediaobject> 4068 </screenshot> 4069 4070 <para>A mouse double-click or the <keycap>Space</keycap> key will start a 4071 viewer for the selected document. This can be an arbitrary document, not only a 4072 &DVI;, PS, PDF or &HTML; document. &kile; takes the &kde; settings into account in order to 4073 start an appropriate viewer.</para> 4074 4075 4076 </sect1> 4077 4078 <sect1 id="help_userdefined"> 4079 4080 <title>User Defined Help</title> 4081 4082 <para>Besides this static &tetex;/&texlive; documentation, &kile; also supports 4083 a more flexible variable way for help documents. In the <guimenu>Help</guimenu> 4084 menu &kile; has a special <guimenu>User help</guimenu> 4085 submenu, where the user can add documents of his or her own choice. 4086 These can be the most important documents of the &tetex;/&texlive; documentation, or even 4087 self-written documents. It is also possible to enter URLs.</para> 4088 4089 <para>Go to 4090 <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu> 4091 <guimenuitem>Kile</guimenuitem><guilabel>Help</guilabel></menuchoice> 4092 and choose the <guibutton>Configure</guibutton> button 4093 to configure this <guimenu>User help</guimenu> menu. You can add, 4094 remove or move menu entries around, and insert separators to optimize 4095 the structure of the menu.</para> 4096 4097 <screenshot> 4098 <screeninfo>Dialog: configure user defined help entries</screeninfo> 4099 <mediaobject> 4100 <imageobject> 4101 <imagedata fileref="dialog-userhelp.png" format="PNG" /> 4102 </imageobject> 4103 <textobject> 4104 <phrase>Dialog: configure user defined help entries</phrase> 4105 </textobject> 4106 </mediaobject> 4107 </screenshot> 4108 4109 <para>Pressing the <guibutton>Add</guibutton> button will open 4110 another dialog, where you can edit the name of the menu entry, 4111 and choose the corresponding file or &URL;. The second button to the right of the text field launches 4112 &konqueror;, which can be used to determine the correct &URL;.</para> 4113 4114 <screenshot> 4115 <screeninfo>Dialog: add a new helpentry</screeninfo> 4116 <mediaobject> 4117 <imageobject> 4118 <imagedata fileref="dialog-addhelp.png" format="PNG" /> 4119 </imageobject> 4120 <textobject> 4121 <phrase>Dialog: add a new helpentry</phrase> 4122 </textobject> 4123 </mediaobject> 4124 </screenshot> 4125 4126 <para>After finishing the configuration, all the entries will appear in the <guimenu>Help</guimenu> 4127 menu of &kile; as a special menu entry <guimenu>User help</guimenu>.</para> 4128 4129 <screenshot> 4130 <screeninfo>Userhelp menu</screeninfo> 4131 <mediaobject> 4132 <imageobject> 4133 <imagedata fileref="menu-userhelp.png" format="PNG" /> 4134 </imageobject> 4135 <textobject> 4136 <phrase>Userhelp menu</phrase> 4137 </textobject> 4138 </mediaobject> 4139 </screenshot> 4140 4141 </sect1> 4142 4143</chapter> 4144 4145<chapter id="credits"> 4146 4147 <title>Credits and License</title> 4148 4149 <para>&kile; is an open-source user-friendly &latex; / &tex; source code editor. It runs on systems 4150 that have the &kde; Desktop Environment installed. &kde; is available for several architectures 4151 including &Linux; and other Unix-like systems.</para> 4152 4153 <para>Many thanks are owed to the people who strive to continue the &kile; project and to those 4154 who sacrifice numerous hours of their time to develop tools we can all use under the &GNU; license. 4155 Up-to-date information about contributors can be found in 4156 the <guimenuitem>About &kile;</guimenuitem> dialog from the <guimenu>Help</guimenu> menu. 4157 </para> 4158 4159 <para>Many thanks to all those involved!</para> 4160 4161<!-- TRANS:CREDIT_FOR_TRANSLATORS --> 4162 4163 &underFDL; <!-- FDL: do not remove --> 4164 &underGPL; <!-- GPL License --> 4165 4166</chapter> 4167 4168 4169&documentation.index; 4170 4171</book> 4172 4173<!-- 4174Local Variables: 4175mode: xml 4176sgml-minimize-attributes:nil 4177sgml-general-insert-case:lower 4178sgml-indent-step:0 4179sgml-indent-data:nil 4180End: 4181 4182vim:tabstop=2:shiftwidth=2:expandtab 4183--> 4184
