5 Input and Output Formats

TEX was designed to be a flexible system. This is true both for the input for TEX as well as for the output. The present section explains which input formats there are and how they are supported by PGF. It also explains which different output formats can be produced.

5.1 Supported Input Formats

TEX does not prescribe exactly how your input should be formatted. While it is customary that, say, an opening brace starts a scope in TEX, this is by no means necessary. Likewise, it is customary that environments start with \begin, but TEX could not really care less about the exact command name.

Even though TEX can be reconfigured, users can not. For this reason, certain input formats specify a set of commands and conventions how input for TEX should be formatted. There are currently three “major” formats: Donald Knuth’s original plain TEX format, Leslie Lamport’s popular LATEX format, and Hans Hangen’s ConTEXt format.

5.1.1 Using the LATEX Format

Using PGF and TikZ with the LATEX format is easy: You say \usepackage{pgf} or \usepackage{tikz}. Usually, that is all you need to do, all configuration will be done automatically and (hopefully) correctly.

The style files used for the LATEX format reside in the subdirectory latex/pgf/ of the PGF-system. Mainly, what these files do is to include files in the directory generic/pgf. For example, here is the content of the file latex/pgf/frontends/tikz.sty:

 % Copyright 2005 by Till Tantau . % % This program can be redistributed and/or modified under the terms % of the GNU Public License, version 2. \RequirePackage{pgf,calc,pgffor,pgflibraryplothandlers,xkeyval} \input{tikz.code} \endinput

The files in the generic/pgf directory do the actual work.

5.1.2 Using the Plain TEX Format

When using the plain TEX format, you say \input{pgf.tex} or \input{tikz.tex}. Instead of \begin{pgfpicture} and \end{pgfpicture} you use \pgfpicture and \endpicture.

Unlike for the LATEX format, PGF is not as good at discerning the appropriate configuration for the plain TEX format. In particular, it can only automatically determine the correct output format if you use pdftex or tex plus dvips. For all other output formats you need to set the macro \pgfsysdriver to the correct value. See the description of using output formats later on.

PGF was originally written for use with LATEX and this shows in a number of places. Nevertheless, the plain TEX support is reasonably good.

Like the LATEX style files, the plain TEX files like tikz.tex also just include the correct tikz.code.tex file.

5.1.3 Using the ConTEXt Format

Currently, there is no special support for the ConTEXt format. Rather, you have to use PGF and TikZ as if you were using the plain TEX format when using ConTEXt. This may change in the future.

5.2 Supported Output Formats

An output format is a format in which TEX outputs the text it has typeset. Producing the output is (conceptually) a two-stage process:

1. TEX typesets your text and graphics. The result of this typesetting is mainly a long list of letter-coordinate pairs, plus (possibly) some “special” commands. This long list of pairs is written to something called a .dvi-file.
2. Some other program reads this .dvi-file and translates the letter-coordinate pairs into, say, PostScript commands for placing the given letter at the given coordinate.

The classical example of this process is the combination of latex and dvips. The latex program (which is just the tex program called with the LATEX-macros preinstalled) produces a .dvi-file as its output. The dvips program takes this output and produces a .ps-file (a PostScript) file. Possibly, this file is further converted using, say, ps2pdf, whose name is supposed to mean “PostScript to PDF.” Another example of programs using this process is the combination of tex and dvipdfm. The dvipdfm program takes a .dvi-file as input and translates the letter-coordinate pairs therein into PDF-commands, resulting in a .pdf file directly. Finally, the tex4ht is also a program that takes a .dvi-file and produces an output, this time it is a .html file. The programs pdftex and pdflatex are special: They directly produce a .pdf-file without the intermediate .dvi-stage. However, from the programmer’s point of view they behave exactly as if there where an intermediate stage.

Normally, TEX only produces letter-coordinate pairs as its “output.” This obviously makes is difficult tho draw, say, a curve. For this, “special” commands can be used. Unfortunately, these special commands are not the same for the different programs that process the .dvi-file. Indeed, every program that takes a .dvi-file as input has a totally different syntax for the special commands.

One of the main jobs of PGF is to “abstract way” the difference in the syntax of the different programs. However, this means that support for each program has to be “programmed,” which is a time-consuming and complicated process.

5.2.1 Selecting the Backend Driver

When TEX typesets your document, it does not know which program you are going to use to transform the .dvi-file. If your .dvi-file does not contain any special commands, this would be fine; but these days almost all .dvi-files contain lots of special commands. It is thus necessary to tell TEX which program you are going to use later on.

