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 or further conversion, you can use the shortcut 2. Then you can view the file using your default viewer with 3, convert the to a PS file with 4, and view the PS file with 5.

BibTEX
If you are using BibTEX for your bibliography entries, you usually have to follow a special compiling scheme. This means calling LATEX and then BibTEX and then LATEX twice again. Fortunately Kile is clever enough to detect automatically if it is necessary to call additional tools like BibTEX, makeidx and Asymptote. This logic is turned on by default and can be changed in Settings Configure Kile... Tools Build in the General tab in the LATEX and PDFLATEX tools.

MetaPost and Asymptote
If you want to compile your document with MetaPost or Asymptote, picture drawing programs, you can do it with Build Compile Metapost, or Build Compile Asymptote.

PDFLATEX
There is also another way to compile your document, if you want a PDF: you can run PDFLATEX, that will compile the source directly into a PDF file, with 6: you can then view the compiled file by pressing 7.
Alternatively, you can convert a PS into a PDF with 8, or a directly into a PDF with 9.
Using PDFLATEX instead of LATEX may be just a matter of simplicity or habit, but sometimes the behavior of the two programs can differ.

LATEX to Web
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 Web. 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 .

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

Quick Preview
You will always need some time to view the result, when working with LATEX. LATEX has to compile the source and the viewer has to be called. This can be annoying if you only changed some letters in an equation difficult to typeset. Kile offers a Quick Preview mode, where you can compile only a part of a document and save a lot of time. It supports four different modes, which can be combined with seven configurations.
Quick Preview
Quick Preview
All settings must be done in Settings Configure Kile... Tools Preview.
Quick Preview Configuration
Quick Preview Configuration

Selection Mode
The user has to select a part of the document. Menu entry Build QuickPreview Selection or the keyboard shortcut P,S will start the selected programs. Kile takes the preamble of the original text, so that all packages and user defined commands are included. The user can choose one of eight predefined configurations:
LaTeX+ (embedded viewer)
LaTeX+ ()
LaTeX+PS (embedded viewer)
LaTeX+PS ()
PDFLaTeX+PDF (embedded viewer)
PDFLaTeX+PDF ()
XeLaTeX+PDF (embedded viewer)
XeLaTeX+PDF ()
This should be sufficient for all situations for which a quick preview is needed.

Environment Mode
Very often you want to preview the current environment, and especially mathematical environments, which sometimes may be difficult to write. Kile offers a very fast way to do this. No selection is needed, just choose Build QuickPreview Environment or the keyboard shortcut P,E and the current environment will be compiled and shown.

Subdocument Mode
If you have a large project with a lot of documents, compiling the whole project is not a great idea, if you have made changes only in one single document. Kile is able to compile and show a preview of the current subdocument. It takes the preamble from the master document and only compiles the current part when you choose Build QuickPreview Subdocument or the keyboard shortcut P,D.

Mathgroup Mode
The mathgroup preview mode allows you to preview the mathgroup you are currently editing. Kile takes the preamble from the master document and only compiles the mathgroup the cursor is currently in when you choose Build QuickPreview Mathgroup or the keyboard shortcut P,M.

Quick Preview in Bottom Bar
Instead of showing the preview in a new document Kile can also be configured to use the bottom bar for preview compilations. You can activate this feature in the quick preview configuration panel.

Graphic File Formats

LATEX and PDFLATEX
PDFLATEX, when used with graphics or graphicx packages, can correctly compile PNG and JPG files into or PDF, but is not able to handle EPS files. Conversely, the process of compiling with LATEX to and converting to PS and eventually PDF does support EPS, but does not support PNG and JPG.
A lot of users want to create PDF documents, but also want to use the excellent Pstricks package to create graphics, or they want to use the output of mathematical and scientific software like Mathematica, Maple or MuPAD. These LATEX users have to compile first in , even if they want to create PDF documents, because these programs produce code which cannot be managed by PDFLATEX. However, it is not so hard as it may sound, because Kile will help.

