<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kile "<application>Kile</application>">
  <!ENTITY latex "L<superscript>A</superscript>T<subscript>E</subscript>X">
  <!ENTITY tex "T<subscript>E</subscript>X">
  <!ENTITY tetex "<application>teT<subscript>E</subscript>X</application>">
  <!ENTITY bibtex "BibT<subscript>E</subscript>X">
  <!ENTITY gnuplot "<application>GnuPlot</application>">
  <!ENTITY kde "<acronym>KDE</acronym>">
  <!ENTITY kdvi "<application>KDVI</application>">
  <!ENTITY pybliographer "<application>pyBliographer</application>">
  <!ENTITY gbib "<application>gBib</application>">
  <!ENTITY makeidx "<application>makeidx</application>">
  <!ENTITY kate "<application>Kate</application>">
  <!ENTITY xfig "<application>XFig</application>">
  <!ENTITY cjk "<abbrev>CJK</abbrev>">
  <!ENTITY ucs "<abbrev>ucs</abbrev>">
  <!ENTITY kappname "&kile;">
  <!ENTITY package "kdeextragear-2">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book lang="&language;">

<bookinfo>
<title>The &kile; Handbook</title>

<authorgroup>
	<author><firstname>Jonathan</firstname><surname>Pechta</surname></author>
	<author><firstname>Federico</firstname><surname>Zenith</surname>
	<affiliation><address><email>zenith@chemeng.ntnu.no</email></address></affiliation></author>
	<othercredit role="developer">
		<firstname>Jeroen</firstname><surname>Wijnhout</surname>
		<affiliation>
		<address><email>Jeroen.Wijnhout@kdemail.net</email></address>
		</affiliation>
	</othercredit>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2003</year>
<holder>Jonathan Pechta</holder>
</copyright>

<copyright>
<year>2003</year><year>2005</year>
<holder>Federico Zenith</holder>
</copyright>

<date>2005-01-18</date>
<releaseinfo>1.7</releaseinfo>

<legalnotice>
&FDLNotice;
</legalnotice>

<abstract>
<para>
&kile; is a &latex; source editor, &tex; shell and &gnuplot; frontend.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdenonbeta</keyword>
<keyword>Kile</keyword>
<keyword>LaTeX</keyword>
<keyword>TeX</keyword>
</keywordset>

</bookinfo>

<chapter id="preface">

<title>Preface</title>

	<sect1 id="preface_sect">

		<title>Requirements</title>
			
		<para>To Run &kile;, you will be required to have the following components 
		installed on your system:</para>

		<itemizedlist>
			<listitem><para><ulink url="http://www.kde.org/">K Desktop environment (&kde;)</ulink>:
			&kde; is a popular open-source desktop environment.</para></listitem>
			<listitem><para><ulink url="http://www.trolltech.com/products/qt/">Qt</ulink>: Qt is a C++
			development tool needed to compile &kile;.</para></listitem>
			<listitem><para><ulink url="http://www.ctan.org/">&latex;</ulink>: high-quality document
			typesetting program. Most likely you have (or want) the &tetex; package, since you are on a
			Unix-like system.</para></listitem>
		</itemizedlist>

		<para>Optional packages:</para>

		<itemizedlist>
			<listitem><para><ulink url="http://devel-home.kde.org/~kdvi/">&kdvi;</ulink>: DVI viewer for &kde;.</para></listitem>
			<listitem><para><ulink url="http://www.gnuplot.info/">&gnuplot;</ulink>: scientific plotting package.</para></listitem>
			<listitem><para><ulink url="http://www.xfig.org/">&xfig;</ulink>: drawing program for X window.</para></listitem>
		</itemizedlist>

		<para>Some of these items might be included in your Linux distribution; please refer to your
		distribution documentation, or refer to your installation CD or DVD, for adding these
		packages to your computer.</para>

		<para>The &kile; project includes several binary packages of &kile; for different distributions that can be easily
		installed and run without having to compile; check out the <ulink url="http://kile.sourceforge.net/">&kile;
		homepage</ulink>.</para>

	</sect1>

	<sect1 id="preface_audience">

		<title>Intended Audience</title>

		<para>This manual is intended for any individual, regardless of her or his experience with
		&latex;, &kde;, &kile; or Linux.</para>

		<para>Advanced users are not likely to read this manual, but all suggestions on
		documentation will be considered. If you would like to contribute to this project or the
		documentation, please consult the <ulink url="http://kile.sourceforge.net/">&kile; web page</ulink>.
		Comments about documentation can be delivered to <email>zenith@chemeng.ntnu.no</email>.</para>

		<para>Need answers about &kile;? Are you stuck with your compile? Want to see a new
		feature? The preferred way to ask technical questions or start a discussion is to
		use our mailing list: <email>kile-devel@lists.sourceforge.net</email>.</para>

	</sect1>

</chapter>

