# The &kile; Handbook

Jonathan
Pechta
Federico
Zenith

    zenith@chemeng.ntnu.no

Jeroen
Wijnhout

    Jeroen.Wijnhout@kdemail.net

2003
Jonathan Pechta
2003
2005
Federico Zenith
2005-01-18
1.7
&FDLNotice;

&kile; is a &latex; source editor, &tex; shell and &gnuplot; frontend.

KDE
kdenonbeta
Kile
LaTeX
TeX

## Preface

### Requirements

To Run &kile;, you will be required to have the following components installed on your system:

- K Desktop environment (&kde;): &kde; is a popular open-source desktop environment.

- Qt: Qt is a C++ development tool needed to compile &kile;.

- &latex;: high-quality document typesetting program. Most likely you have (or want) the &tetex; package, since you are on a Unix-like system.

Optional packages:

- &kdvi;: DVI viewer for &kde;.

- &gnuplot;: scientific plotting package.

- &xfig;: drawing program for X window.

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.

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 &kile; homepage.

### Intended Audience

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

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 &kile; web page. Comments about documentation can be delivered to zenith@chemeng.ntnu.no.

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: kile-devel@lists.sourceforge.net.

## Introduction

### Basic facts

#### About &kile;

&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.

#### What is &latex;

&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 by no chance 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 will look good!

#### How do you pronounce it? Why that strange typesetting?

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 τεχ, in latin letters tech. 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.

The pronounciation is supposed to be as follows: T as you would expect, E as in get, and X as in the German ich. If you don't know what ch sounds like, it is more or less as an hissing cat; the IPA symbol is /ç/. Many people report the different pronounciation of ach (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/.

Last, in &latex; the first LA is pronounced as lay: the idea is that, while raw &tex; is difficult, even a layman 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!

### &latex; 101

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 tags, 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 LaTeX in the menu bar.

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.

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

### &kile;'s Main Features

#### QuickStart Wizard

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.

Wizard options:

- Document Class: choose the type of document you want to create: article, letter, report, book or other custom-defined.

- Typeface Size: tell &kile; what point size you want to use.

- Paper Size: choose the size or style of sheets.

- Encoding: you will almost always want to use Latin 1 or Utf-8 encodings, to allow you to enter words like `naïveté` directly, and not through the ASCII-fication `na\"\ivet\'e`; however, many more options are available, like Latin 5 for Turkish.

- Author's name: put your name here.

- Title of Document: add your document title here.

- Other options: this allows you to set further options such as printing, draft, and others.

#### Predefined Templates

The predefined templates in &kile; are:

- Empty document: real men start from scratch!

- Article: sets the article format, for a document short enough not to be broken down to chapters.

- Report: sets the report format, for a middle-sized document, with for example page numbering on the page's outer edge.

- Book: sets the book format, a full-fledged flavour, so powerful that it is used to write many university textbooks.

- Letter: sets the letter format, that can automatically do those nasty indentations that nobody really remembers.

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 .

#### Syntax Highlighting

&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.

#### Auto-Completion of Environments

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

#### Jump to Structure Element

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):

- \part

- \chapter

- \section

- \subsection

- \subsubsection

- \paragraph

- \subparagraph

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

#### Inverse Search

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.

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.

#### Forward Search

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.

### The Toolbar: a Reference Guide to Features

- New: begin a new document.

- Open: open a new document.

- Close: close your document.

- Define document as master: 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.

- Quickbuild: compiles your &latex; source code and displays the results automatically, unless you have code errors.

- Watch file mode: this mode will "watch" the DVI file for changes, and will not launch a new session of &kdvi; after Quickbuild.

- View logfile: views the .log file, so you can spot errors.

- Previous error: jumps backward through the .log file and highlights errors in source.

- Next error: jumps forward through .log file and highlights errors in source.

- Stop: halts current function.

- LaTeX: runs &latex; on the active document.

- View DVI: launches DVI viewer.

- DVI to PS: converts DVI file to a PostScript (PS).

- View PS: launches PostScript (PS) viewer.

