# The &kile; Handbook

Jonathan
Pechta

    jrpechta@yahoo.com

Jeroen
Wijnhout

    Jeroen.Wijnhout@kdemail.net

2003
Jonathan Pechta
2003-10-23
1.6
&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 Linux distribution:

- K Desktop environment (KDE): KDE is a popular open-source desktop environment

- Qt: Qt is an C++ development tool needed to compile Kile

- LaTeX: High-quality document typesetting program

Recommended Package

- KDVI: DVI preview for KDE

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

The Kile project includes several different packages of Kile that can be easily installed and run without having to compile.

Suggested system requirements

- Pentium-compatible or faster processor

- 128MB RAM

- 400 MB to 4 GB hard disk space depending on number of programs installed

- Mouse and keyboard

### About this document - Important

Portions of this manual will be marked by a boxed exclamation point and italicized text. These items contain cautions, warnings or notes that a reader new to Kile should give special attention; these sections can be skipped by advanced users, but will sometimes contain further information about LaTeX or programming in LaTeX that an advanced user might consider helpful.

Commands will NEVER be italicized, even in noted sections marked with an exclamation point graphic. This is to try and make commands obvious to the user and to emphasize to a new user that all command are preceded with a backslash similar to the following example:

> to begin a quote in LaTeX, the command always used to begin a quote is \begin{quote}, and when I want to end my quote I use the command \end{quote} with the text for my quote between the two commands.

### Intended audience

This manual can be used by any individual regardless of their experience with LaTeX, KDE, Kile or Linux. New users who do not want to read this manual, but dive right into using LaTeX, should consult Appendix E. Appendix E contains a brief walkthrough on how to get started with LaTeX and contains sample code and exercises, that will let the user begin using Kile immediately.

Users who are interested in learning more about Kile, and how Kile can streamline your LaTeX documentation efforts should read this manual from start to finish.

Advanced users are not likely to read this manual, but all suggestions on documentation will be regarded. If you would like to contribute to this project or the documentation please consult the Kile web page at: http://kile.sourceforge.net/ Comments about documentation can be delivered to jrpechta@yahoo.com.

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.

### What's new in Kile?

The current version of Kile is 1.6. Here are some of the more significant changes and features that have been implemented since the last version of Kile (version 1.5).

New features:

- Project management

- New, more powerful internal editor (katepart)

- All standard tools are configurable

- Files and projects restored on start-up

- Improved syntax highlighting:

  - Incorporates verbatim environments

  - Highlighting inside math environments

- Insert citations from BibTeX biblographt using gBib or pyBliographer

- Word count

- User configurable standard tools

- User configurable tags

Bug fixes:

Minor fixes throughout program

### License Agreement

If you use Kile, you agree to be bound by the GNU General Public License Agreement. Details of the GNU General Public License Agreement can be found at the following web page: http://www.gnu.org/copyleft/gpl.html.

Please read for more information.

## Introduction

### About Kile

Kile is an integrated LaTeX environment for the KDE desktop. Kile allows the author the ability to utilize all the functionality of LaTeX in a graphical shell, simplifying the amount of work an author has to do to edit LaTeX source code. The software shortens the work it would take an author to create a high quality piece of documentation and gives the user many different formats (Postscript, PDF, HTML, etc.) to publish their text.

### What is LaTeX

LaTeX is a text-processing system derived from Tex, a program developed originally in 1977, for authors or those in printing to help them layout their work professionally, similar to the job function of a typesetter. A typesetter is a person who keys in text to be printed and styles it according to specifications for the document is primarily concerned with the look and visual quality of the work. An author writing the document is not only concerned with the look of the document, but in the end is responsible for all facets of the work, including the look and the content. LaTeX was created to bridge the gap between the author and the typesetter, to give the creator the ability to compose complex documents, but also use the professional layout and the high quality typography offered by Tex.

### LaTeX basics

The LaTeX typesetting system is similar to Extensible Markup language (XML) or Hypertext Markup Language (HTML). Don't let these big terms scare you away. All markup languages consist of symbols, which are used to give instructions, or describe how information is to be displayed. A Kile user does not need to know HTML or XML to use LaTeX, this is just an example.