Graphics Conversion
To overcome this frustrating loop, when you want to include both code and PNG or JPG files, you have a number of workarounds:
If you need a file in PS format, but have JPG or PNG graphics, you can also simply use PDFLATEX with output first, and then run dvips to create the PS file. You see that PDFLATEX is a very good choice, if your source contains no code at all.
You can convert EPS files to PNG or other formats with utilities as the Gimp or ImageMagick and use PDFLATEX.
A preferred way is to convert EPS graphics to PDF graphics with epstopdf, which comes with every TEX distribution and then use PDFLATEX. It produces high quality graphics, and you can even control the result with some of the following options:

	-dAutoFilterColorImages=false
	-dAutoFilterGrayImages=false
	-sColorImageFilter=FlateEncode
	-sGrayImageFilter=FlateEncode
	-dPDFSETTINGS=/prepress
	-dUseFlateCompression=true

Even better: if your system allows shell-escape, conversion can be done on the fly. All you have to do is to include the epstopdf package, which is part of all TEX distributions, with the command \usepackage{epstopdf}. Assuming that your code is:

	\includegraphics[width=5cm]{test.eps}

When you call PDFLATEX with option --shell-escape, graphics test.eps is automatically converted into test.pdf.
This conversion will take place each time you run PDFLATEX. If your graphics command is given implicitly:

	\includegraphics[width=5cm]{test}

epstopdf checks whether test.pdf is already available, so that the conversion step can be skipped.
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. Conversion of all graphics formats to EPS can be done by ImageMagick. Another simple program that does this process correctly is jpg2ps.
You can also use an automatic conversion. All graphics files are converted on the fly to EPS, and inserted into the PS document. This is a comfortable way, but you have to set up your system properly. This is discussed in the section EPS Graphics.

Use the right File for the right Graphic
EPS is sort of a graphic vector scripting language, describing all the lines and dots the graphic is made of; it looks good even when magnified beyond its default size, and suits best diagrams and vectorial graphics natively produced in EPS, which look very clear and sharp while maintaining a very small byte size.
PNG (or the deprecated ) 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.

EPS Graphics
EPS graphics files are the traditional way to insert graphics files into LATEX documents. As mailing lists are full with questions concerning EPS graphics, we will discuss some important aspects and demonstrate how Kile supports them.

LATEX and EPS Graphics
If you decided to use the traditional LATEX to produce PS or PDF output, you will probably run into some problems with graphics. You have to use EPS graphics (Encapsulated ); no JPEG or PNG files. This should be no problem, as there are a lot of converters like convert from the excellent ImageMagick package. But, it needs some time of course.
The EPS files are used by both LATEX and the -PS converter:
LATEX scans the EPS file for the bounding-box line, which tells LATEX how much space to reserve for the graphics.
The -PS converter then reads the EPS file and inserts the graphics in the PS file.
This has some implications:
LATEX never reads the EPS file if the bounding-box parameters are specified in the graphics insertion command.
Since LATEX cannot read non-ASCII files, it cannot read the bounding-box information from compressed or non-EPS graphics files.
The EPS graphics are not included in the file. Since the EPS files must be present when the file is converted to PS, the EPS files must accompany the files whenever they are moved.
Now you can call LATEX, and a -PS converter like dvips to create your document. If your goal is a PDF document, you should run dvips with option -Ppdf and then call ps2pdf. You will find a lot of documents describing this solution.

The Way of Kile
Kile helps you to get the bounding-box information. If you have installed ImageMagick package, Kile will extract this information from the EPS file and insert it as an option. This is done automatically when you select the graphics file. There are two advantages to proceeding like this:
The information is already scanned in the dialog, and need not to be done by LATEX later on.
Even more important is that the width and height of the picture can be calculated, when the resolution is known. This information will be shown near the top of the dialog, and may serve as a clue when you want to scale the graphics.
Kile can also support zipped or gzipped EPS files, which are much smaller than uncompressed EPS files. But, this feature can only be used with a special system setup and a change of your local graphics configuration, as it is described in the Bitmap Graphics section.