- PDFLaTeX: creates PDF from &latex; source, if you have a &latex; header.

- View PDF: views PDF.

- DVI to PDF: converts a DVI to a PDF.

- PS to PDF: converts a PS to a PDF.

- LaTeX to HTML: creates HTML code from &latex; source.

- View HTML: views HTML created.

- Kdvi Forward Search: jump to page that corresponds to the current line in the editor.

If you look at the Edit 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:

- part: highest level of sectioning for a document.

- chapter: starts a new chapter.

- section: create a new section.

- subsection: create a new subsection.

- subsubsection: a secondary section between subsection and paragraph.

- paragraph: create a new paragraph.

- subparagraph: create a new subparagraph.

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

- label: a command that produces a label for a chapter, a figure or another element.

- index: creates an entry for the index.

- footnote: creates a footnote in your document.

- ref: used to refer to a predefined label, which you can choose from a drop-down list.

- pageref: just like ref, but refers to a page instead of a structure element.

- cite: create a reference with data from a bibliography.

The Label drop-down menu
The Label drop-down menu
Selecting the label for a reference
Selecting the label for a reference

When using cite, 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.

The last drop-down box labeled tiny 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:

- tiny: smallest.

- scriptsize: very small.

- footnotesize: smaller.

- small: small.

- normalsize: normal.

- large: large.

- Large: larger.

- LARGE: even larger.

- huge: still larger.

- Huge: largest.

## Quickstart

### Writing a &latex; Document with &kile; for Beginners

Users of &kile; have two choices when starting a new document: they can use the Wizard 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.

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

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

Typing in the code example above from the text box gives you the following output:

    		Here is a bunch of text coded in LaTeX.

The brackets that come after the command `\documentclass` contain the options for the command. The option `[12pt]` 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.

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 Build menu, or using the Quickbuild button.

Alt2 is the keyboard shortcut to compile your source code.

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

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

### Environments

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 `\begin{environment}`, `\huge` and `\end{environment}` will let you temporarily alter the text inside the environment commands to be size huge.

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

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 `\end` command, or at the end of your environment.

- `\begin{emph}` or `\begin{em}`: this command makes text italicised, and is valid until the code comes across a `\end{em}`, `\end{emph}` or another environment. To italicise one word in a sentence, you can use the syntax: this is `\em{my}` sentence.

- `\bfseries{I'm making this text inside the brackets bold}`: this command makes your text bold. The bold command will continue until a close brace is found.

- `\quote`: to create a quote inside your document; begin your quote with `\begin{quote}` and end it with `\end{quote}`.

- `\center`: centers the text.

- `\verse`: creates offset text for poems.

- `\itemize`: makes an itemised list.

### Using &kile;

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.

1. Start &kile;.

2. Create new document, using File New Empty Document.

3. Select Wizard Quick Start, then choose a format, and set your preferences in the wizard.

4. 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.

5. Save your file, and give it the name `intro.tex`.

6. Build your document using Alt 2, or the button labeled LaTeX.

7. Select View Dvi.

8. Check out all your new text.

9. When you are done viewing your document, click the Editor View 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.

That's it! You have just created your first &latex; document!

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!

### DVI Files

DVI stands for DeVice Independent 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.

#### Viewing a DVI

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

#### Printing a DVI

To print a DVI, you can use the same process that you used to create your document earlier (see ). At step 7, after clicking View DVI, select File Print in the viewer, and if you have your printer properly configured, you will be able to print the DVI.

#### Manually Printing a DVI from a console

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

#### Exporting a DVI

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.

### Forward and Inverse searches between &kile; and &kdvi;

#### Forward Search

The command Forward Search uses &kdvi; and an additional file (additional files are referred to as packages in &latex;) called `srcltx.sty`. You will have to do a search of your files to check if your distribution has `scrltx.sty` included. If it is not included, you may download it; copy it to a &tex; folder, for example `/usr/share/texmf/tex/latex/srcltx/`, and run ``texhash`` so that &latex; will know its whereabouts. Then you can set the following command in the preamble:

    		\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}

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

#### Inverse Search