This similarity to HTML and XML makes the LaTeX not only very flexible, but offers the advanced user the ability to compose personalized functions. It also gives users who are familiar with HTML the ability to see the similarities to the way coding for LaTeX and HTML are laid out.

Creating web pages in HTML gives the user some experience similar to LaTeX because HTML has the advantage of breaking up sections using tags like HTML, head, and body to point the user where certain information in to be located. LaTeX has a similar style, because EVERY LaTeX file must contain a preamble and body.

Preamble: A series of commands that setup the document with global command such as paper size, page numbering, dimensions of the text on the page. The command \documentclass is the only required preamble, but must be there to form a document.

Body: Any additional command that comes after \begin{document}. These commands are considered local and will end with the end of the body of the document, which is concluded by \end{document}

### Kile's main features

#### Document wizard

The wizard built into Kile is a unique feature to get a user started creating documents right away in Kile. Choosing the wizard from the taskbar gives you several choices for the creation of your document. (Insert 3 figures in this general area, a location of wizard in toolbar, close-up of wizard, and segment of code generated by wizard). This lets a user quickly specify the type of document they would like to produce, whether that is an article, a book, letter or report and set options relating to the document. The author has the ability in this section to let Kile quickly generate LaTeX code based upon the settings you have defined in the wizard.

Wizard options:

- Document Class; what kind of document are you creating? Letter, report, book?

- Typeface Size; what point size are you using?

- Paper Size; What size or style of paper will you be exporting your document?

- Encoding; Encoding is used to automatically set packages relating to the encoding (but we will get into explaining packages later)

- Author's Name; put your name here

- Title of Document; add your document title here

- Other options; this allows you to set other options for printing, draft, etc.

#### Predefined templates

Any Kile user who is continuously writing the same type of document can take advantage of using templates in Kile. The predefined templates in Kile are:

- Empty document : a blank template

- Article : sets format for an article

- Book : this template sets pages up a format for book specific document such as a page numbering scheme with page number on outside edges of paper

- Letter : sets format for a letter with address and receipt settings

- Report : sets format for a report

New users need not worry, these sections are just a brief description of features and more attention will be paid to completing these tasks in detail in later in the Quickstart section.

#### Syntax Highlighting

Kile is similar to programs that deal with source code and editing and will automatically highlight commands, options and items that are misused. Just like your word processor that highlights or underlines problem areas of your document, Kile has a similar feature for the LaTeX, HTML, C, C++, SQL and many other languages. It will highlight areas that it believes are problems as a warning to a user that segments of text need to be addressed.

#### Auto-completion of environments

New to this version of Kile is the auto-completion of environments, this means that when a user begins a new environment by typing for example: \begin{environment} Kile will automatically add a \end{environment} command, with a line in between for your text.

#### Jump to sections

Sections are commands that allow a user to produce a division similar to those found in books or outlines and allow the author to create a hierarchy for their documentation. Kile allows users to break up documents into the following hierarchy (part being the highest in the hierarchy and subparagraph being the lowest)

- \parts

- \chapter

- \section

- \subsection

- \subsubsection

- \paragraph

- \subparagraph

When viewing a document in the structure view, the user can jump between sections by clicking on the section they would like to view.

#### Inverse search

When creating your own LaTeX file, inverse search can be very helpful. Once a user has created a DVI file (Device Independent File). When the user clicks the middle- mouse button in the DVI viewer, Kile will jump to the corresponding line in the LaTeX source code.

Definition of DVI: 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/LaTeX. A number of utilties 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 a user 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 include other .tex files in your document.

- Quickbuild : Compiles your LaTeX source code and displays results. automatically, unless you have code errors.

- Watch file mode : This mode will "watch" the DVI file for changes and automatically update this file without having to re-launch KDVI

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

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

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

- Stop : stops current function.

- LaTeX : runs LaTeX on the active document.

- View DVI : launches DVI viewe.r

