☰
PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.10

Installation and Configuration

10 Supported Formats

was designed to be a flexible system. This is true both for the input for 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.

10.1 Supported Input Formats: , Plain , Cont

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

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

10.1.1 Using the Format

Using pgf and TikZ with the 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 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 2019 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Public License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\RequirePackage{pgf,pgffor}

\input{tikz.code.tex}

\endinput

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

10.1.2 Using the Plain Format

When using the plain format, you say \input{pgf.tex} or \input{tikz.tex}. Then, instead of \begin{pgfpicture} and \end{pgfpicture} you use \pgfpicture and \endpgfpicture.

Unlike for the format, pgf is not as good at discerning the appropriate configuration for the plain 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.

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

10.1.3 Using the Cont Format

When using the Cont format, you say \usemodule[pgf] or \usemodule[tikz]. As for the plain format you also have to replace the start- and end-of-environment tags as follows: Instead of \begin{pgfpicture} and \end{pgfpicture} you use \startpgfpicture and \stoppgfpicture; similarly, instead of \begin{tikzpicture} and \end{tikzpicture} you use must now use \starttikzpicture and \stoptikzpicture; and so on for other environments.

The Cont support is very similar to the plain support, so the same restrictions apply: You may have to set the output format directly and graphics inclusion may be a problem.

In addition to pgf and tikz there also exist modules like pgfcore or pgfmodulematrix. To use them, you may need to include the module pgfmod first (the modules pgf and tikz both include pgfmod for you, so typically you can skip this). This special module is necessary since old versions of Cont MkII before 2005 satanically restricted the length of module names to 8 characters and pgf’s long names are mapped to cryptic 6-letter-names for you by the module pgfmod. This restriction was never in place in Cont MkIV and the pgfmod module can be safely ignored nowadays.