Inverse search cannot work unless:

- `srcltx.sty` is in use.

- The source file has been compiled successfully.

- &kdvi; knows which editor you would like to use.

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 Settings DVI Options....

Configuring &kdvi;
Configuring &kdvi;

#### Resolving Errors

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.

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 Previous LaTeX Error and Next LaTeX Error 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.

## Starting a New Document

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:

- Empty document

- Letter

- Book

- Article

- Report

If you selected an Empty document, you can either start writing a document from scratch, or you can use the wizard to quickly start a new document (see ).

### Templates

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.

#### Create a New Template

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 File Create Template from Document.

#### Configuring Automatic Substitutions

When creating a new document by selecting a template from File New, 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 Settings Configure &kile;.

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

- `$$AUTHOR$$`: This string will be replaced by the author variable.

- `$$DOCUMENTCLASSOPTIONS$$`: This string will be replaced by the documentclass options variable. Typically this is used as follows: `\documentclass[$$DOCUMENTCLASSOPTIONS$$]{article}`.

- `$$INPUTENCODING$$`: If the inputencoding variable is set to, say, `latin1` this string is replaced by `\input[latin1]{inputenc}`.

#### Create a Template from the Wizard

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:

1. Save your file;

2. Go to File;

3. Choose Create Template from Document;

4. Make any corrections necessary to the template;

5. Enter a name for your new template;

6. Click OK to add your template to the menu.

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

#### Creating a Template from any File

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 .

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 Jonathan Marchini's home page, but many more are available. Remember that you will need the `a0poster` package, which is normally not in a standard &tetex; installation, so you will have to download it, copy it to a &tex; folder, for example `/usr/share/texmf/tex/latex/a0poster/`, and run ``texhash`` so that &latex; will know that is exists. Do not forget setting the file permissions so that everybody can read the file.

#### Removing a Template

To remove a template from &kile;, do as follows:

1. Go to Settings Remove template...;

2. A dialog box will appear with all templates listed: select a template;

3. Click OK, and your template will be removed.

Templates marked with an asterisk (*) cannot be removed without the proper permission.

## Editing &latex; Documents

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; Tools menu.

To learn more about &kate; and its capabilities, see the Kate Handbook. &kile; users can start reading from the chapter Working with the Kate Editor.

### The &latex; Reference

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

### Cursor Movements

To select text, you have the following options:

- Hold left mouse button, and drag mouse to highlight text.

- Click once on a word to move the cursor to a new area.

- Click twice on a word to select the whole word.

- Click three times to select the whole sentence.

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

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

### Bracket Completion and Matching

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 `\section{Introduction}`, you would see `\section{Introduction}` in the default yellow highlight, showing you the location of the beginning and ending brackets.

### Highlighting

&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.

### Automatic Environment Completion

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

Auto-completion can be turned off in the &latex; section of Settings Configure &kile;.

Completing an Equation Environment
Completing an Equation Environment

### Array Wizardry

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 Wizard menu. Other than the Quick Start option, it contains Tabular and Array (used in math environments). You will then have a matrix-formed input form that you can easily fill in with your entries. The Tabbing 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.

Inserting a tabular environment
Inserting a tabular environment

## Special Tags in &latex;

### Using the &latex; Tag Library

&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.

The Sidebar Menu
The Sidebar Menu

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

- Relational symbols

- Greek letters

- Arrows

- Delimiters

- Miscellaneous symbols

- Foreign characters

### Using Bibitems

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

The optional `[label]` 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.

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

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

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

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

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

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 Edit toolbar click on the second drop-down box (usually it reads label) and select cite. 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 Edit Refresh Structure.

The final product in your document's bybliography would then look like this:

`[1] Homer J. Simpson. Mmmmm...doughnuts. Evergreen Terrace Printing Co., Springfield, SomewhereUSA, 1998.`

The easiest way to work with `\bibitem` and `\cite` is to use the toolbar drop-down box marked cite. When you select a citation to insert, you will be given the list of `bibitem`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.

### User-Defined Tags

