The PGF package, where “PGF” is supposed to mean “portable graphics format” (or “pretty, good, functional” if
you prefer...), is a package for creating graphics in an “inline” manner. The package defines a number of
TEX commands that draw graphics. For example, the code \tikz \draw (0pt,0pt) -- (20pt,6pt); yields the
line and the code \tikz \fill[orange] (1ex,1ex) circle (1ex); yields .
In a sense, when using PGF you “program” your graphics, just as you “program” your document
when using TEX. This means that you get the advantages of the “TEX-approach to typesetting”
also for your graphics: quick creation of simple graphics, precise positioning, the use of macros, often
superior typography. You also inherit all the disadvantages: steep learning curve, no WYSIWYG, small
changes require a long recompilation time, and the code does not really “show” how things will look
like.
1.1 Structure of the System
The PGF system consists of different layers:
System layer:
This layer provides a complete abstraction of what is going on “in the driver.” The driver
is a program like dvips or dvipdfm that takes a .dvi file as input and generates a .ps or a .pdf file.
(The pdftex program also counts as a driver, even though it does not take a .dvi file as input. Never
mind.) Each driver has its own syntax for the generation of graphics, causing headaches to everyone
who wants to create graphics in a portable way. PGF’s system layer “abstracts away” these differences.
For example, the system command \pgfsys@lineto{10pt}{10pt} extends the current path to the
coordinate (10pt,10pt) of the current {pgfpicture}. Depending on whether dvips, dvipdfm, or
pdftex is used to process the document, the system command will be converted to different \special
commands.
The system layer is as “minimalistic” as possible since each additional command makes it more work to
port PGF to a new driver. Currently, only drivers that produce PostScript or PDF output are supported
and only few of these (hence the name portable graphics format is currently a bit boastful). However,
in principle, the system layer could be ported to many different drivers quite easily. It should even be
possible to produce, say, SVG output in conjunction with TEX4HT.
As a user, you will not use the system layer directly.
Basic layer:
The basic layer provides a set of basic commands that allow you to produce complex graphics
in a much easier way than by using the system layer directly. For example, the system layer provides no
commands for creating circles since circles can be composed from the more basic Bézier curves (well,
almost). However, as a user you will want to have a simple command to create circles (at least I do)
instead of having to write down half a page of Bézier curve support coordinates. Thus, the basic layer
provides a command \pgfpathcircle that generates the necessary curve coordinates for you.
The basic layer is consists of a core, which consists of several interdependent packages that can only be
loaded en bloc, and additional packages that extend the core by more special-purpose commands like
node management or a plotting interface. For instance, the BEAMER package uses the core, but not all
of the additional packages of the basic layer.
Frontend layer:
A frontend (of which there can be several) is a set of commands or a special syntax that makes
using the basic layer easier. A problem with directly using the basic layer is that code written for this layer is
often too “verbose.” For example, to draw a simple triangle, you may need as many as five commands when
using the basic layer: One for beginning a path at the first corner of the triangle, one for extending the path to
the second corner, one for going to the third, one for closing the path, and one for actually painting the
triangle (as opposed to filling it). With the tikz frontend all this boils down to a single simple METAFONT-like
command:
\draw (0,0) -- (1,0) -- (1,1) -- cycle;
There are different frontends:
The TikZ frontend is the “natural” frontend for PGF. It gives you access to all features of PGF,
but it is intended to be easy to use. The syntax is a mixture of METAFONT and PSTRICKS and
some ideas of myself. This frontend is neither a complete METAFONT compatibility layer nor a
PSTRICKS compatibility layer and it is not intended to become either.
The pgfpict2e frontend reimplements the standard LATEX{picture} environment and
commands like \line or \vector using the PGF basic layer. This layer is not really “necessary”
since the pict2e.sty package does at least as good a job at reimplementing the {picture}
environment. Rather, the idea behind this package is to have a simple demonstration of how a
frontend can be implemented.
It would be possible to implement a pgftricks frontend that maps PSTRICKS commands to PGF commands.
However, I have not done this and even if fully implemented, many things that work in PSTRICKS will not
work, namely whenever some PSTRICKS command relies too heavily on PostScript trickery. Nevertheless, such
a package might be useful in some situations.
As a user of PGF you will use the commands of a frontend plus perhaps some commands of the basic layer.
For this reason, this manual explains the frontends first, then the basic layer, and finally the system
layer.
1.2 Comparison with Other Graphics Packages
There were two main motivations for creating PGF:
The standard LATEX{picture} environment is not powerful enough to create anything but really
simple graphics. This is certainly not due to a lack of knowledge or imagination on the part of LATEX’s
designer(s). Rather, this is the price paid for the {picture} environment’s portability: It works together
with all backend drivers.
The {pstricks} package is certainly powerful enough to create any conceivable kind of graphic, but it
is not portable at all. Most importantly, it does not work with pdftex nor with any other driver that
produces anything but PostScript code.
The PGF package is a trade-off between portability and expressive power. It is not as portable as {picture} and
perhaps not quite as powerful as {pspicture}. However, it is more powerful than {picture} and more portable
than {pspicture}.
1.3 Utilities: Page Management
The PGF package include a special subpackage called pgfpages, which is used to assemble several pages into a single
page. This package is not really about creating graphics, but it is part of PGF nevertheless, mostly because its
implementation uses PGF heavily.
The subpackage pgfpages provides commands for assembling several “virtual pages” into a single “physical
page.” The idea is that whenever TEX has a page ready for “shipout,” pgfpages interrupts this shipout and
instead stores the page to be shipped out in a special box. When enough “virtual pages” have been accumulated in
this way, they are scaled down and arranged on a “physical page,” which then really shipped out. This mechanism
allows you to create “two page on one page” versions of a document directly inside LATEX without the use of any
external programs.
However, pgfpages can do quite a lot more than that. You can use it to put logos and watermark on pages, print
up to 16 pages on one page, add borders to pages, and more.
1.4 How to Read This Manual
This manual describes both the design of the PGF system and its usage. The organization is very roughly according
to “user-friendliness.” The commands and subpackages that are easiest and most frequently used are described first,
more low-level and esoteric features are discussed later.
If you have not yet installed PGF, please read the installation first. Second, it might be a good idea to read the
tutorial. Finally, you might wish to skim through the description of TikZ. Typically, you will not need to read the
sections on the basic layer. You will only need to read the part on the system layer if you intend to write your own
frontend or if you wish to port PGF to a new driver.
The “public” commands and environments provided by the pgf package are described throughout the text. In
each such description, the described command, environment or option is printed in red. Text shown in green is
optional and can be left out.
1.5 Getting Help
When you need help with PGF and TikZ, please do the following:
Read the manual, at least the part that has to do with your problem.
If that does not solve the problem, try having a look at the sourceforge development page for PGF and
TikZ (see the title of this document). Perhaps someone has already reported a similar problem and
someone has found a solution.
On the website you will find numerous forums for getting help. There, you can write to help forums,
file bug reports, join mailing lists, and so on.
Before you file a bug report, especially a bug report concerning the installation, make sure that this
is really a bug. In particular, have a look at the .log file that results when you TEX your files. This
.log file should show that all the right files are loaded from the right directories. Nearly all installation
problems can be resolved by looking at the .log file.
As a last resort you can try to email me (the author). I do not mind getting emails, I simply get
way too many of them. Because of this, I cannot guarantee that your emails will be answered timely
or even at all. Your chances that your problem will be fixed are somewhat higher if you mail to the
PGF mailing list (naturally, I read this list and answer questions when I have the time).
Please, do not phone me in my office. If you need a hotline, buy a commercial product.