10.2 Supported Output Formats

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

  • 1. 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 (informally known as “device-independent 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 -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 was an intermediate stage.

Normally, only produces letter–coordinate pairs as its “output”. This obviously makes it difficult to 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 away” 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.

10.2.1 Selecting the Backend Driver

When 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 which program you are going to use later on.

Unfortunately, there is no “standard” way of telling this to . For the 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.

10.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 pdf, that is, with the pdftex or pdflatex command. It includes pgfsys-common-pdf.def.

    This driver has a lot of functionality. (Almost) 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 mode it uses graphicx for the graphics inclusion and does not support masking.

    • 2. In plain mode it does not support image inclusion.

  • File pgfsys-xetex.def

    • This is a driver file for use with xe(la)tex followed by xdvipdfmx. This driver supports largely the same operations as the dvipdfm driver.

  • File pgfsys-vtex.def

    • This is the driver file for use with the commercial vtex program. Even though it produces 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 mode it uses graphicx for the graphics inclusion and does not support masking.

    • 2. In plain mode it does not support image inclusion.

    • 3. Shadings are approximated with discrete colors. This typically leads to aliasing patterns in PostScript and pdf viewing applications.

    • 4. Opacity, Transparency Groups, Fadings and Blend Modes are not supported.

    • 5. Remembering of pictures (inter-picture connections) is not supported.

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

10.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 mode it uses graphicx for the graphics inclusion. Image masking is supported if the PostScript output is further processed with ps2pdf to produce pdf.

    • 2. In plain mode it does not support image inclusion.

    • 3. Functional shadings are approximated with Type-0 functions (sampled functions), because Type-4 functions are not available in the latest (version 3) PostScript language definition. Due to their fixed resolution, Type-0 functional shadings are of lesser quality at higher zoom levels as compared to functional shadings from pdf producing drivers. Axial and radial shadings are fully supported. The same output quality (smooth shadings) is achieved as with drivers that produce pdf output.

    • 4. Although fully supported, opacity and fadings are pdf features that become visible only after further processing the PostScript output with ps2pdf. Note that newer Ghostscript versions are necessary for producing opacity in the pdf output. Also, beginning with version 9.52 of Ghostscript, command line option -dALLOWPSTRANSPARENCY must be added:


      ps2pdf -dALLOWPSTRANSPARENCY example.ps

    • 5. For remembering of pictures (inter-picture connections) you need to use a recent version of pdftex running in DVI-mode.

  • File pgfsys-textures.def

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

    This driver shares the restrictions of the vtex driver, but adds limited opacity support (no transparency groups, fadings and blend modes, though).

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

10.2.4 Producing SVG Output

  • File pgfsys-dvisvgm.def

    • This driver converts dvi files to svg file, including text and fonts. When you select this driver, pgf will output the required raw svg code for the pictures it produces.

    Since the graphics package does not (yet?) support this driver directly, there is special rule for this driver in : If the option dvisvgm is given to the tikz package, this driver gets selected (normally, the driver selected by graphics would be used). For packages like beamer that load pgf themselves, this means that the option dvisvgm should be given to the document class.


    % example.tex
    \documentclass[dvisvgm]{minimal}

    \usepackage{tikz}

    \begin{document}
    Hello \tikz [baseline] \fill [fill=blue!80!black] (0,.75ex) circle[radius=.75ex];
    \end{document}

    And then run


    latex example
    dvisvgm example

    or better


    lualatex --output-format=dvi example
    dvisvgm example

    (This is “better” since it gives you access to the full power of Lua inside your -file. In particular, TikZ is able to run graph drawing algorithms in this case.)

    Unlike the tex4ht driver below, this driver has full support of text nodes.

  • File pgfsys-tex4ht.def

    • This is a driver file for use with the tex4ht program. It is selected automatically when the tex4ht style or command is loaded. It includes pgfsys-common-svg.def.

    The tex4ht program converts .dvi-files to .html-files. While the html-format cannot be used to draw graphics, the svg-format can. This driver will ask pgf to produce an svg-picture for each pgf graphic in your text.

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

    • 1. In mode it uses graphicx for the graphics inclusion.

    • 2. In plain mode it does not support image inclusion.

    • 3. Remembering of pictures (inter-picture connections) is not supported.

    • 4. Text inside pgfpictures is not supported very well. The reason is that the svg specification currently does not support text very well and, although it is possible to “escape back” to html, TikZ has then to guess what size the text rendered by the browser would have.

    • 5. Unlike for other output formats, the bounding box of a picture “really crops” the picture.

    • 6. Matrices do not work.

    • 7. Functional shadings are not supported.

    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 special that inserts 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.

    Because text is not supported very well in the svg standard, you may wish to use the following options to modify the way text is handled:

    • /pgf/tex4ht node/escape=⟨boolean⟩ (default false)

      • Selects the rendering method for a text node with the tex4ht driver.

      When this key is set to false, text is translated into svg text, which is somewhat limited: simple characters (letters, numerals, punctuation, \(\sum \), \(\int \), …), subscripts and superscripts (but not subsubscripts) will display but everything else will be filtered out, ignored or will produce invalid html code (in the worst case). This means that two kind of texts render reasonably well:

      • 1. First, plain text without math mode, special characters or anything else special.

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

      If you use text that contains anything special, even something as simple as $\alpha$, this may corrupt the graphic.


      \tikz \node[draw,/pgf/tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$};

      When you write node[/pgf/tex4ht node/escape=true] {⟨text⟩}, pgf escapes back to html to render the ⟨text⟩. This method produces valid html code in most cases and the support for complicated text nodes is much better since code that renders well outside a {pgfpicture}, should also render well inside a text node. Another advantage is that inside text nodes with fixed width, html will produce line breaks for long lines. On the other hand, you need a browser with good svg support to display the picture. Also, the text will display differently, depending on your browsers, the fonts you have on your system and your settings. Finally, pgf has to guess the size of the text rendered by the browser to scale it and prevent it from sticking from the node. When it fails, the text will be either cropped or too small.


      \tikz \node[draw,/pgf/tex4ht node/escape=true]
      {Example : $\int_0^\infty\frac{1}{1+t^2}dt=\frac{\pi}{2}$};

    • /pgf/tex4ht node/css=⟨filename⟩ (default \jobname)

      • This option allows you to tell the browser what css file it should use to style the display of the node (only with tex4ht node/escape=true).

    • /pgf/tex4ht node/class=⟨class name⟩ (default foreignobject)

      • This option allows you to give a class name to the node, allowing it to be styled by a css file (only with tex4ht node/escape=true).

    • /pgf/tex4ht node/id=⟨id name⟩ (default \jobname picture number-node number)

      • This option allows you to give a unique id to the node, allowing it to be styled by a css file (only with tex4ht node/escape=true).

10.2.5 Producing Perfectly Portable DVI Output

  • File pgfsys-dvi.def

    • This is a driver file that can be used with any output driver, except for tex4ht.

    The driver will produce perfectly portable .dvi files by composing all pictures entirely of black rectangles, the basic and only graphic shape supported by the core. Even straight, but slanted lines are tricky to get right in this model (they need to be composed of lots of little squares).

    Naturally, very little is possible with this driver. In fact, so little is possible that it is easier to list what is possible:

    • • Text boxes can be placed in the normal way.

    • • Lines and curves can be drawn (stroked). If they are not horizontal or vertical, they are composed of hundreds of small rectangles.

    • • Lines of different width are supported.

    • • Transformations are supported.

    Note that, say, even filling is not supported! (Let alone color or anything fancy.)

    This driver has only one real application: It might be useful when you only need horizontal or vertical lines in a picture. Then, the results are quite satisfactory.