&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 `I prefer \LaTeX\ to \TeX\` and `What would I do without Linux?`. To create user-defined tags to write these sentences, he would access User User Tags Edit User Tags; this will present him a dialog where he can create his own user-defined tags.

The Edit User Tags Dialog
The Edit User Tags Dialog
Invoking a User-Defined Tag
Invoking a User Defined Tag

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 Menu item, and the text of frequently-used command should be entered into the section labelled Value. Once the commands are entered, he can use them quickly using the shortcut CtrlShift 1 for the first tag to enter `I prefer \LaTeX\ to \TeX\` and CtrlShift 2 to enter `What would I do without Linux?`.

#### Placeholders in User-Defined Tags

There are some placeholders you can use in user-defined tags: they are `%S`, `%M`, and `%C`.

- `%S`: will be replaced by the source file's name.

- `%M`: this stands for marked text; the selected text is inserted in its place when using user-defined tags.

- `%C`: this is where the cursor will be placed after using a user-defined tag.

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

## Using the Build Tools

### Compiling, converting and viewing

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

To compile your source code for screen viewers like &kdvi;, other DVI viewers or further conversion, you can use the shortcut Alt2. Then you can view the DVI file using your default viewer with Alt3, convert the DVI to a PS file with Alt4, and view the PS file with Alt5.

#### &bibtex;

If you are using &bibtex; for your bibliography entries, you will have to follow a special compiling scheme.

1. Run &latex; with Alt2.

2. Run &bibtex; with Alt-: this will compile the bybliography file.

3. Run twice &latex; again, to incorporate the compiled bybliography information, and to get citations and cross-referencing right.

You may also view the &bibtex; file with your &bibtex; editor of choice (for example &gbib;) by choosing Build View View Bibtex; you can change the default &bibtex; viewer at Tools Configure Kile...Tools.

#### MakeIndex

If you are using the &makeidx; package to make a final, alphabetical index for your document, you have also to follow a certain compilation pattern.

1. Run &latex; with Alt2.

2. Make index with Alt=: this will compile the index file.

3. Run &latex; again, to incorporate the compiled index information.

#### MetaPost

If you want to compile your document with MetaPost, a picture drawing program, you can do it with Build Compile Mpost.

#### PDF&latex;

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 Alt6: you can then view the compiled file pressing Alt7.

Alternatively, you can convert a PS into a PDF with Alt8, or directly a DVI into a PDF with Alt9.

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.

#### &latex;2HTML

Finally, you may want to publish your work on the web and not just on paper. You may then use the latex2html program, that can be called from &kile;'s menu Build Convert LaTeX to HTML. 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 Build View View HTML.

#### Passing Command-Line Parameters

If you want to pass some specific command-line parameters to the compile, convert or view tools, you can configure their call in Settings Configure Kile...Tools.

### Graphic File Formats

PDF&latex;, when used with `graphics` or `graphicx` 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:

- You can convert EPS files to PNG or other formats with utilities as the Gimp, and use PDF&latex;.

- 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 highly 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 jpg2ps.

- 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 pdftops, or, better yet, implement your own user tag to do that for you (see ).

Use the right file for the right graphic!

- 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.

- PNG (or the deprecated GIF) is a non-lossy 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.

- JPG is a lossy 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.

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

### Master Document

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 Settings menu, all the commands of the Tools menu will apply only to this document, even when you are working on the child documents. You can even close the Master document.

### Error Handling

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 Build View Log File, or by using the keyboard shortcut Alt0. The generated log is then displayed in the Log / Messages view; errors and warnings are highlighted.

Viewing the log
Viewing the log

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

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.

### Using the Watch File Mode

When you launch the Quickbuild 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.

If you are adjusting the look of your document, you might launch Quickbuild very often, and have many viewer windows open on your desktop; to avoid this confusion, you can activate the Watch file mode, that will prevent Quickbuild from launching a viewer.

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.

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.

## Navigating the &latex; Source

### Using the Structure View

The Structure 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.

If you included a separate &latex; file in your source using the `\input` or `\include` tags, these files will be referred to in the Structure view; double-clicking on their names in it will make &kile; bring up the included file in the editor window.

The hierarchy tree has also a separate branch for labels used in the text.

Using the Structure View
Using the Structure View

#### Updating the Structure View

To update your structure view you can either go to Edit Refresh Structure, or you can save your document, which will make &kile; update its Structure view.

### Bookmarks

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 Ctrl B, 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 Bookmark Toggle Bookmark.

To remove all your bookmarks, select Bookmarks Clear Bookmarks.

## Projects

### Working with Projects

In &kile; you can create and work with projects. 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 `.tex` 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.

A Project adds the following functionalities:

- You need not set a master document, &kile; does this automatically.

- Project files can easily be archived together.

- The Files and Project view shows which files are included in the project.

- After opening a project, any file that was previously opened will be restored with the original encoding and highlighting.

### Creating a Project

To create a project, select Project New Project.... You will be asked to give the following information to create your project:

- Title of your project.

- Name of the project file with .kilepr extension.

- Filename.

- Type of file creating: Empty Document, Article, Book, Letter, Report.

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

### Using the File and Project View

The File and Project 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 File and Projects view.

The File and Project View
The File and Project View

### Adding and Removing Files

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

If you have multiple files to be added to a project, you can select the project from the Files and Project view and right-click then select Add Files; you will then be able to select your files in a dialog box.

You can also right-click on the project's name in the Files and Project view, and select Add Files... to bring up a file selection dialog.

Adding a file to a project
Adding a file to a project

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

### Changing your Project's Options

&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 Project Options, and you will have the option of changing:

- The title of your project.

- The archive command.

- Recognised extensions for non-source files.

- The option to use file extensions as regular expressions.

#### Archiving your Project

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

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 Files and Project view, and uncheck the Include in Archive option.

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:

- `%S`: this is replaced by the name of your project file without the .kilepr extension.

- `%F`: this command is used to replace the list of files to be included in the archive.

#### Extensions for Non-Source Files

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.

### Closing a Project

To close a project, select the Files and Project view from the vertical toolbar, right click on your project title, and then select Close. 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 Open Recent Project... in the Project menu.

## Setting the Document's Encoding

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:

- One way to set the encoding is to use the Set encoding combo box, located at the bottom of the Open File sidebar view.

- Another way is using the submenu View Set Encoding.

- 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.

&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 `\"e` for `ë`. There is a package to help you with this, called inputenc, and is included in the preamble using `\usepackage[latin1]{inputenc}`, where the optional argument is the encoding you would like to use (in most cases `latin1`). This tells &latex; to translate all of the `ë`'s you wrote to `\"e`'s before compiling. Please refer to the inputenc documents directly for more information on inputenc. Last but not least: remember to make sure that your file is actually encoded in the same encoding you told inputenc!