The Way and Bitmap Graphics
If your system allows shell-escape, Kile also supports an easy way to include bitmap graphics, if you set up your TEX system properly. There is no need to convert JPEG or PNG graphics, this can be done automatically when the file is converted to PS.
LATEX needs some information about the file suffixes. The package graphicx looks for a file graphics.cfg, which must be somewhere in your search path for LATEX documents. Search for entries like:

   \DeclareGraphicsRule{.pz}{eps}{.bb}{}%
   \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}%
   \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}%
   \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}%
   \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{}%

and replace these lines with:

   \DeclareGraphicsRule{.pz}{eps}{.bb}{}%
   \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}%
   \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}%
   \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}%
   % changed or new graphic rules
   \DeclareGraphicsRule{.eps.zip}{eps}{.eps.bb}{`unzip -p #1}%   zipped EPS
   \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c #1}%   gzipped EPS
   \DeclareGraphicsRule{.jpg}{eps}{}{`convert #1 eps:-}%         JPEG
   \DeclareGraphicsRule{.gif}{eps}{.bb}{`convert #1 eps:-}%      GIF
   \DeclareGraphicsRule{.png}{eps}{.bb}{`convert #1 eps:-}%      PNG
   \DeclareGraphicsRule{.tif}{eps}{.bb}{`convert #1 eps:-}%      TIFF
   \DeclareGraphicsRule{.pdf}{eps}{.bb}{`convert #1 eps:-}%      PDF-graphics

You will find this file, for example in Debian, at /etc/texmf/latex/graphics.cfg. The best way to proceed is to copy this file to your local texpath and then change this copy. See your TEX distribution manual to learn how to get a list of your TEX folders.
With this configuration file you are able to insert bitmap graphics and zipped or gzipped EPS files in LATEX. The command for conversion is given by dvips. When you look at the conversion command you will see that no extra file is created. The result of the conversion process is directly piped into the PS file. The only thing LATEX must know is the size of the graphics, and therefore we need the bounding box, which is provided by Kile.
Some say that this way is insecure; you have to decide on how to work. In any case, you need no bounding box, as Kile will extract this information from all types of graphics.

PDFLATEX and EPS Graphics
As already stated, PDFLATEX is not able to handle EPS graphic files, but converters like epstopdf will help. The best way is to include package epstopdf, which must follow the graphicx package.

   \usepackage[pdftex]{graphicx}
   \usepackage{epstopdf}

Now you can already include EPS graphics, if you run pdflatex with option --shell-escape, but we can make it even better and also handle zipped or gzipped EPS files. Again we have to change the graphics configuration file graphics.cfg as above. This time we search for:

   % pdfTeX is running in pdf mode
   \ExecuteOptions{pdftex}%

and simply add some lines:

   % pdfTeX is running in pdf mode
   \ExecuteOptions{pdftex}%
   \AtEndOfPackage{%
      \g@addto@macro\Gin@extensions{.eps.gz,.eps.zip}%
      \@namedef{Gin@rule@.eps.gz}#1{{pdf}{.pdf}{`gunzip -c #1 | epstopdf -f >\Gin@base.pdf}}%
      \@namedef{Gin@rule@.eps.zip}#1{{pdf}{.pdf}{`unzip -p #1 | epstopdf -f >\Gin@base.pdf}}%
   }%

With these lines, PDFLATEX is able to handle EPS files, and hopefully there should be no more issues concerning graphics.

Master Document
Defining your document as a master allows you to work with separate 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 and Messages window. One can take a closer look at the messages by selecting Build View Log File, or by using the keyboard shortcut 0. The generated log is then displayed in the Log and Messages view; errors and warnings are highlighted.
Viewing the log
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 and Messages view. Kile will take you automatically to the offending line.

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