<chapter id="introduction">

	<title>Introduction</title>

	<sect1 id="intro_about">

		<title>Basic facts</title>

		<sect2>

			<title>About &kile;</title>

			<para>&kile; is an integrated &latex; environment for the &kde; desktop. &kile; gives you the
			ability to use all the functionalities of &latex; in a graphical interface, giving you easy,
			immediate, and customised access to all programs for &latex; compiling, postprocessing,
			debugging, conversion and viewing tools; you also get very handy wizards, a &latex;
			reference, interfaces with &gnuplot; and &xfig;, and project management.</para>

		</sect2>

		<sect2>

			<title>What is &latex;</title>

			<para>&latex; is a text-processing system derived from &tex;, a program developed originally in
			1977 by Donald Knuth to help authors layout their work professionally, obtaining a work similar 
			to a typesetter's; the typesetter is the professional that styles a document's look according to 
			specifications for the type of document.
			&latex; was created by Leslie Lamport to give authors an automatic typesetter, especially when 
			it came to the expensive and painstaking typesetting of mathematical formulas and expressions,
			that <emphasis>by no chance</emphasis> are enclosed in dollar signs in &latex;.
			Today, word-processing programs let any user be the typesetter; but what you often want
			is a document that looks good, not one that you spent hours on to make it look good.
			&latex; takes that burden, and lets you think of the document, not of the layout. And yes,
			it <emphasis>will</emphasis> look good!</para>

		</sect2>

		<sect2>

			<title>How do you pronounce it? Why that strange typesetting?</title>

			<para>There is a funny traditions of &tex;-related packages to have the strangest pronounciation
			and typesetting possible. &tex; was supposed to be brought in from the greek <emphasis>τεχ</emphasis>,
			in latin letters <emphasis>tech</emphasis>. There are a lot of explanations why, but most likely it's because
			&latex; was originally conceived for technical reports, and indeed its foremost ability was the correct and
			easy typesetting of mathematical formulae, then an extremely expensive, time-consuming and
			frustrating business.</para>
			<para>The pronounciation is supposed to be as follows: <emphasis>T</emphasis> as you would expect,
			<emphasis>E</emphasis> as in <emphasis>get</emphasis>, and <emphasis>X</emphasis> as in the
			German i<emphasis>ch</emphasis>. If you don't know what <emphasis>ch</emphasis> sounds like,
			it is more or less as an hissing cat; the IPA symbol is /ç/. Many people report the different pronounciation
			of <emphasis>ach</emphasis> (IPA symbol /x/), but I have personally asked some Greeks, and can
			confirm the first version. You should be aware that a lot of people mispronounce /teks/ or /tek/.</para>
			<para>Last, in &latex; the first L<superscript>A</superscript> is pronounced as
			<emphasis>lay</emphasis>: the idea is that, while raw &tex; is difficult, even a <emphasis>lay</emphasis>man
			can use &latex; macros. A less inspiring, but more realistic explanation is that it stems from the surname of 
			Leslie Lamport, the creator of &latex;. Now you know!</para>

		</sect2>

	</sect1>

	<sect1 id="intro_latexbasics">

		<title>&latex; 101</title>

		<para>The &latex; typesetting system is similar to other markup languages as XML, used for
		many types of documents (including the one you are reading), or HTML, used for web
		pages. The general idea is about having specially wrapped keywords, called <emphasis>
		tags</emphasis>, that tell a program (a word processor, a web browser, or the &kile;
		compiler) how to present text. &kile; offers you a good number of such tags in the
		menu <guimenu>LaTeX</guimenu> in the menu bar.</para>

		<para>While we will try to give you a good idea of what &latex; is, this is not The Definitive
		Book on &latex;. If you want to learn &latex; well, you may want to loan a book in your
		library. The writer has had a good experience with A Guide to &latex; by H. Kopka
		and.P. W. Daly, and still keeps it on the shelf.</para>

		<para>As other markup languages, &latex; contains a <emphasis>preamble</emphasis>, which
		sets global commands, such as paper size, page numbering, dimensions of the text on the page,
		and a <emphasis>body</emphasis>, that contains the document text; the preamble contains
		at least the <userinput>\documentclass</userinput> command, and precedes the body, that 
		starts with the command <userinput>\begin{document}</userinput>, and is quite predictably 
		concluded by the command <userinput>\end{document}</userinput>.</para>

	</sect1>

	<sect1 id="intro_mainfeat">

		<title>&kile;'s Main Features</title>

		<sect2 id="intro_docwizard">

			<title>QuickStart Wizard</title>

			<para>The wizard built into &kile; is a useful feature to quickly start creating documents
			in &kile;. Choosing the wizard from the menubar gives you several choices
			for the creation of your document: article, book, letter, report, or empty. You can also
			specify some options related to the document right away.</para>

			<para>Wizard options:</para>

			<itemizedlist>
				<listitem><para><guilabel>Document Class</guilabel>: choose the type of document you want to create: article, 
				letter, report, book or other custom-defined.</para></listitem>
				<listitem><para><guilabel>Typeface Size</guilabel>: tell &kile; what point size you want to use.</para></listitem>
				<listitem><para><guilabel>Paper Size</guilabel>: choose the size or style of sheets.</para></listitem>
				<listitem><para><guilabel>Encoding</guilabel>: you will almost always want to use Latin 1 or Utf-8 encodings, 
				to allow you to enter words like <userinput>naïveté</userinput>
				directly, and not through the ASCII-fication <userinput>na\"\ivet\'e</userinput>; however, 
				many more options are available, like Latin 5 for Turkish.</para></listitem>
				<listitem><para><guilabel>Author's name</guilabel>: put your name here.</para></listitem>
				<listitem><para><guilabel>Title of Document</guilabel>: add your document title here.</para></listitem>
				<listitem><para><guilabel>Other options</guilabel>: this allows you to set further options such as printing, 
				draft, and others.</para></listitem>
			</itemizedlist>

		</sect2>

		<sect2 id="intro_templates">

			<title>Predefined Templates</title>

			<para>The predefined templates in &kile; are:</para>

			<itemizedlist>
				<listitem><para>Empty document: real men start from scratch!</para></listitem>
				<listitem><para>Article: sets the article format, for a document short enough not to
				be broken down to chapters.</para></listitem>
				<listitem><para>Report: sets the report format, for a middle-sized document, with for
				example page numbering on the page's outer edge.</para></listitem>
				<listitem><para>Book: sets the book format, a full-fledged flavour, so powerful that
				it is used to write many university textbooks.</para></listitem>
				<listitem><para>Letter: sets the letter format, that can automatically do those nasty
				indentations that nobody really remembers.</para></listitem>
			</itemizedlist>

			<para>New users need not to worry, this list is just a brief description of features,
			and more attention will be paid to complete these tasks in detail later in 
			<xref linkend="quickstart"/>.</para>

		</sect2>

		<sect2 id="intro_highlight">

			<title>Syntax Highlighting</title>

			<para>&kile; is similar to programs that deal with source code and editing, and will
			automatically highlight commands, options and items that are used and abused.
			&kile; makes so possible to spot easily problem areas: for example, if you see major
			areas of text turned green, it's likely that you forgot closing a math environment somewhere;
			you would have noticed anyway by how crappy the output file would have looked, but
			highlighting really saves you time and frustration.</para>

		</sect2>

		<sect2 id="intro_autocoml">

			<title>Auto-Completion of Environments</title>

			<para>The auto-completion of environments means that, when you begin a new environment by typing
			<userinput>\begin{environment}</userinput>, &kile; will automatically insert a matching
			<userinput>\end{environment}</userinput> command, with a line in between them
			for your text. You can of course deactivate it if you want in <menuchoice><guimenu>Settings</guimenu>
			<guimenuitem>Configure &kile;...</guimenuitem><guilabel>LaTeX</guilabel></menuchoice>.</para>

		</sect2>

		<sect2 id="intro_jump">

			<title>Jump to Structure Element</title>

			<para>All documents are normally structured in a hierarchy of some type.
			&latex; allows you to break up documents into the following hierarchy
			(part being highest in the hierarchy, and subparagraph being lowest):</para>

			<itemizedlist>
				<listitem><para>\part</para></listitem>
				<listitem><para>\chapter</para></listitem>
				<listitem><para>\section</para></listitem>
				<listitem><para>\subsection</para></listitem>
				<listitem><para>\subsubsection</para></listitem>
				<listitem><para>\paragraph</para></listitem>
				<listitem><para>\subparagraph</para></listitem>
			</itemizedlist>

			<para>When viewing a document in the <guilabel>Structure</guilabel> view, you can jump 
			between elements by clicking on the element you would like to view.</para>

		</sect2>

		<sect2 id="intro_inverse">

			<title>Inverse Search</title>

			<para>When creating your own &latex; file, inverse search can be very helpful. Once you
			have created a DVI file (DeVice Independent File), when you click the middle-
			mouse button in the DVI viewer, &kile; will jump to the corresponding line in the
			&latex; source code.</para>

			<para>A DVI is a type of file containing a
			description of a formatted document, along with other
			information including character font, and is the usual output of
			&tex; or &latex;. A number of utilities exist to view and print DVI files on
			various systems and devices. A DVI file is sometimes also known as
			a metafile.</para>

		</sect2>

		<sect2 id="intro_forward">

			<title>Forward Search</title>

			<para>When using inverse search, the selection of items in the DVI file is associated with
			the editor, so when you click on the DVI file, the main window jumps to the
			corresponding section of &latex; code in the editor. Forward search is the exact
			opposite of this. Forward search will allow you to click on a specific section of text
			in the &latex; code, and jump to the associated position in the DVI viewer window.</para>

		</sect2>

	</sect1>

	<sect1 id="intro_toolbar">

		<title>The Toolbar: a Reference Guide to Features</title>

		<itemizedlist>
			<listitem><para><guibutton>New</guibutton>: begin a new document.</para></listitem>
			<listitem><para><guibutton>Open</guibutton>: open a new document.</para></listitem>
			<listitem><para><guibutton>Close</guibutton>: close your document.</para></listitem>
			<listitem><para><guibutton>Define document as master</guibutton>: this is used when working with multiple files.
			Having a master document will let you work more easily with other .tex files included 
			in your document.</para></listitem>
			<listitem><para><guibutton>Quickbuild</guibutton>: compiles your &latex; source code and displays the results
			automatically, unless you have code errors.</para></listitem>
			<listitem><para><guibutton>Watch file mode</guibutton>: this mode will "watch" the DVI file for changes, and
			will not launch a new session of &kdvi; after <guibutton>Quickbuild</guibutton>.</para></listitem>
			<listitem><para><guibutton>View logfile</guibutton>: views the .log file, so you can spot errors.</para></listitem>
			<listitem><para><guibutton>Previous error</guibutton>: jumps backward through the .log file 
			and highlights errors in source.</para></listitem>
			<listitem><para><guibutton>Next error</guibutton>: jumps forward through .log file and 
			highlights errors in source.</para></listitem>
			<listitem><para><guibutton>Stop</guibutton>: halts current function.</para></listitem>
			<listitem><para><guibutton>LaTeX</guibutton>: runs &latex; on the active document.</para></listitem>
			<listitem><para><guibutton>View DVI</guibutton>: launches DVI viewer.</para></listitem>
			<listitem><para><guibutton>DVI to PS</guibutton>: converts DVI file to a PostScript (PS).</para></listitem>
			<listitem><para><guibutton>View PS</guibutton>: launches PostScript (PS) viewer.</para></listitem>
			<listitem><para><guibutton>PDFLaTeX</guibutton>: creates PDF from &latex; source, 
			if you have a &latex; header.</para></listitem>
			<listitem><para><guibutton>View PDF</guibutton>: views PDF.</para></listitem>
			<listitem><para><guibutton>DVI to PDF</guibutton>: converts a DVI to a PDF.</para></listitem>
			<listitem><para><guibutton>PS to PDF</guibutton>: converts a PS to a PDF.</para></listitem>
			<listitem><para><guibutton>LaTeX to HTML</guibutton>: creates HTML code from &latex; source.</para></listitem>
			<listitem><para><guibutton>View HTML</guibutton>: views HTML created.</para></listitem>
			<listitem><para><guibutton>Kdvi Forward Search</guibutton>: jump to page that corresponds to the current line in the
			editor.</para></listitem>
		</itemizedlist>

		<para>If you look at the <guilabel>Edit</guilabel> toolbar, you will notice three large 
		drop-down menus. The drop-down menus were designed for you to be able to quickly add
		certain common features into your document. The first drop-down box
		is used for quickly dividing your document by parts, chapter, sections and so on; the
		available commands to add segments to your &latex; source code are:</para>

		<itemizedlist>
			<listitem><para><guilabel>part</guilabel>: highest level of sectioning for a document.</para></listitem>
			<listitem><para><guilabel>chapter</guilabel>: starts a new chapter.</para></listitem>
			<listitem><para><guilabel>section</guilabel>: create a new section.</para></listitem>
			<listitem><para><guilabel>subsection</guilabel>: create a new subsection.</para></listitem>
			<listitem><para><guilabel>subsubsection</guilabel>: a secondary section between subsection and
			paragraph.</para></listitem>
			<listitem><para><guilabel>paragraph</guilabel>: create a new paragraph.</para></listitem>
			<listitem><para><guilabel>subparagraph</guilabel>: create a new subparagraph.</para></listitem>
		</itemizedlist>

		<para>The drop-down box named <guilabel>label</guilabel> is used to insert items to your document such as
		indexes, footnotes, and references; the available commands are:</para>

		<itemizedlist>
			<listitem><para><guilabel>label</guilabel>: a command that produces a label for a chapter, 
			a figure or another element.</para></listitem>
			<listitem><para><guilabel>index</guilabel>: creates an entry for the index.</para></listitem>
			<listitem><para><guilabel>footnote</guilabel>: creates a footnote in your document.</para></listitem>
			<listitem><para><guilabel>ref</guilabel>: used to refer to a predefined label, which
			you can choose from a drop-down list.</para></listitem>
			<listitem><para><guilabel>pageref</guilabel>: just like <guilabel>ref</guilabel>, but refers to 
			a page instead of a structure element.</para></listitem>
			<listitem><para><guilabel>cite</guilabel>: create a reference with data from a bibliography.</para></listitem>
		</itemizedlist>

		<screenshot>
			<screeninfo>The <guilabel>Label</guilabel> drop-down menu</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_ref_choose.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The <guilabel>Label</guilabel> drop-down menu</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<screenshot>
			<screeninfo>Selecting the label for a reference</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_ref_select.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Selecting the label for a reference</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>When using <guilabel>cite</guilabel>, you are presented with a drop-down list of bibitems, but if you
		are using &bibtex; this will only work if the file belongs to a Project. You can also use &gbib; or &pybliographer;, 
		or do it by hand.</para>

		<para>The last drop-down box labeled <guilabel>tiny</guilabel> is used to set the size of the text. You can
		set the size of the main text, of footnotes, and so on. The available commands are:</para>

		<itemizedlist>
			<listitem><para><guilabel>tiny</guilabel>: smallest.</para></listitem>
			<listitem><para><guilabel>scriptsize</guilabel>: very small.</para></listitem>
			<listitem><para><guilabel>footnotesize</guilabel>: smaller.</para></listitem>
			<listitem><para><guilabel>small</guilabel>: small.</para></listitem>
			<listitem><para><guilabel>normalsize</guilabel>: normal.</para></listitem>
			<listitem><para><guilabel>large</guilabel>: large.</para></listitem>
			<listitem><para><guilabel>Large</guilabel>: larger.</para></listitem>
			<listitem><para><guilabel>LARGE</guilabel>: even larger.</para></listitem>
			<listitem><para><guilabel>huge</guilabel>: still larger.</para></listitem>
			<listitem><para><guilabel>Huge</guilabel>: largest.</para></listitem>
		</itemizedlist>

	</sect1>