Choosing the source file's encoding
Choosing the source file's encoding

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 Unicode. There are many implementations of Unicode, and utf-8 is the most successful in Linux; Windows® relies instead on the more cumbersome and less flexible ucs-2. Some distributions, as RedHat, have already begun setting their default encoding to utf-8, and therefore you may be very interested in using a `utf-8` argument to the `inputenc` package.

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

### The &ucs; Package

You can get the &ucs; package from the home page of Unicode support for &latex;, by Dominique Unruh from the university of Karlsruhe.

To install it, unpack the downloaded file and move the uncompressed contents to a directory that &tex; can see; you could for instance use `/usr/share/texmf/tex/latex/ucs/` (make sure this is actually your $`TEXMF` 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 `chmod`. You have to perform all these actions as root, so be careful.

When you have finished, launch the `texhash` 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:

    		\usepackage{ucs}
    		\usepackage[utf8x]{inputenc}

### Chinese, Japanese and Korean (&cjk;) Support

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.

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!

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 Pai H. Chou's page about how to setup PDF&latex;.

1. Download the &cjk; package. Copy its unpacked files to an appropriate subfolder of $`TEXMF`, just like you did with the &ucs; package before (see ). The files will be unpacked in a `CJK/X_Y.Z` directory, it is not important that you take them out, though it will probably be tidier for you to maintain.

2. Now you have to download a font that supports all the &cjk; characters you need. You can choose any `*.ttf` file that covers them, but in this walkthrough we will use Cyberbit. Unzip the file and rename `Cyberbit.ttf` to `cyberbit.ttf`, since uppercase might confuse your system.

   Place `cyberbit.ttf` in a folder together with `Unicode.sfd`, and generate the `*.tfm` and `*.enc` files with the command `$ ttf2tfm cyberbit.ttf -w cyberbit@Unicode@`. For some reasons, sometimes this does not produce the hundreds of files it should. Should that be your case, you can download both `*.tfm` and `*.enc` files.

   Place the `*.tfm` files in an appropriate folder, say `$TEXMF/fonts/tfm/bitstream/cyberbit/`; the `*.enc` files may be installed in `$TEXMF/pdftex/enc/cyberbit/`.

3. Now we need a map file to connect the `*.enc` files to the font. Download `cyberbit.map` and install it in `$TEXMF/pdftex/config/`.

4. Download another file, `c70cyberbit.fd`, and place it in an appropriate folder. You may choose, for example, `$TEXMF/tex/misc/`.

5. The last file we have to generate is a PostScript Type 1 font, necessary to read DVI files generated with &latex;. Run the command `$ ttf2pfb cyberbit.ttf -o cyberbit.pfb`, and copy the resulting `cyberbit.pfb` in a folder like `$TEXMF/fonts/type1/cyberbit/`.

6. Let's now place `cyberbit.ttf` among the fonts where &latex; can find it. You could place it in a folder named `$TEXMF/fonts/truetype/`.

7. Check the configuration file you find at `$TEXMF/web2c/texmf.cnf`, and make sure that the line mentioning `TTFONTS` is uncommented and points to the folder where you saved `cyberbit.ttf`.

8. To make it possible for PDF&latex; to use your &cjk; fonts, it is necessary that you add a line in configuration file `$TEXMF/pdftex/config/pdftex.cfg`. Add `map +cyberbit.map` in the file to complete the configuration for PDF&latex;.

9. To configure &latex; so that you can produce DVI files with &cjk; characters, you have to add a line in file `ttfonts.map`. The file might be in a directory named `$TEXMF/ttf2pk/`, but you will probably have to look for it. Add the line `cyberbit@Unicode@ cyberbit.ttf` into it.

10. Now, you only have to run `texhash` and the system should be ready.

To test whether your configuration is correct, you can try to compile this test file.

#### &cjk; Troubleshooting

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.

- Obviously, since you run &latex; as a user and not as root, you must allow ordinary users to access the new files. Make sure all folders and files are accessible using the `chmod` command.

- 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 `*.pk` 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 `ttfonts.map` for your custom line first. However, it might happen that your `ttf2pk` command, which is usually invoked by the DVI viewer, has been compiled without support for the kpathsea libraries. If this is the case, `$ ttf2pk --version` will make no mention of kpathsea. As support for these libraries is necessary, you might have to find a new package, or recompile FreeType 1 by yourself.

#### How do I input &cjk; in Unicode?

There are a number of different input engines, and the choice can depend also on personal preference. The author uses Skim, a port to &kde; of the Scim 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 Skim you will have to define an environment variable `XMODIFIERS="@im=SCIM"` before starting X.

## Credits and License

&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.

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 GNU license. Here is a short list of the programmers, editors, translators, writers, debuggers, packagers, web developers and users who made this project possible.

Program copyright 2003 and currently maintained by Jeroen Wijnhout Jeroen.Wijnhout@kdemail.net

Program copyright 2002-2003 Pascal Brachet

&kile; contains source code from the free (GPL) program Xgfe (X Windows GUI front end to &gnuplot;), Copyright © 1998 David Ishee

Documentation Copyright © 2003 Jonathan Pechta, 2003-2005 Federico Zenith

Contributions from: Rob Lensen, Roland Schulz, Michael Margraf

Many thanks to all those involved!

&underFDL; &underGPL;

&documentation.index;