- 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 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 upper right hand end of the toolbar, you will notice three large drop- down boxes. The drop-down boxes were designed for the user to be able to quickly add insert features into their document. The first drop-down box (insert figure of part drop- down box) is used for quickly dividing your document by parts, chapter, sections etc. 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 coming between section and paragraph.

- Paragraph : create a new paragraph.

- Subparagraph : create a new subparagraph.

The drop-down box entitled label is used to insert items to your document such as indexes, footnotes, references. Available commands to add items to your LaTeX source code are:

- Label : command that produces a label for a level.

- Index : creates an entry for the index with a file suffix .idx.

- Footnote : creates a footnote in your document.

- Reference : used to refer to a predefined label, which the user chooses from a drop down list.

- Page reference : creates a page number in your document that corresponds to a label.

- Cite : create a citation in your document from a list of bibitems.

When using cite, the user is presented with a drop-down list of bibitems, but if the user is using BibTeX this won't work. Users will have to use gBib or pyBliographer.

The last drop-down box labeled tiny is used to set the size of your text. The user has the option of setting the size of the text, footnotes etc. Available commands to add a text size to your LaTeX source code 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 document with Kile for beginners

Any user of Kile has two choices when wanting to start a new document. They can either use to wizard to begin a new document, selecting the type of document they would like to create and the options such as font size, paper size, etc. The other option a user has is to write 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 2e, which uses `\documentclass` to being a document. This 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 denotes an option 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, don't worry, 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 a user to compile LaTeX is to use the build menu or using the quickbuild button.

Alt-2 is the keyboard shortcut to compile your source code.

You will need to save your source code before you can compile, but Kile will warn you of this.

If your document didn't compile, check the log for errors. When using the quickbuild key, the KDVI viewer should launch automatically, if it does not, check the log for errors.

Now, change the text of your document, change the punctuation from a period to an exclamation point, then save and run the LaTeX command again followed by the name of the file.

If you don't save your file, when you try and view it, you will get your previous version of text for your output because your document hasn't been saved or recompiled; this will then update the DVI viewer.

### Environments

An environment is a command that lets you manage a segment of text differently than you set the variables for the rest of your 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 the

size HUGE.

So, changes are only effective from /begin{environment} blah blah blah change change change \end{environment}. There are no limits as to how make 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. Features such as fonts, bold, italics, underline etc. are features you can add to your document and the commands that will make your document look wonderful, but will end with either an `\end` command or the end of your environment.

- `\begin{emph`} or `\begin{em}` : This command makes text italicized and this command is valid until the code comes across a \end{em}, `\end{emph}` or environment. To italicize one word in a sentence, you use the syntax: This is`\em{my}` sentence; which gives you the output, This is my sentence.

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

- `\qoute` : To create a quote inside your document, begin your quote with `\begin{quote}` and end with `\end{quote}`.

- `\center`: Centers the text.

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

- `\itemize` : Makes an itemized list.

### Using Kile

Now that we have given you some background as to how to write code using the LaTeX mark-up language, we will show you how to create a document step-by-step using Kile.

1. Start Kile.

2. Create new document, using File, then new, then select 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, one bold, 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 done viewing your document, click the Editor View button to return to the editor.

That's it! You have just created your first LaTeX document. To be able to alter the file further, go to View => Editor view and you will be returned to the source code editor.

If you build your document and don't see any text, make sure you adjust your viewer in the upper left section of the screen. When compiling your source, Quickbuild will center your text in the middle of the screen, but using LaTeX to build and then View DVI will not automatically center your text on the screen.

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 would like. Experiment and have fun!

### DVI file