Unfortunately, there is no “standard” way of telling this to TEX. For the LATEX format a sophisticated mechanism exists inside the graphics package and PGF plugs into this mechanism. For other formats and when this plugging does not work as expected, it is necessary to tell PGF directly which program you are going to use. This is done by redefining the macro \pgfsysdriver to an appropriate value before you load pgf. If you are going to use the dvips program, you set this macro to the value pgfsys-dvips.def; if you use pdftex or pdflatex, you set it to pgfsys-pdftex.def; and so on. In the following, details of the support of the different programs are discussed.

5.2.2 Producing PDF Output

PGF supports three programs that produce PDF output (PDF means “portable document format” and was invented by the Adobe company): dvipdfm, pdftex, and vtex. The pdflatex program is the same as the pdftex program: it uses a different input format, but the output is exactly the same.

File pgfsys-pdftex.def

This is the driver file for use with pdfTEX, that is, with the pdftex or pdflatex command. It includes pgfsys-common-pdf.def.

This driver has the “complete” functionality. This means, everything PGF “can do at all” is implemented in this driver.

File pgfsys-dvipdfm.def

This is a driver file for use with (la)tex followed by dvipdfm. It includes pgfsys-common-pdf.def.

This driver supports most of PGF’s features, but there are some restrictions:

1. In LATEX mode it uses graphicx for the graphics inclusion and does not support masking.
2. In plain TEX mode it does not support image inclusion.

File pgfsys-vtex.def

This is the driver file for use with the commercial VTEX program. Even though is will produce PDF output, it includes pgfsys-common-postscript.def. Note that the VTEX program can produce both Postscript and PDF output, depending on the command line parameters. However, whether you produce Postscript or PDF output does not change anything with respect to the driver.

This driver supports most of PGF’s features, except for the following restrictions:

1. In LATEX mode it uses graphicx for the graphics inclusion and does not support masking.
2. In plain TEX mode it does not support image inclusion.
3. Shading is fully implemented, but yields the same quality as the implementation for dvips.
4. Opacity is not implemented at all.

It is also possible to produce a .pdf-file by first producing a PostScript file (see below) and then using a PostScript-to-PDF conversion program like ps2pdf or the Acrobat Distiller.

5.2.3 Producing PostScript Output

File pgfsys-dvips.def

This is a driver file for use with (la)tex followed by dvips. It includes pgfsys-common-postscript.def.

This driver also supports most of PGF’s features, except for the following restrictions:

1. In LATEX mode it uses graphicx for the graphics inclusion and does not support masking.
2. In plain TEX mode it does not support image inclusion.
3. Shading is fully implemented, but the results will not be as good as with a driver producing .pdf as output.
4. Opacity works only in conjunction with newer versions of GhostScript.

File pgfsys-textures.def

This is a driver file for use with the TEXTURES program. It includes pgfsys-common-postscript.def.

This driver has exactly the same restrictions as the driver for dvips.

You can also use the vtex program together with pgfsys-vtex.def to produce Postscript output.

5.2.4 Producing HTML / SVG Output

The tex4ht program converts .dvi-files to .html-files. While the HTML-format cannot be used to draw graphics, the SVG-format can. Using the following driver, you can ask PGF to produce an SVG-picture for each PGF graphic in your text.

File pgfsys-tex4ht.def

This is a driver file for use with the tex4ht program. It includes pgfsys-common-svg.def.

When using this driver you should be aware of the following restrictions:

1. In LATEX mode it uses graphicx for the graphics inclusion.
2. In plain TEX mode it does not support image inclusion.
3. Text inside pgfpictures is not supported very well. The reason is that the SVG specification currently does not support text very well and it is also not possible to correctly “escape back” to HTML. All these problems will hopefully disappear in the future, but currently only two kinds of text work reasonably well: First, plain text without math mode, special characters or anything else special. Second, very simple mathematical text that contains subscripts or superscripts. Even then, variables are not correctly set in italics and, in general, text simple does not look very nice.
4. If you use text that contains anything special, even something as simple as $\alpha$, this may corrupt the graphic since text4ht does not always produce valid XML code. So, once more, stick to very simple node text inside graphics. Sorry.
5. Unlike for other output formats, the bounding box of a picture “really crops” the picture.

The driver basically works as follows: When a {pgfpicture} is started, appropriate \special commands are used to directed the output of tex4ht to a new file called \jobname-xxx.svg, where xxx is a number that is increased for each graphic. Then, till the end of the picture, each (system layer) graphic command creates a specials that insert appropriate SVG literal text into the output file. The exact details are a bit complicated since the imaging model and the processing model of PostScript/PDF and SVG are not quite the same; but they are “close enough” for PGF’s purposes.