</chapter>

<chapter id="quickstart">

	<title>Quickstart</title>

	<sect1 id="quick_begin">

		<title>Writing a &latex; Document with &kile; for Beginners</title>

		<para>Users of &kile; have two choices when starting a new document: they can use the 
		<guimenu>Wizard</guimenu> to begin a new document, selecting the type of document they
		would like to create and options such as font size, paper size, and so on; otherwise, 
		they can write the code by hand.</para>

		<screen><userinput>
		\documentclass[12pt]{article}
		\begin{document}
		Here is a bunch of text coded in LaTeX.
		\end{document}</userinput></screen>

		<para>Every document in &latex; begins with the command <userinput>\documentclass{TypeOfDocument}</userinput>,
		unless you are using an older version of &latex;, then the command is <userinput>\documentstyle{TypeOfDocument}</userinput>.
		There are currently two common version of &latex; you might run into: version 2.09, which uses
		<userinput>\documentstyle</userinput>, and version 2<subscript>ε</subscript>, which uses
		<userinput>\documentclass</userinput> to begin a document. The command <userinput>\documentclass</userinput>
		always follows the syntax <userinput>\documentclass[optional argument]{class}</userinput>.</para>

		<para>Typing in the code example above from the text box gives you the following output:</para>

		<screen><computeroutput>
		Here is a bunch of text coded in LaTeX.</computeroutput></screen>

		<para>The brackets that come after the command <userinput>\documentclass</userinput>
		contain the options for the command. The option <userinput>[12pt]</userinput> sets the size
		of the font for your article; if you do not set the font size in the beginning, you can set 
		it later in the text.</para>

		<para>Once you have typed in the code example from the box above, you will need to
		compile your &latex; source code. The easiest way for you to compile &latex; is to
		use the <guimenu>Build</guimenu> menu, or using the <guilabel>Quickbuild</guilabel> button.</para>

		<para><keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>
		is the keyboard shortcut to compile your source code.</para>

		<para>You have to save your source code before you can compile; &kile; will do this automatically for you.</para>

		<para>If your document didn't compile, check the log for errors. When using the <guilabel>Quickbuild</guilabel>
		key, the &kdvi; viewer should be launched automatically; if it does not, look at the log.</para>

	</sect1>

	<sect1 id="quick_env">
		<title>Environments</title>

		<para>An environment is a segment of text that is managed differently
		than the rest of the document. For example, you create a report with font size 12, 
		but you need to change your font size for a few sentences. The commands 
		<userinput>\begin{environment}</userinput>, <userinput>\huge</userinput> and 
		<userinput>\end{environment}</userinput> will let you temporarily alter the text inside 
		the environment commands to be size huge.</para>

		<para>Changes are only effective from <userinput>\begin{environment}</userinput> to
		<userinput>\end{environment}</userinput>. There are no limits as how many changes
		you can make inside an environment.</para>

		<para>There are many features you can add to your document that will make it more
		readable and user-friendly. You can add features such as specific fonts, bold, italics,
		underline etc. to your document, and these commands will end with either an
		<userinput>\end</userinput> command, or at the end of your environment.</para>

		<itemizedlist>
			<listitem><para><userinput>\begin{emph}</userinput> or <userinput>\begin{em}</userinput>: this command makes 
			text italicised, and is valid until the code comes across a <userinput>\end{em}</userinput>,
			<userinput>\end{emph}</userinput> or another environment. To italicise one word in a sentence, you
			can use the syntax: this is <userinput>\em{my}</userinput> sentence.</para></listitem>
			<listitem><para><userinput>\bfseries{I'm making this text inside the brackets bold}</userinput>: this
			command makes your text bold. The bold command will continue until a close brace is found.</para></listitem>
			<listitem><para><userinput>\quote</userinput>: to create a quote inside your document; begin your quote
			with <userinput>\begin{quote}</userinput> and end it with <userinput>\end{quote}</userinput>.</para></listitem>
			<listitem><para><userinput>\center</userinput>: centers the text.</para></listitem>
			<listitem><para><userinput>\verse</userinput>: creates offset text for poems.</para></listitem>
			<listitem><para><userinput>\itemize</userinput>: makes an itemised list.</para></listitem>
		</itemizedlist>

	</sect1>

	<sect1 id="quick_using">

		<title>Using &kile;</title>

		<para>Now that we have given you some background about how to write code using the
		&latex; mark-up language, we will show you how to create a document
		using &kile; step-by-step.</para>

		<procedure>
        		<step><para>Start &kile;.</para></step>
			<step><para>Create new document, using <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem><guilabel>Empty
			Document</guilabel></menuchoice>.</para></step>
			<step><para>Select <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Quick Start</guimenuitem></menuchoice>,
			then choose a format, and set your preferences in the wizard.</para></step>
			<step><para>Once the wizard has entered text, do some customization to make the
			document more readable, add a minimum of one quote, some bold text,
			italics, and a verse to see the difference between the commands.</para></step>
			<step><para>Save your file, and give it the name <filename>intro.tex</filename>.</para></step>
			<step><para>Build your document using <keycombo><keycap>Alt</keycap>
			<keycap>2</keycap></keycombo>, or the button labeled <guilabel>LaTeX</guilabel>.</para></step>
			<step><para>Select <guibutton>View Dvi</guibutton>.</para></step>
			<step><para>Check out all your new text.</para></step>
			<step><para>When you are done viewing your document, click the <guibutton>Editor View</guibutton> 
			button to return to the editor if you are using the embedded viewer, or close the viewer window 
			if you are using a separate viewer.</para></step>
		</procedure>

		<para>That's it! You have just created your first &latex; document!</para>

		<para>Once you have created your DVI, you will be able to print your document, or change
		it into a postscript or PDF file if you want. Experiment and have fun!</para>

	</sect1>

	<sect1 id="quick_dvi">

		<title>DVI Files</title>

		<para>DVI stands for <emphasis>DeVice Independent</emphasis> file. These files are produced
		by &tex; or &latex; to be read by a driver of some sort on your computer. There are many different types of output that
		a .dvi can be sent to, such as a printer, postscript or PDF file converter, or your computer screen.</para>

	 	<sect2 id="quick_viewdvi">

			<title>Viewing a DVI</title>

			<para>You have already seen how to view a DVI file on the screen by using the <guibutton>View
			DVI</guibutton> button in the toolbar.</para>

		</sect2>

		<sect2 id="quick_printdvi">

        	<title>Printing a DVI</title>

			<para>To print a DVI, you can use the same process that you used to create your
			document earlier (see <xref linkend="quick_using"/>). At step 7, after
			clicking <guibutton>View DVI</guibutton>, select
			<menuchoice><guimenu>File</guimenu><guimenuitem>Print</guimenuitem></menuchoice>
			in the viewer, and if you have your printer properly configured, you will be able 
			to print the DVI.</para>

		</sect2>

		<sect2 id="quick_manprint">

			<title>Manually Printing a DVI from a console</title>

			<para>To print a DVI manually from a console, use first the command 
			<userinput>dvips intro.dvi</userinput>. The command will convert your DVI into a postscript file. 
			Once your file is converted, you can then print it using the command 
			<userinput>lpr intro.ps</userinput>.</para>

		</sect2>

		<sect2 id="quick_exportdvi">

			<title>Exporting a DVI</title>

			<para>The toolbar gives the options of exporting a DVI to other formats. Once you
			have created a DVI from your &latex; source code, you will be able to export it
			to a format of your choice using the toolbar buttons.</para>

		</sect2>

	</sect1>

	<sect1 id="quick_inverseforward">

		<title>Forward and Inverse searches between &kile; and &kdvi;</title>

		<sect2>

			<title>Forward Search</title>

			<para>The command Forward Search uses &kdvi; and an additional file (additional files are
			referred to as <emphasis>packages</emphasis> in &latex;) called <filename>srcltx.sty</filename>.
			You will have to do a search of your files to check if your distribution has 
			<filename>scrltx.sty</filename> included. If it is not included, you may 
			<ulink url="http://valis.cs.uiuc.edu/~sariel/research/latex/srcltx.sty">download it</ulink>; copy it 
			to a &tex; folder, for example <userinput>/usr/share/texmf/tex/latex/srcltx/</userinput>, and 
			run <userinput><command>texhash</command></userinput> so that &latex; will know its whereabouts. 
			Then you can set the following command in the preamble:</para>

			<screen><userinput>
		\documentclass[12pt, a4paper]{book}
		\usepackage[active]{srcltx}
		\pagestyle{empty}
		\renewcommand{\baselinestretch}{2}
		\begin{document}
		\begin{verse}
		The KDE \LaTeX\ source code editor &kile; is my favorite.
		
		\emph{Because} it is easy to use!
		\end{verse}
		\end{document}</userinput></screen>

			<para>Once you have added the package <filename>srcltx</filename>, you can leave &kdvi; open.
			To execute a forward search, position the cursor on a line of source code, and click 
			<guilabel>Kdvi Forward Search</guilabel> to jump to the associated position 
			in the DVI viewer window.</para>

		</sect2>

		<sect2>

			<title>Inverse Search</title>

			<para>Inverse search cannot work unless:</para>

			<itemizedlist>
				<listitem><para><filename>srcltx.sty</filename> is in use.</para></listitem>
				<listitem><para>The source file has been compiled successfully.</para></listitem>
				<listitem><para>&kdvi; knows which editor you would like to use.</para></listitem>
			</itemizedlist>

			<para>With this feature of &kdvi;, a middle mouse click in the DVI document will
			have &kile; open the corresponding &tex; document and attempt to go to the
			corresponding line. Remember to tell &kdvi; to use &kile; as a text editor, in &kdvi;'s
			menu item <menuchoice><guimenu>Settings</guimenu><guimenuitem>DVI Options...</guimenuitem></menuchoice>.</para>

			<screenshot>
				<screeninfo>Configuring &kdvi;</screeninfo>
				<mediaobject>
				<imageobject>
				<imagedata fileref="snap_kdvi_settings.png" format="PNG" />
				</imageobject>
				<textobject>
				<phrase>Configuring &kdvi;</phrase>
				</textobject>
				</mediaobject>
			</screenshot>
		</sect2>

		<sect2>

			<title>Resolving Errors</title>

			<para>If you are trying to use quickbuild, and the DVI viewer does not open, chances are
			you have an error. If you have an error, it will be visible in the log file / message area,
			and the summary of the error will be given.</para>

			<para>The log file will explain the source of the error in your code. In the
			editor, you can use the buttons in the toolbar labeled <guibutton>Previous LaTeX Error</guibutton>
			and <guibutton>Next LaTeX Error</guibutton> to jump to and from errors. The log file always states
			in which line the error occurred. To view the line where an error occurred, click on the error
			in the log window, and &kile; will take you to its line.</para>

		</sect2>

	</sect1>

</chapter>

<chapter id="startnew">

	<title>Starting a New Document</title>

	<para>When you click the button in the toolbar to begin a new document a dialog appears,
	asking which type of template you would like to use to write your document. The
	default choices are:</para>

	<itemizedlist>
		<listitem><para>Empty document</para></listitem>
		<listitem><para>Letter</para></listitem>
		<listitem><para>Book</para></listitem>
		<listitem><para>Article</para></listitem>
		<listitem><para>Report</para></listitem>
	</itemizedlist>

	<para>If you selected an <guilabel>Empty document</guilabel>, you can either start writing a document from scratch, 
	or you can use the wizard to quickly start a new document (see <xref linkend="intro_docwizard"/>).</para>


	<sect1 id="startnew_templates">

		<title>Templates</title>

		<para>Frequent users of &latex; typically use the same preamble for almost every document they use. 
		Templates can be created, saved and loaded within &kile; to make it easier to start a new document.</para>


		<sect2>
			<title>Create a New Template</title>

			<para>To create a new template, you must first either open a &tex; / &latex; file, or create a file
			of your own. &kile; can generate a template from an existing document by opening the desired document and selecting
			<menuchoice><guimenu>File</guimenu><guimenuitem>Create Template from Document</guimenuitem></menuchoice>.</para>

		</sect2>

		<sect2>

			<title>Configuring Automatic Substitutions</title>

			<para>When creating a new document by selecting a template from
			<menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>,
			certain character combinations will be replaced by data such as your name, 
			or the character encoding your are using. These variables can be configured in
			<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kile;</guimenuitem></menuchoice>.</para>

			<para>When designing your own template, it is useful to known which character 
			combinations are replaced by which template variables:</para>

			<itemizedlist>
				<listitem><para><userinput>$$AUTHOR$$</userinput>: This string
				will be replaced by the author variable.</para></listitem>
				<listitem><para><userinput>$$DOCUMENTCLASSOPTIONS$$</userinput>: This string will be replaced 
				by the documentclass options variable. Typically this is used as follows:
				<userinput>\documentclass[$$DOCUMENTCLASSOPTIONS$$]{article}</userinput>.</para></listitem>
				<listitem><para><userinput>$$INPUTENCODING$$</userinput>: If the
				inputencoding variable is set to, say, <userinput>latin1</userinput> this string is replaced by
				<userinput>\input[latin1]{inputenc}</userinput>.</para></listitem>
			</itemizedlist>

		</sect2>

		<sect2 id="templ_wiz">

			<title>Create a Template from the Wizard</title>

			<para>The easiest way to create a new template is to start the wizard,
			and then add commands in the editor. Once you have your
			document set up the way you like:</para>

			<procedure>
				<step><para>Save your file;</para></step>
				<step><para>Go to <guimenu>File</guimenu>;</para></step>
				<step><para>Choose <guimenuitem>Create Template from Document</guimenuitem>;</para></step>
				<step><para>Make any corrections necessary to the template;</para></step>
				<step><para>Enter a name for your new template;</para></step>
				<step><para>Click <guibutton>OK</guibutton> to add your template to the menu.</para></step>
			</procedure>

			<para>Next time you start up a new document, you will be able to choose 
			your customised template instead of the default ones.</para>

		</sect2>

		<sect2>

			<title>Creating a Template from any File</title>

			<para>A template can be created from any &latex; file. If you are looking for an easy way to
			configure a template, go find one you like on the internet and follow the same steps
			listed in <xref linkend="templ_wiz"/>.</para>

			<para>For istance, you may want to create a full-fledged A0 poster. These posters are usually seen
			at scientific conferences, and &latex; will help you making an attractive, catchy poster. You can get a
			template for A0 posters at <ulink url="http://www.stats.ox.ac.uk/~marchini/a0poster.html">Jonathan Marchini's 
			home page</ulink>, but many more are available. Remember that you will need the <filename>a0poster</filename> 
			package, which is normally not in a standard &tetex; installation, so you will have to 
			<ulink url="http://www.tug.org/tex-archive/help/Catalogue/entries/a0poster.html">download it</ulink>,
			copy it to a &tex; folder, for example <userinput>/usr/share/texmf/tex/latex/a0poster/</userinput>, and 
			run <userinput><command>texhash</command></userinput> so that &latex; will know that is exists. Do not forget
			setting the file permissions so that everybody can read the file.</para>

		</sect2>

		 <sect2 id="templ_rem">

	 		<title>Removing a Template</title>

			<para>To remove a template from &kile;, do as follows:</para>

			<procedure>
				<step><para>Go to <menuchoice><guimenu>Settings</guimenu><guimenuitem>Remove 
				template...</guimenuitem></menuchoice>;</para></step>
				<step><para>A dialog box will appear with all templates listed: select a template;</para></step>
				<step><para>Click <guilabel>OK</guilabel>, and your template will be removed.</para></step>
			</procedure>
			
			<para>Templates marked with an asterisk (*) cannot be removed without the proper permission.</para>

		</sect2>

	</sect1>

</chapter>

<chapter id="editing">

	<title>Editing &latex; Documents</title>

	<para>The internal editor that &kile; uses is &kate;.
	Kate is a text editor created for programmers, which incorporates the ability to read
	and highlight many different types of text files, among which &latex; and &bibtex;; you can access
	many options for &kate; directly from the &kile; <guimenu>Tools</guimenu> menu.</para>

	 <para>To learn more about &kate; and its capabilities, see the <ulink url="help:kate">Kate Handbook</ulink>.
	&kile; users can start reading from the chapter <quote>Working with the Kate Editor</quote>.</para>

	 <sect1 id="editing_sect">

		<title>The &latex; Reference</title>

		<para>&kile; features a very practical &latex; tag reference, which you can access
		by choosing <menuchoice><guimenu>Help</guimenu><guimenuitem>LaTeX 
		Reference</guimenuitem></menuchoice>. It contains a thorough description
		of almost all the commands that you may use in &latex; and their syntax.</para>

	</sect1>

	<sect1 id="editing_cursor">

	 	<title>Cursor Movements</title>
		
		<para>To select text, you have the following options:</para>

		<itemizedlist>
			<listitem><para>Hold left mouse button, and drag mouse to highlight text.</para></listitem>
			<listitem><para>Click once on a word to move the cursor to a new area.</para></listitem>
			<listitem><para>Click twice on a word to select the whole word.</para></listitem>
			<listitem><para>Click three times to select the whole sentence.</para></listitem>
		</itemizedlist>

		<para>Holding the left mouse button, and dragging the text you want to select,
		automatically copies the selected text to the clipboard.</para>

		<para>Holding shift and using the arrow keys allows you to select portions of the source
		code in the editor window.</para>

	</sect1>

	<sect1 id="editing_bracket">

		<title>Bracket Completion and Matching</title>

		<para>Bracket completion is a visual tool that the editor view uses to indicate you
		which bracket matches which. If you open any .tex file, and select any
		bracket, whether it be a parenthesis (), square brackets [] or braces {}, the editor will
		highlight the bracket and its match in yellow (this default color can be changed). So, for example,
		if you position the cursor on the braces in <userinput>\section{Introduction}</userinput>,
		you would see <userinput>\section{Introduction}</userinput> in the default yellow highlight,
		showing you the location of the beginning and ending brackets.</para>

	</sect1>

	<sect1 id="editing_highlight">

		<title>Highlighting</title>

		<para>&kile; has the ability to look for and highlight different types of code. For example, &latex; commands
		are distinguished from normal text, and formulas too are highlighted in a different color.</para>

	</sect1>

	<sect1 id="editing_completion">

		<title>Automatic Environment Completion</title>

		<para>When you begin a new environment, typing <userinput>\begin{environment}</userinput>,
		&kile; will automatically add a <userinput>\end{environment}</userinput> command, with a 
		line in between for your text.</para>

		<para>Auto-completion can be turned off in the &latex; section of
		<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kile;</guimenuitem></menuchoice>.
		</para>

		<screenshot>
			<screeninfo>Completing an Equation Environment</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_autocomplete.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Completing an Equation Environment</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

	</sect1>

	<sect1 id="editing_wizard">

		<title>Array Wizardry</title>

		<para>One of the most boring jobs one can do in &latex; is to write a matrix or a 
		tabular environment. One has to keep track of all the elements, ensure that the environment
		is well formed, and that all things are where they are supposed to be. Good indentation helps, 
		but there is a simpler way: using &kile;'s <guimenu>Wizard</guimenu> menu. Other than the 
		<guimenuitem>Quick Start</guimenuitem> option, it contains <guimenuitem>Tabular</guimenuitem>
		and <guimenuitem>Array</guimenuitem> (used in math environments). You will then have a 
		matrix-formed input form that you can easily fill in with your entries. The 
		<guimenuitem>Tabbing</guimenuitem> option will display a simpler menu to set up a 
		tabbing environment. In all these environments, you can easily set the
		number of rows and columns, along with other specific options.</para>

		<screenshot>
			<screeninfo>Inserting a tabular environment</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_wizardry.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Inserting a tabular environment</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

	</sect1>

</chapter>

<chapter id="latex">

	<title>Special Tags in &latex;</title>

	<sect1 id="latex_library">
		<title>Using the &latex; Tag Library</title>

		<para>&latex; has hundreds of tags for symbols and special characters. 
		The easiest way to insert special characters is to use the sidebar menu, 
		left of the editor window.</para>

		<screenshot>
			<screeninfo>The Sidebar Menu</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_sidebarmenu.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The Sidebar Menu</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>To add a special character, click on the type of character you would 
		like to add. You can add the following types of characters:</para>

		<itemizedlist>
			<listitem><para>Relational symbols</para></listitem>
			<listitem><para>Greek letters</para></listitem>
			<listitem><para>Arrows</para></listitem>
			<listitem><para>Delimiters</para></listitem>
			<listitem><para>Miscellaneous symbols</para></listitem>
			<listitem><para>Foreign characters</para></listitem>
		</itemizedlist>

	</sect1>

	<sect1 id="latex_bib">

		<title>Using Bibitems</title>

		<para><userinput>\bibitem</userinput> is a command used to enter a reference in a
		<userinput>thebibliography</userinput> environment in your document. The syntax for using
		<userinput>\bibitem</userinput> is <userinput>\bibitem[label]{key}</userinput>.</para>

		<para>The optional <userinput>[label]</userinput> is for you to add your own 
		labelling system for the bibliography entry. If no label is set, the entries 
		will be set in numerical order: [1], [2], [3], etc.</para>

		<para>The argument <userinput>{key}</userinput> is used to reference and link the commands
		<userinput>\bibitem</userinput> and <userinput>\cite</userinput> to
		each other and the information they contain. The command <userinput>\cite</userinput> contains the
		label associated with the intended <userinput>\bibitem</userinput>, which is located inside a
		<userinput>thebibliography</userinput> environment, and contains the reference data.
		Both corresponding <userinput>\bibitem</userinput> and <userinput>\cite</userinput> must
		have the same <userinput>{key}</userinput>; the easiest way to organise keys is by 
		the author's last name. The secondary braces in the <userinput>thebibliography</userinput> 
		environmen denote the longest bibliography label you expect to have. 
		So, inserting <userinput>{<replaceable>foo</replaceable>}</userinput> means 
		you can have any label shorter or as large as the expression 
		<userinput><replaceable>foo</replaceable></userinput>. Failure to set this parameter correctly 
		may result in a not so attractive indentation of your bybliography.</para>

		<para>The bibliography is a section apart from your main document, and an example of
		code for the bibliography would look like the following:</para>

		<screen><userinput>
		\begin{thebibliography}{50}
		\bibitem{Simpson} Homer J. Simpson. \textsl{Mmmmm...doughnuts}.
		Evergreen Terrace Printing Co., Springfield, SomewhereUSA, 1998
		\end{thebibliography)</userinput></screen>

		<para>Then, your main source code would contain the location of the information relating to
		the <userinput>\bibitem</userinput> using <userinput>\cite</userinput>. That source code would look similar to this:</para>

		<screen><userinput>
		My thesis, about the philosophy of The Simpsons\copyright
		comes from my favorite book \cite{Simpson}.</userinput></screen>

		<para>As it is often difficult to remember the exact citation key once you have many 
		references, &kile; provides an easy way to insert a citation. On the <guilabel>Edit</guilabel> 
		toolbar click on the second drop-down box (usually it reads <guilabel>label</guilabel>) and select 
		<guilabel>cite</guilabel>. A list with all the citation keys will show: select the correct 
		reference and a citation will be inserted in your document. To update the list of keys, 
		either save the file or choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh 
		Structure</guimenuitem></menuchoice>.</para>

		<para>The final product in your document's bybliography would then look like this:</para>

		<para><computeroutput>[1] Homer J. Simpson. Mmmmm...doughnuts. Evergreen Terrace Printing Co.,
		Springfield, SomewhereUSA, 1998.</computeroutput></para>

		<para>The easiest way to work with <userinput>\bibitem</userinput> and
		<userinput>\cite</userinput> is to use the toolbar drop-down box marked
		<guilabel>cite</guilabel>. When you select a citation to insert, you will be given the list of
		<userinput>bibitem</userinput>s you have created so far, and will be able to select the
		reference from the list. &kile; can also work together with &bibtex; editor applications,
		such as &gbib; and &pybliographer;, to help make citations easier.</para>

	</sect1>

	<sect1 id="latex_usertags">

		<title>User-Defined Tags</title>

		<para>&kile; gives you the ability to make your own tags. A tag is similar
		to a shortcut that launches some command or writes frequently-used text.
		For example, Joe Sixpack uses often the sentences <userinput>I prefer \LaTeX\ 
		to \TeX\</userinput> and <userinput>What would I do without Linux?</userinput>. 
		To create user-defined tags to write these sentences, he would access 
		<menuchoice><guimenu>User</guimenu><guisubmenu>User Tags</guisubmenu><guimenuitem>Edit 
		User Tags</guimenuitem></menuchoice>; this will present him a dialog where he can create 
		his own user-defined tags.</para>

		<screenshot>
			<screeninfo>The Edit User Tags Dialog</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_editusertag.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The Edit User Tags Dialog</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<screenshot>
			<screeninfo>Invoking a User-Defined Tag</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_usertag.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Invoking a User Defined Tag</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>He would probably give each tag a name that can clearly identify it. The name you give your tag 
		is entered in the section marked <guilabel>Menu item</guilabel>, and the text of frequently-used command 
		should be entered into the section labelled <guilabel>Value</guilabel>. Once the commands are entered, 
		he can use them quickly using the shortcut <keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap>
		<keycap>1</keycap></keycombo> for the first tag to enter <userinput>I prefer
		\LaTeX\ to \TeX\</userinput> and <keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap>
		<keycap>2</keycap></keycombo> to enter <userinput>What would I do without Linux?</userinput>.</para>

		<sect2 id="latex_usertags_uc">

			<title>Placeholders in User-Defined Tags</title>

			<para>There are some placeholders you can use in user-defined tags: 
			they are <userinput>%S</userinput>, <userinput>%M</userinput>, and
			<userinput>%C</userinput>.</para>

			<itemizedlist>
				<listitem><para><userinput>%S</userinput>: will be replaced by the source file's name.</para></listitem>
				<listitem><para><userinput>%M</userinput>: this stands for marked text; the selected text is
				inserted in its place when using user-defined tags.</para></listitem>
				<listitem><para><userinput>%C</userinput>: this is where the cursor will be placed after using a
				user-defined tag.</para></listitem>
			</itemizedlist>

			<para>To show you how this works let's say for example that we have a user-defined tag,
			which contains the value <userinput>\bfseries{%M}%C</userinput>, and I have a selection of text
			highlighted in my document that we want to turn into bold text. So, we highlight the
			phrase <userinput>I love Fridays</userinput>, apply our user-defined tag by pressing
			<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>1</keycap></keycombo>,
			and we get the text <userinput>\bfseries{I love Fridays}</userinput>, with the cursor 
			placed at the end of the text.</para>

		</sect2>

	</sect1>

</chapter>

<chapter id="build">

	<title>Using the Build Tools</title>

	<sect1 id="build_sect">

		<title>Compiling, converting and viewing</title>

		<para>To view the result of your work, you first need to compile the source. All the build 
		tools are grouped closely together in the
		<menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu></menuchoice>,
		<menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu></menuchoice>,
		and <menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu></menuchoice> 
		menus.</para>

		<para>To compile your source code for screen viewers like &kdvi;, other DVI viewers or
		further conversion, you can use the shortcut <keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>. 
		Then you can view the DVI file using your default viewer with 
		<keycombo><keycap>Alt</keycap><keycap>3</keycap></keycombo>, convert 
		the DVI to a PS file with <keycombo><keycap>Alt</keycap><keycap>4</keycap></keycombo>, 
		and view the PS file with <keycombo><keycap>Alt</keycap><keycap>5</keycap></keycombo>.</para>

		<sect2>

		<title>&bibtex;</title>

			<para>If you are using <ulink url="http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html">&bibtex;</ulink> 
			for your bibliography entries, you will have to follow a special compiling scheme.</para>

			<procedure>
				<step><para>Run &latex; with <keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>.</para></step>
				<step><para>Run &bibtex; with <keycombo><keycap>Alt</keycap><keycap>-</keycap></keycombo>: this 
				will compile the bybliography file.</para></step>
				<step><para>Run <emphasis>twice</emphasis> &latex; again, to incorporate the compiled bybliography 
				information, and to get citations and cross-referencing right.</para></step>
			</procedure>

			<para>You may also view the &bibtex; file with your &bibtex; editor of choice (for example &gbib;) 
			by choosing <menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu><guimenuitem>View 
			Bibtex</guimenuitem></menuchoice>; you can change the default &bibtex; viewer at 
			<menuchoice><guimenu>Tools</guimenu><guisubmenu>Configure 
			Kile...</guisubmenu><guilabel>Tools</guilabel></menuchoice>.</para>

		</sect2>

		<sect2>

			<title>MakeIndex</title>

			<para>If you are using the <ulink url="http://ipagwww.med.yale.edu/latex/makeindex.pdf">&makeidx;</ulink> 
			package to make a final, alphabetical index for your document, you have also to follow a certain
			compilation pattern.</para>

			<procedure>
				<step><para>Run &latex; with <keycombo><keycap>Alt</keycap><keycap>2</keycap></keycombo>.</para></step>
				<step><para>Make index with <keycombo><keycap>Alt</keycap><keycap>=</keycap></keycombo>: this 
				will compile the index file.</para></step>
				<step><para>Run &latex; again, to incorporate the compiled index information.</para></step>
			</procedure>

		</sect2>

		<sect2>

			<title>MetaPost</title>

			<para>If you want to compile your document with <application>MetaPost</application>, a picture 
			drawing program, you can do it with 
			<menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu><guimenuitem>Mpost</guimenuitem></menuchoice>.</para>

		</sect2>
		
		<sect2>

			<title>PDF&latex;</title>

			<para>There is also another way to compile your document, if you want a PDF: you can run 
			PDF&latex;, that will compile the source directly into a PDF file, with 
			<keycombo><keycap>Alt</keycap><keycap>6</keycap></keycombo>: you can then view the compiled 
			file pressing <keycombo><keycap>Alt</keycap><keycap>7</keycap></keycombo>.</para>

			<para>Alternatively, you can convert a PS into a PDF with 
			<keycombo><keycap>Alt</keycap><keycap>8</keycap></keycombo>, or directly a 
			DVI into a PDF with <keycombo><keycap>Alt</keycap><keycap>9</keycap></keycombo>.</para>

			<para>Using PDF&latex; instead of &latex; may be just a matter of simplicity or habit,
			but sometimes the behaviour of the two program can differ.</para>
			
		</sect2>

		<sect2>

			<title>&latex;2HTML</title>

			<para>Finally, you may want to publish your work on the web and not just on paper. You may
			then use the <application>latex2html</application> program, that can be called from &kile;'s menu
			<menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu><guimenuitem>LaTeX
			to HTML</guimenuitem></menuchoice>. The result will be placed in a subfolder of the work folder,
			and you will be able to see the result of the conversion choosing the menu item 
			<menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu><guimenuitem>View
			HTML</guimenuitem></menuchoice>.</para>

		</sect2>

		<sect2 id="build_cl">

			<title>Passing Command-Line Parameters</title>

			<para>If you want to pass some specific command-line parameters to the compile, convert 
			or view tools, you can configure their call in <menuchoice><guimenu>Settings</guimenu>
			<guimenuitem>Configure Kile...</guimenuitem><guilabel>Tools</guilabel></menuchoice>.</para>

		</sect2>
	
	</sect1>

	<sect1 id="build_graphics">

		<title>Graphic File Formats</title>

		<para>PDF&latex;, when used with <userinput>graphics</userinput> or
		<userinput>graphicx</userinput> packages, can compile correctly PNG and JPG files into
		the PDF, but is not able to handle EPS files.
		Conversely, the process of compiling to DVI and converting to PS and eventually PDF 
		does support EPS, but does not support PNG and JPG. To overcome this frustrating loop, 
		in case you want to include both EPS and PNG or JPG files, you have a number of workarounds:</para>

		<itemizedlist>
			<listitem><para>You can convert EPS files to PNG or other formats with utilities as the
			<ulink url="http://www.gimp.org/"><application>Gimp</application></ulink>, and use PDF&latex;.</para></listitem>
			<listitem><para>You can convert the other way around, and use &latex; and PS-PDF conversion;
			this is not always a good idea, since EPS encapsulation of JPG or PNG can yield larger 
			files, that in turn yield unnecessarily large documents; this is however <emphasis>highly</emphasis> 
			dependent on the graphic utility that you use, since EPS can encapsulate other graphics, 
			but not all applications support this perfectly; some might actually try to build your JPG image 
			with vectors and various scripting, which will result in gigantic files. 
			A simple program that does this process correctly is 
			<ulink url="http://www.tex.uniyar.ac.ru/win32/tools/jpg2ps/"><application>jpg2ps</application></ulink>.</para></listitem>
			<listitem><para>If you need a file in PS format, but have JPG or PNG graphics, you can also
			simply use PDF&latex; first, and then use the command-line instruction 
			<application>pdftops</application>, or, better yet, implement your own user tag to do that for you
			(see <xref linkend="latex_usertags"/>).</para></listitem>
		</itemizedlist>

		<para>Use the right file for the right graphic!</para>

	 	<itemizedlist>
			<listitem><para>EPS is sort of a graphic vector scripting language, describing
			all the lines and dots the graph is made of; it looks good even when magnified beyond its
			default size, and suits best diagrams and vectorial graphic natively produced in EPS, 
			which look very clear and sharp while maintaining a very small byte size.</para></listitem>
			<listitem><para>PNG (or the deprecated GIF) is a <emphasis>non-lossy</emphasis> file format, 
			with good compression and quality. It is very good for diagrams, scans of drawings, 
			or anything whose sharpness you do want to retain. It is sometimes overkill 
			when used for photos.</para></listitem>
			<listitem><para>JPG is a <emphasis>lossy</emphasis> format, that compresses files better than PNG 
			at the price of some loss in the picture detail. This is usually irrelevant for photos, 
			but may cause bad quality for diagrams, drawings, and may make some thin lines disappear outright; 
			in those cases use EPS or PNG.</para></listitem>
		</itemizedlist>

		<para>But always remember: garbage in, garbage out! No conversion will make a bad picture good.</para>

	</sect1>

	<sect1 id="build_master">

		<title>Master Document</title>

		<para>Defining your document as a master allows you to work with separated files,
		which gives you a parent document (or Master document), and child documents that
		make up a complete work. After having defined your Master document, with the
		corresponding command in the <guimenu>Settings</guimenu>
		menu, all the commands of the <guimenu>Tools</guimenu>
		menu will apply only to this document, even when you are working on the child
		documents. You can even close the Master document.</para>
	</sect1>

	<sect1 id="build_errorhandling">

		<title>Error Handling</title>

		<para>After you have compiled something, &kile; takes a look at the error messages that were generated. If there are
		any errors or warnings, they will be briefly reported in the Log / Messages window. One can take a closer look at the
		messages by selecting <menuchoice><guimenu>Build</guimenu><guimenuitem>View Log File</guimenuitem></menuchoice>,
		or by using the keyboard shortcut <keycombo><keycap>Alt</keycap><keycap>0</keycap></keycombo>.
		The generated log is then displayed in the Log / Messages view; errors and warnings are highlighted.</para>

		<screenshot>
			<screeninfo>Viewing the log</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_compile_error.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Viewing the log</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>You can easily jump from one message in the log file to another by using the
		<menuchoice><guimenu>Build</guimenu><guimenuitem>Next / Previous
		LaTeX Error / Warning</guimenuitem></menuchoice> menu items, or by using
		the corresponding toolbar buttons.</para>

		<para>To jump to the line in the &latex; source where the error or warning occurred,
		click on the error or warning in the Log/Messages view.
		&kile; will take you automatically to the offending line.</para>

	</sect1>

	<sect1 id="build_watch">

			<title>Using the Watch File Mode</title>

			<para>When you launch the <guibutton>Quickbuild</guibutton> command, a viewer of
			some sort will normally be called after the compilation. If you are not using an embedded 
			viewer, a new window will be open every time.</para>

			<para>If you are adjusting the look of your document, you might launch
			<guibutton>Quickbuild</guibutton> very often, and have many viewer windows open on
			your desktop; to avoid this confusion, you can activate the <guibutton>Watch file</guibutton>
			mode, that will prevent <guibutton>Quickbuild</guibutton> from launching a viewer.</para>
			
			<para>Presently, &kdvi; supports continuous updating of the viewed DVI file, but
			&kghostview; is not as perfect: to update the document after compiling, you will have
			to change page, and the number of pages will not be changed in &kghostview;'s visualisation.</para>
			
			<para>This mode is of course useless with the embedded viewers, as you have to close them
			anyway to get back to editing the document and recompiling.</para>

	</sect1>

</chapter>

<chapter id="navigating">

	<title>Navigating the &latex; Source</title>

	<sect1 id="navigating_struct">

		<title>Using the Structure View</title>

		<para>The <guilabel>Structure</guilabel> view shows the hierarchy of the document
		being created in &kile;, and allows you to quickly navigate it, showing its segmentation. 
		To navigate around your document, all you need to do is to left click on any label, chapter, 
		section, subsection, etc., and you will be taken to the beginning of
		the corresponding area.</para>
		
		<para>If you included a separate &latex; file in your source using
		the <userinput>\input</userinput> or <userinput>\include</userinput> tags, these files will
		be referred to in the <guilabel>Structure</guilabel> view; double-clicking on their names in
		it will make &kile; bring up the included file in the editor window.</para>
		
		<para>The hierarchy tree has also a separate branch for labels used in the text.</para>

		<screenshot>
			<screeninfo>Using the Structure View</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_structview_label.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Using the Structure View</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<sect2 id="navigating_update">

			<title>Updating the Structure View</title>

			<para>To update your structure view you can either go to 
			<menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh 
			Structure</guimenuitem></menuchoice>, or you can save your document,
			which will make &kile; update its <guilabel>Structure</guilabel> view.</para>

		</sect2>

	</sect1>

	<sect1 id="navigating_bookmarks">

		<title>Bookmarks</title>

		<para>Bookmarks are your reference to a segment of text or a line inside the &kile;
		environment. To use a bookmark, select a specific line of your document
		you would like to return to, then press <keycombo><keycap>Ctrl</keycap>
		<keycap>B</keycap></keycombo>, and &kile; will add a bookmark to this line. 
		Alternatively, you can also set a bookmark by highlighting a line and choosing 
		the menu labeled <menuchoice><guimenu>Bookmark</guimenu><guimenuitem>Toggle 
		Bookmark</guimenuitem></menuchoice>.</para>

		<para>To remove all your bookmarks, select <menuchoice><guimenu>Bookmarks</guimenu>
		<guimenuitem>Clear Bookmarks</guimenuitem></menuchoice>.</para>

	</sect1>

</chapter>

<chapter id="projects">

	<title>Projects</title>

	<sect1 id="projects_working">
	
		<title>Working with Projects</title>

		<para>In &kile; you can create and work with <emphasis>projects</emphasis>. A project is a 
		group of &latex;, &tex; or other documents that contain all the information that is used to build 
		your complete document. A typical project would be a document consisting of several chapters, 
		written in different <filename>.tex</filename> files; all of them could be included in
		a project, to make the whole document easier to manage. You can also store non-source files
		such a graphics in a project. The specifications of the project are stored in a special file, 
		with extension .kilepr.</para>

		<para>A Project adds the following functionalities:</para>

		<itemizedlist>
			<listitem><para>You need not set a master document, &kile; does this automatically.</para></listitem>
			<listitem><para>Project files can easily be archived together.</para></listitem>
			<listitem><para>The <guilabel>Files and Project</guilabel> view shows which files are included
			in the project.</para></listitem>
			<listitem><para>After opening a project, any file that was previously opened will be
			restored with the original encoding and highlighting.</para></listitem>
		</itemizedlist>

	</sect1>

	<sect1 id="projects_creating">

		<title>Creating a Project</title>

		<para>To create a project, select <menuchoice><guimenu>Project</guimenu>
		<guimenuitem>New Project...</guimenuitem></menuchoice>. You will be
		asked to give the following information to create your project:</para>
		<itemizedlist>
			<listitem><para>Title of your project.</para></listitem>
			<listitem><para>Name of the project file with .kilepr extension.</para></listitem>
			<listitem><para>Filename.</para></listitem>
			<listitem><para>Type of file creating: Empty Document, Article, Book, Letter, Report.</para></listitem>
		</itemizedlist>

		<para>When you fill out the <guilabel>filename</guilabel> box, you have to include a relative 
		path from where the .kilepr project file is stored to the file.</para>

	</sect1>

	<sect1 id="projects_view">

		<title>Using the File and Project View</title>

		<para>The <guilabel>File and Project</guilabel> view is a button of the sidebar menu. 
		From this view, you can see the structure of your project, its files, 
		and the name of the .kilepr file that stores the project information. 
		Adding, removing, or changing options in your project are done via
		the <guilabel>File and Projects</guilabel> view.</para>

		<screenshot>
			<screeninfo>The File and Project View</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_projectview.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The File and Project View</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

	</sect1>

	<sect1 id="projects_adding">

		<title>Adding and Removing Files</title>

		<para>To add a file to your project, open any &tex; file, right click on its name in the
		<guilabel>Files and Project</guilabel> view, and select <guilabel>Add to
		Project</guilabel>. If you have multiple projects open, a dialog box will ask
		you which project the file has to be added to.</para>

		<para>If you have multiple files to be added to a project, you can select the
		project from the <guilabel>Files and Project</guilabel> view and right-click then select
		<guilabel>Add Files</guilabel>; you will then be able to select your files in a dialog box.</para>
		
		<para>You can also right-click on the project's name in the <guilabel>Files and 
		Project</guilabel> view, and select <guilabel>Add Files...</guilabel> to bring
		up a file selection dialog.</para>

		<screenshot>
			<screeninfo>Adding a file to a project</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_projectview_add.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Adding a file to a project</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>To remove a file from a project, right-click on it and select <guilabel>Remove File</guilabel>.
		This does <emphasis>not</emphasis> delete your file, but only removes it from the list 
		of files contained in the .kilepr extension.</para>

	</sect1>

	<sect1 id="projects_options">

		<title>Changing your Project's Options</title>

		<para>&kile; has a few options related to your project that can be set. To change them,
		right-click on the title of your project and select <guilabel>Project Options</guilabel>,
		and you will have the option of changing:</para>

		<itemizedlist>
			<listitem><para>The title of your project.</para></listitem>
 			<listitem><para>The archive command.</para></listitem>
 			<listitem><para>Recognised extensions for non-source files.</para></listitem>
 			<listitem><para>The option to use file extensions as regular expressions.</para></listitem>
		</itemizedlist>

		<sect2 id="projects_archive">

			<title>Archiving your Project</title>

			<para>&kile; allows you to easily backup your project by storing all its files 
			into a single archive (often known as <emphasis>tarball</emphasis>). To archive your project 
			right-click on its name in the <guilabel>Files and Project</guilabel> view, or select 
			<menuchoice><guimenu>Project</guimenu><guimenuitem>Archive</guimenuitem></menuchoice>.</para>

			<para>By default, all files in a project are added to the archive. If you don't want to include 
			a certain file in the archive, right-click on it in the <guilabel>Files and Project</guilabel> 
			view, and uncheck the <guilabel>Include in Archive</guilabel> option.</para>

			<para>Archive commands are simple shell commands that are executed from the project
			folder (where the .kilepr file is located). Some placeholders can be used
			when writing the archive command:</para>

			<itemizedlist>
				<listitem><para><userinput>%S</userinput>: this is replaced by the name of 
				your project file without the .kilepr extension.</para></listitem>
				<listitem><para><userinput>%F</userinput>: this command is used to replace 
				the list of files to be included in the archive.</para></listitem>
			</itemizedlist>

		</sect2>

		<sect2 id="projects_ext">

			<title>Extensions for Non-Source Files</title>

			<para>Non-source files are files such as pictures, PDF or postscript files, etc. that are 
			to be included in the project, but are not source files with the extension .tex. You have 
			the option to use your own regular expressions to match non-source files.</para>

		</sect2>

	</sect1>

	<sect1 id="projects_closing">

		<title>Closing a Project</title>

		<para>To close a project, select the <guilabel>Files and Project</guilabel> view from
		the vertical toolbar, right click on your project title, and then select <guimenuitem>
		Close</guimenuitem>. This will close your project, all the files associated with your project,
		and will also add the name of the project you just closed to <guisubmenu>Open Recent
		Project...</guisubmenu> in the <guimenu>Project</guimenu> menu.</para>

	</sect1>

</chapter>

<chapter id="lang">

	<title>Setting the Document's Encoding</title>

	<para>The &kile; editor allows you to read, convert and set the text to the encoding 
	your document needs. This allows you to use non-standard letters and symbols; 
	you can use, for example, accented characters for Italian or French.
	Selecting the encoding for your document can be done in three ways:</para>

	<itemizedlist>
		<listitem><para>One way to set the encoding is to use the <guilabel>Set encoding</guilabel> combo
		box, located at the bottom of the <guilabel>Open File</guilabel> sidebar view.</para></listitem>
		<listitem><para>Another way is using the submenu <menuchoice><guimenu>View</guimenu><guisubmenu>Set
		Encoding</guisubmenu></menuchoice>.</para></listitem>
		<listitem><para>A third way to set the encoding for a document is to set the option
		when you use the wizard to create a new document.</para></listitem>
	</itemizedlist>

	<para>&latex; itself understands only ASCII, a very limited set of characters, so you couldn't use
	accented or special letters directly. To use accented letters, a special syntax was created: 
	such as for example <userinput>\"e</userinput> for <computeroutput>ë</computeroutput>. 
	There is a package to help you with this, called <application>inputenc</application>, and is included 
	in the preamble using <userinput>\usepackage[latin1]{inputenc}</userinput>, where the optional argument 
	is the encoding you would like to use (in most cases <userinput>latin1</userinput>). This tells &latex;
	to translate all of the <userinput>ë</userinput>'s you wrote to <userinput>\"e</userinput>'s before
	compiling. Please refer to the <application>inputenc</application> documents directly for more
	information on <application>inputenc</application>. Last but not least: remember to make sure that 
	your file is <emphasis>actually</emphasis> encoded in the same encoding you told 
	<application>inputenc</application>!</para>

	<screenshot>
		<screeninfo>Choosing the source file's encoding</screeninfo>
		<mediaobject>
		<imageobject>
		<imagedata fileref="snap_encoding.png" format="PNG" />
		</imageobject>
		<textobject>
		<phrase>Choosing the source file's encoding</phrase>
		</textobject>
		</mediaobject>
	</screenshot>

	<para>This host of different character coding tables has been creating problems on 
	many applications: for example, you cannot write a course of Turkish in French without 
	losing one language's special characters. There is general agreement that, sooner or later, 
	everybody will switch to <ulink url="http://www.unicode.org">Unicode</ulink>. There
	are many implementations of Unicode, and <abbrev>utf-8</abbrev> is the most
	successful in Linux; Windows&reg; relies instead on the more cumbersome and
	less flexible <abbrev>ucs-2</abbrev>. Some distributions, as RedHat, have already
	begun setting their default encoding to <abbrev>utf-8</abbrev>, and therefore you
	may be very interested in using a <userinput>utf-8</userinput> argument to the
	<userinput>inputenc</userinput> package.</para>

	<para>The bad news is, it's not yet included in &tetex; at the time of writing this
	document; the good news is, there <emphasis>is</emphasis> a &latex; package
	that can do just that, and you can install it yourself.</para>

	<sect1 id="ucs">
	
		<title>The &ucs; Package</title>
		
		<para>You can get the &ucs; package from the home page of 
		<ulink url="http://www.unruh.de/DniQ/latex/unicode/">Unicode support for 
		&latex;</ulink>, by Dominique Unruh from the university of Karlsruhe.</para>
		
		<para>To install it, unpack the downloaded file and move the uncompressed 
		contents to a directory that &tex; can see; you could for instance use 
		<userinput>/usr/share/texmf/tex/latex/ucs/</userinput> (make sure this is 
		actually your $<envar>TEXMF</envar> path, as it sometimes change depending 
		on the distribution you use!). Make the directory globally readable if it is
		not already, and the subdirectories executable, using <command>chmod</command>.
		You have to perform all these actions as root, so be careful.</para>
		
		<para>When you have finished, launch the <command>texhash</command> command
		to make &tex; review its files, and hopefully find the new package. Refer to 
		the package documentation for details, but generally you will need little more
		than setting the following in your preamble:
		<screen><userinput>
		\usepackage{ucs}
		\usepackage[utf8x]{inputenc}</userinput></screen></para>
		
	</sect1>
	
	<sect1 id="cjk">
		
		<title>Chinese, Japanese and Korean (&cjk;) Support</title>
		
		<para>Adding support for ideographic languages is quite tricky. However, once
		you are done with it, it will work quite well. Other than installing packages,
		there is some extra configuration work to do.</para>
		
		<tip><para>Your Linux distribution might already have a &cjk; package ready for 
		you, so you might be saved the hassle of manually installing everything. Do check 
		before going forward!</para></tip>
		
		<para>There is the possibility of using the &ucs; package in order to write
		short snippets of &cjk; text, but that option is seriously limited as it does
		not handle, among other things, newlines. We will instead install the complete
		&cjk;-&latex; package and make it work for both &latex; and PDF&latex;. A lot
		of this material has been inspired by <ulink url="http://www.ece.uci.edu/~chou/">Pai
		H. Chou</ulink>'s <ulink url="http://www.ece.uci.edu/~chou/unicode-tex.html">page 
		about how to setup PDF&latex;</ulink>.</para>
		
		<orderedlist>
		
		<listitem><para>Download the <ulink 
		url="http://www.ctan.org/tex-archive/help/Catalogue/entries/cjk.html">&cjk;</ulink> 
		package. Copy its unpacked files to an appropriate subfolder of 
		$<envar>TEXMF</envar>, just like you did with the &ucs; package 
		before (see <xref linkend="ucs"/>). The files will be unpacked in a 
		<filename>CJK/X_Y.Z</filename> directory, it is not important that you 
		take them out, though it will probably be tidier for you to 
		maintain.</para></listitem>
		
		<listitem><para>Now you have to download a font that supports all the &cjk; characters 
		you need. You can choose any <literal role="extension">*.ttf</literal> file that
		covers them, but in this walkthrough we will use <ulink
		url="ftp://ftp.netscape.com/pub/communicator/extras/fonts/windows/Cyberbit.ZIP">Cyberbit</ulink>.
		Unzip the file and rename <filename>Cyberbit.ttf</filename> to 
		<filename>cyberbit.ttf</filename>, since uppercase might confuse your system.</para>
		<para>Place <filename>cyberbit.ttf</filename> in a folder together with
		<ulink url="http://delloye.free.fr/Unicode.sfd"><filename>Unicode.sfd</filename></ulink>,
		and generate the <literal role="extension">*.tfm</literal> and 
		<literal role="extension">*.enc</literal> files with the command 
		<command>$ ttf2tfm cyberbit.ttf -w cyberbit@Unicode@</command>. 
		For some reasons, sometimes this does not produce the hundreds 
		of files it should. Should that be your case, you can download both 
		<ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-tfm.tgz"><literal
		role="extension">*.tfm</literal></ulink> and 
		<ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-enc.tgz"><literal
		role="extension">*.enc</literal></ulink> files.</para>
		<para>Place the <literal role="extension">*.tfm</literal> files in an 
		appropriate folder, say <filename>$TEXMF/fonts/tfm/bitstream/cyberbit/</filename>;
		the <literal role="extension">*.enc</literal> files may be installed in
		<filename>$TEXMF/pdftex/enc/cyberbit/</filename>.</para></listitem>
		
		<listitem><para>Now we need a map file to connect the <literal
		role="extension">*.enc</literal> files to the font. Download <ulink
		url="http://delloye.free.fr/cyberbit.map"><filename>cyberbit.map</filename></ulink> 
		and install it in <filename>$TEXMF/pdftex/config/</filename>.</para></listitem>
		
		<listitem><para>Download another file, <ulink 
		url="http://delloye.free.fr/c70cyberbit.fd"><filename>c70cyberbit.fd</filename></ulink>,
		and place it in an appropriate folder. You may choose, for example, 
		<filename>$TEXMF/tex/misc/</filename>.</para></listitem>
		
		<listitem><para>The last file we have to generate is a PostScript Type 1
		font, necessary to read DVI files generated with &latex;. Run the command
		<command>$ ttf2pfb cyberbit.ttf -o cyberbit.pfb</command>, and copy the
		resulting <filename>cyberbit.pfb</filename> in a folder like
		<filename>$TEXMF/fonts/type1/cyberbit/</filename>.</para></listitem>
		
		<listitem><para>Let's now place <filename>cyberbit.ttf</filename> among the fonts 
		where &latex; can find it. You could place it in a folder named 
		<filename>$TEXMF/fonts/truetype/</filename>.</para></listitem>
		
		<listitem><para>Check the configuration file you find at
		<filename>$TEXMF/web2c/texmf.cnf</filename>, and make sure that the 
		line mentioning <envar>TTFONTS</envar> is uncommented and points to 
		the folder where you saved <filename>cyberbit.ttf</filename>.</para></listitem>
		
		<listitem><para>To make it possible for PDF&latex; to use your &cjk; 
		fonts, it is necessary that you add a line in configuration file
		<filename>$TEXMF/pdftex/config/pdftex.cfg</filename>. Add 
		<userinput>map +cyberbit.map</userinput> in the file to complete the
		configuration for PDF&latex;.</para></listitem>
		
		<listitem><para>To configure &latex; so that you can produce DVI 
		files with &cjk; characters, you have to add a line in file 
		<filename>ttfonts.map</filename>. The file might be in a directory named 
		<filename>$TEXMF/ttf2pk/</filename>, but you will probably have to look 
		for it. Add the line <userinput>cyberbit@Unicode@ cyberbit.ttf</userinput>
		into it.</para></listitem>
		
		<listitem><para>Now, you only have to run <command>texhash</command> and 
		the system should be ready.</para></listitem>
		
		</orderedlist>
		
		<para>To test whether your configuration is correct, you can try to compile
		<ulink url="http://www.math.nus.edu.sg/aslaksen/cs/sample-utf8.tex">this test
		file</ulink>.</para>
		
		<sect2>
			<title>&cjk; Troubleshooting</title>
			
			<para>There are many things that can go wrong when setting &cjk; 
			support manually. If something seems not to work, the following 
			checklist might help you.</para>
			
			<itemizedlist>
			
			<listitem><para>Obviously, since you run &latex; as a user and
			not as root, you must <emphasis>allow</emphasis> ordinary users
			to access the new files. Make sure all folders and files are 
			accessible using the <command>chmod</command> command.</para></listitem>
			
			<listitem><para>If &latex; writes a DVI without problems, but you
			cannot view it, it's almost certainly because of some problems in the
			automatic generation of <literal role="extension">*.pk</literal> 
			fonts. They are supposed to be generated on the fly when viewing a
			DVI file, but this might fail for a number of reasons: double-check
			<filename>ttfonts.map</filename> for your custom line first. However,
			it might happen that your <command>ttf2pk</command> command, which 
			is usually invoked by the DVI viewer, has been compiled 
			<emphasis>without</emphasis> support for the 
			<application>kpathsea</application> libraries. If this is the case,
			<command>$ ttf2pk --version</command> will make no mention of 
			<application>kpathsea</application>. As support for these libraries
			is necessary, you might have to find a new package, or recompile
			<application>FreeType 1</application> by yourself.</para></listitem>
			
			</itemizedlist>
			
		</sect2>
			
		
		<sect2>
		
			<title>How do I input &cjk; in Unicode?</title>
			
			<para>There are a number of different input engines, and the choice can
			depend also on personal preference. The author uses <ulink 
			url="http://www.scim-im.org/projects/skim"><application>Skim</application></ulink>,
			a port to &kde; of the <ulink 
			url="http://www.scim-im.org"><application>Scim</application></ulink>
			engine. Refer to your distribution's documentation to learn how to 
			install these programs. Configuration of such programs can be tricky
			too, in the case of <application>Skim</application> you will have to 
			define an environment variable <userinput>XMODIFIERS="@im=SCIM"</userinput> 
			<emphasis>before</emphasis> starting <application>X</application>.</para>
		
		</sect2>
	
	</sect1>

</chapter>

<chapter id="credits">

	<title>Credits and License</title>

	<para>&kile; is an open-source user-friendly &latex; / &tex; source code editor. It will run on systems
	with the &kde; Desktop Environment installed. &kde; is available for several architectures
	with Linux and other Unix-like systems installed. &kile; is also part of the Fink project,
	which means you can run &kile; on a Mac with OS-X.</para>

	<para>Many thanks are owed to those who strive to continue the &kile; project, and the many
	hours of contributions made by those who sacrifice their time to develop tools we can all
	use under the <acronym>GNU</acronym> license. Here is a short list of the programmers, editors, translators,
	writers, debuggers, packagers, web developers and users who made this project possible.</para>

	<para>Program copyright 2003 and currently maintained by Jeroen
	Wijnhout <email>Jeroen.Wijnhout@kdemail.net</email></para>

	<para>Program copyright 2002-2003 Pascal Brachet</para>

	<para>&kile; contains source code from the free (GPL) program
	<application>Xgfe</application> (X Windows GUI front end to &gnuplot;),
	Copyright &copy; 1998 David Ishee</para>

	<para>Documentation Copyright &copy; 2003 Jonathan Pechta, 2003-2005 Federico Zenith</para>

	<para>Contributions from: Rob Lensen, Roland Schulz, Michael Margraf</para>

	<para>Many thanks to all those involved!</para>

	&underFDL;               <!-- FDL: do not remove -->
	&underGPL;        	 <!-- GPL License -->

</chapter>

&documentation.index;

</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
-->