A DVI stands for device independent file. These files are produced by Tex or LaTeX to be read by a driver on your computer. There are many different types of output that a .DVI can take such as a printer, PDF, postscript, 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 (if you can't remember refer to ). At step 7, instead of clicking view DVI, select print from the toolbar and if you have your printer configured to print properly on your computer, the DVI should export and print immediately.

#### Manually print a DVI

To print a DVI manually from the Konsole, use the command DVI to PS from the toolbar or type `dvips intro.dvi`. The command (if you have dvips installed) will convert your DVI into a postscript file. Once your file is converted, you can then print it using the print button and selecting you intro.ps file, or by typing `lp intro.ps`. All files should be in the same directory where you installed Kile.

#### Exporting a DVI

The toolbar gives the options of exporting a DVI to different formats. Once you have created a DVI from your LaTeX source code you should be able to export it to the format of you choosing using the toolbar buttons.

### Forward search

The command forward search uses KDVI and an outside file (outside 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 included. If it is included, then you must set the following command in the preamble.

`\documentstyle[14pt,a4paper]{book} \usepackage[active]{scrltx} \pagestyle{empty} \renewcommand{\baselinestretch}{2} \begin{document} \begin{verse} The KDE \LaTeX\ source code editor Kile is my favorite. \em{because} it is easy to use! \end{verse} \end{document}`

Once you have added the package scrltx, you can leave KDVI open. Forward search will allow a user to click on a specific section of text in the LaTeX code, and jump to the associated position in the DVI viewer window.

### Inverse search

Inverse search can not work unless:

- Forward search is enabled and working.

- The source file must have been compiled.

- KDVI must know which editor you would like to use (see ).

To use forward search, save and compile your LaTeX source and open the DVI viewer by using the DVI Viewer button in the toolbar.

Once the DVI viewer is open, click with your middle button on a segment of text and you should be directed back to the editor, to the section of source code you middle clicked from the DVI viewer.

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. For this to work, the tex document must be already compiled, and the KDVI Forward Search must be working.

### DVI preferences and settings

To make Kile your default editor in KDVI, enter the following command in the shell command line area:

`"kile %f --line %l" (this is %L, but lowercase)`

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 error" and "next error" to jump to and from errors. The log file always states which line the error occurred. To view the line where an error occurred, click on the error and Kile will take you to the line corresponding to the error.

## 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. Your default choices are:

- Empty document

- Letter

- Book

- Article

- Report

If you selected an Empty document, you can either start with 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 every document they use. Usually they fine-tuned the preamble to their likings. When starting a new document it is convenient if Kile would start with this user-defined LaTeX document right away. Templates allow you to accomplish this.

### Create a new template

To create a new template, you must first either open a Tex/LaTeX file, or start a file of your own. Any Kile user who is continuously writing the same type of document can take advantage of using Kile to create templates of their own. Kile can generate a template from an existing document by open the desired document and selecting File Create Template from Document.

#### Configuring automatic substitutions

When create 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. Modify the Template Variables to your wishes.

If you are designing your own template it is useful to known which characters 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

To start a customized template of own, the easiest way to create a new template is to start a wizard, then add commands to the editor on the right. Once you have your document set up how you would like:

1. Save your file

2. Go to Settings

3. Choose Create template from document

4. Make any corrections necessary to 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 from your customized template instead of the standard letter, report, book, etc.

#### Creating a template from any file

A template can be created from any 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 .

### Removing a template

To remove a template from Kile, go to:

- Settings => Remove template

- A dialog box will appear with all templates listed

- Select a template

- Click Remove, and your template will be removed

- Templates marked with a * can not be removed without the proper permission

## Editing LaTeX documents

The internal editor 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.

To learn more about Kate and it's capabilities you can reference the Kate Handbook here. Kile users can start reading from the Working with the Kate editor chapter.

### Cursor movement

If the user would like to select text they have the following options:

- Hold left mouse button and drag mouse to highlight text

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

- Click twice on a word selects the whole word

- Click three time selects 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 a user to select portions of the source code in the editor window.

### Bracket completion and bracket matching

Bracket completion is a visual tool that the editor view uses to alert to user to brackets that match each other. If you open any .tex extension file and select any bracket, whether it be a (), [] or {} the bracket selected will highlight its matching bracket in yellow (default color, but can be changed). So, an example would be if a user clicked the open bracket in the example \section{Introduction}, they would see \section{Introduction} in the default yellow highlight telling them 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, making it easy for the user to read normal text. Also formulas are highlighted in a different color.

### Automatic environment completion

New to this version of Kile is the auto-completion of environments, this means that when a user begins a new environment by typing for example: \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.

## Using the LaTeX tag library

LaTeX has hundreds of tags that can be inserted to represent symbols and special characters. The easiest way to insert a specialized character is to use to menu between the file viewer and the source code 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 categories of characters:

- Relational symbols

- Greek Letters

- Arrows

- Delimiters

- Miscellaneous symbols

- Foreign characters

### Using bibitems

`\bibite`m is a command used to enter a reference in your document to a bibliography item. The syntax for using the command \bibitem is `\bibitem[label]{key}`.

The optional `[label]` is for the user to add their own labeling 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 command `\bibitem` and `\cite` to each other and the information they contain. The command `\cite` contains the information about the source such as author, publisher, etc. whereas the `\bibitem` command contains the physical location of the bibliography within the text itself . Both corresponding `\bibitem` and `\cite` must have the same `{key}`, the easiest way to organize keys is by author's last name. The secondary `{}` in `{thebibliography}` denotes the maximum number of bibliography items you can have. So, having {99} bibitems means I can have between 0 and 99 bibitems since the bibitem must contain two-digit numbers.

The bibliography is a separate file from your main source code, and an example of code for the bibliography would look like the following:

`\begin{thebibliography}{50} \bibitem{Simpson} Homer J. Simpson. \texts]{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}.`

The final product in my document would then look like this:

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

The easiest way to work with bibitem and cite is to use the toolbar option drop-down box marked label. When you select a citation to insert, you will be given the list of bibitems you have created so far and will be able to select the reference from the list. Kile can now work together with BibTeX editor applications such as gBib and pyBliographer to help make citations easier for the user.

### User defined tags

Kile gives the user the ability to make tags for their document. A tag is similar to a shortcut, where the user can create their own commands or text they use often in their document and access that tag using the keys Ctrl-Shift-1. For example, when writing I often use the phrases "I prefer LaTeX to TeX" in my text and "What would I do without Linux?" To create these as user defined tags I would:

- Select User from the menu

- Select User Tags

- Select Edit User Tags

This will give me a dialog where I can create my own user defined tags.

The edit user tag dialog.
The edit user tag dialog.
Invoking a user defined tag.
Invoking a user defined tag.

To create my two user defined tags I use often when writing I would give each a name that can clearly identify them. The name you give your tag gets entered in the section marked "Menu Item" and the text of command I use often would get entered into the section labeled "Value". Once I have them both entered, I can use them quickly in my text by using the shortcut Ctrl-Shift-1 for my first tag to enter "I prefer LaTeX to TeX" and Ctrl-Shift-2 to enter "What would I do without Linux?"

#### Unique characters in User defined tags

There are several unique characters in Kile, these characters have unique meaning in user defined tags and they are %, %S, %M, %C and %env.

- % : A character used to comment your source code

- %S : Replaces the source file name

- %M : This stands for marked text; where the selected text is inserted 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 I have a user defined tag, which contains the value \bfseries{%M}{%C} and I have a selection of text highlighted in my document that I want to turn into bold text. So, I highlight the phrase "I love Friday", apply my user defined tag by pressing Ctrl-Shift-1 and I get the phrase "I love Friday" with the cursor is placed at the end of the phrase.

## Using the build tools

### Compile LaTex, PDFLaTeX

To convert your document to another format you need to first need to compile the source from your LaTeX environment.

To compile your source code for the screen through KDVI, another DVI viewer or conversion to postscript (PS) you want to use the shortcut key Alt-2 or Tools =>LaTeX from the menu. This compiles the source for these different formats and then you have the options to:

- View DVI (this will use your default viewer); Alt-3

- Convert the DVI to PS; Alt-4

- View the PS file; Alt-5

There are several ways to compile your document. For example, if you would like to compile your document and turn it into a PDF, you need to run PDFLaTeX that compiles your source, which then you can convert to a PDF file. This is done by using the shortcut key Alt-6 or selecting Tools from the menubar and select PDFLaTeX from the menu. This process of using Tools => LaTeX, builds your document so your viewer, or other formats can read the information.

- View PDF; Alt-7

- PS to PDF; Alt-8

- DVI to PDF; Alt-9

#### Passing command-line parameters

Perhaps you want to give some special command line parameters to the tools to compile or convert your files. The standard tools can be configured in Settings Configure Kile.

### Master document

To define your document as a master allows a user to work with separated files, which gives you a parent document (or Master document) and child document that make up a complete work. After having defined your "Master" document, with the corresponding command in the Options menu, all the commands of the Tools menu will apply only to this document even when you are working on the "children" documents. You can even close the Master document.

### Advanced error handling

After you have run LaTeX, Kile takes a look at the error messages LaTeX generated. If there are any errors or warnings, this will be reported in the Log/Messages window. One can take a closer look at the messages by selecting Build View Log, or by using the keyboard shortcut Alt-0. The log LaTeX generated is then displayed in the Log/Messages view, errors and warnings are highlighted.

Viewing the log...
Viewing the log...

One 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 occurred, simply click on the error/warning in the Log/Messages view. Kile will take you automatically to the offending line.

### Viewing your document

To view your document once you have compiled the source using LaTex or Alt-2, you can view the document using the DVI viewer. To view the document in your default DVI viewer use the View DVI button in the toolbar or Alt-3.

### Using Watch File

1. Launch the Quickbuild command.

2. Leave KDVI open and select the Watch File mode for this program.

3. Select the Watch File in the Tools menu in Kile.

Each time you launch the Quickbuild command, the "DVI" document will be automatically updated, without KDVI being started again.

This mode also works with KGhostView, but will not work with the embedded viewers.

### Converting your document

Once you have compiled your LaTeX source from the editor, you can then convert into a format that fits you best.

#### Standard conversions (dvips, pspdf, dvipdf, etc.)

Selecting the conversion tools from the menu or by using the shortcuts lets a user convert the document into a different form. Standard conversions are:

- DVI

- PS

- HTML

Note that pdflatex convert your document directly into a PDF.

## Navigating the LaTeX source

### Using structure view

The structure view shows the hierarchy of the document being created in Kile and allows the user to quickly navigate the document and shows segmentation of the document. To navigate around your document all a user needs 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.

#### Click on labels, sections

When using the structure view, you can easily jump between labels, sections, and subsections by clicking on the item in the structure view and you will be taken to that section in the editor view. Sections and subsections are clearly marked with special characters that make them easy to identify.

Using the structure view.
Using the structure view.

#### Double click on input, include

If you include a file into your LaTeX document using the `\input` or `\include` tags, the structure view will contain an item representing this file. Double-clicking on the file name will cause Kile to display this included file.

#### Update structure

To update your structure view you can go to Edit Refresh Structure and this will refresh your structure view.

After you save your document, Kile will automatically update the structure view.

### Bookmarks

Bookmarks are a user's reference to a segment of text or a line inside the Kile environment. To use a bookmark, a user can select a specific line of their document they would like to return to, then press Ctrl-B and Kile will automatically add a bookmark to this line. Optionally, the user can also set a bookmark by highlighting the line they would like to return to and choose the menu item labeled Bookmark.

To remove your bookmarks, select Clear Bookmarks from the menu item.

## Working with projects

When working in Kile the user has the ability to create and work with project files. A project is a grouping of LaTeX or TeX documents that manage all information related to your document. A typical example of a user using a project would be if the user had a document that had several chapters, they could then create a project, so each individual chapter in its own separate file making the project easier to manage. Other examples of when a user would use a project file would be to store non-source files such a graphic. The project data is then stored in a special file with the extension .kilepr.

A Project adds the following functionality:

1. A user need not set a master document, Kile does this automatically

2. Project files can be archived

3. The Files and Projects view shows the relationship between files in the hierarchy of your document

4. 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, click the new project button in the toolbar. 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 doc, book, report, article, letter

When creating a new project the project file box is a prompt for the user to give a name for your project with the extension .kilepr. When you fill out the section entitled filename you must include a relative path for your documents. An example of a relative path a user might use in the filename section would be /usr/HomerJ/myproject.kilepr. Make sure you include the extension .kilepr.

A new installation of Kile might not have the buttons for creating, opening, closing or project options in the toolbar. You can add these if they are not included by going to Settings, then Configure Toolbars.

### Using the Files and Project view

The Files and Project view, is a button listed vertically that looks like two pieces of paper. From this view, you can visually see the structure of your project, the files in your project 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 project and files view.
The project and files view.

### Adding and removing files

To add a file to your project, open any TeX file and in the project view you can right-click on the TeX file and select, "Add to Project". If you have multiple projects open, you will choose the project to add the file to in a dialog box.

Or, if you have multiple files that need to be added to a project, you can select the project from the Files and Project view and right-click then select "Add Files". This gives the user the option of adding multiple files at once.

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

To remove a file from a project just right click on a file and select "Remove File" and your file will be removed from the project. This does not delete your file, but just removes the file from the list of files contained in the .kilepr extension. You will still be able to access the file later to make changes or to re-add it to a project if needed.

### Changing your project options

Kile only has a few options that can be set related to your project. To change your project options, 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

- Archive commands

- Extensions for non-source files

- And set the option to use files as regular expressions or not

#### Archiving your project

Kile allows you to easily backup your project by archiving all the projects files into a single archive. To archive your project right-click on the project name in the Files and Projects 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 this file in the Files and Projects view and uncheck the "Include in archive" option.

Archive commands are shell commands that are executed from the project directory (where the .kilepr file is located). Special commands when using archive:

- %S : This used to replace the filename of your project file (without the .kilepr extension)

- %F : This command is used to replace the list of files needed to be included in the archive

#### Extensions for non-source files

Non-source files are files such as pictures, PDF files, postscript, etc. that specify which files are to be considered as included in the project, but aren't source files such as files with the extension .tex. For example, a PDF file is a non-source file because you can create a PDF from a file with a .tex extension. Users also have the option to use their 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 and right click on your project title, then select close. This will close your project, all the files associated with your project and also add the name of the project you just closed to the Open Recent Project drop-down box toolbar (if you have it on your toolbar, because it isn't a default toolbar option you need to add it using Settings, Configure Toolbars).

## Preparing a document in an alternate language

One of the powerful advantages of using Kile is the ability to read, convert and set the text to the encoding your document needs. This will allow your document the option of using non-standard letters and symbols. This is very handy because you can setting the encoding which allows the user to type and display specialized characters. An example of this would be if a user need to display or use the capabilities of their keyboard to type in Italian, they would set the encoding and be able to insert and display letters with accents on them. Selecting the encoding for your document can be done in two ways.

One way to set the encoding is to use the encoding menu drop-down box located at the bottom of the file view.

A second way to set the encoding for a document is to set the option when you use the wizard to create a new document.

There is also separate encoding for the LaTeX typesetting system. Traditionally, LaTeX only understands a very limited set of characters, so a user doesn't have the ability to use accented letters directly. To use accented letters, LaTeX created some syntax to be able to include an accented letter, which is \"e. There is a package to help users with this called inputenc and is included in the preamble using \usepackage[latin1]{inputenc}, where the option argument is the encoding you would like to use. This tells LaTeX to translate all of the \"e's in your document to ë. Please consult the inputenc documents for more information on inputenc.

Ideally you would use a LaTeX version that understand UNICODE, however this is not available on most systems.

## Credits and License

&kile;

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 installed. Kile is also part of the Fink project, which means you can run Kile even 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 make this project possible.

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

Program copyright 2002-2003 Brachet Pascal

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

Documentation Copyright © 2003 Jonathan Pechta

Contributions from: Rob Lensen, Roland Schulz, Michael Margraf

Translators: Thomas Basset (fr), Kris Luyten (nl), Alexander Hunziger (de), Stefan Asserhall (se), Alfredo Beaumont (eu), Leopold Palomo Avellaneda (ca), Federico Zenith (it), Quique (es), Maciej Woloszyn (pl).

Many thanks and best wishes to all those involved!

&underFDL; &underGPL;

&documentation.index;