% Copyright 2006 by Till Tantau % % This file may be distributed and/or modified % % 1. under the LaTeX Project Public License and/or % 2. under the GNU Free Documentation License. % % See the file doc/generic/pgf/licenses/LICENSE for more details. \section{Introduction} The \pgfname\ package, where ``\pgfname'' is supposed to mean ``portable graphics format'' (or ``pretty, good, functional'' if you prefer\dots), is a package for creating graphics in an ``inline'' manner. It defines a number of \TeX\ commands that draw graphics. For example, the code |\tikz \draw (0pt,0pt) -- (20pt,6pt);| yields the line \tikz \draw (0pt,0pt) -- (20pt,6pt); and the code |\tikz \fill[orange] (1ex,1ex) circle (1ex);| yields \tikz \fill[orange] (1ex,1ex) circle (1ex);. In a sense, when you use \pgfname\ you ``program'' your graphics, just as you ``program'' your document when you use \TeX. You get all the advantages of the ``\TeX-approach to typesetting'' 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 \textsc{wysiwyg}, small changes require a long recompilation time, and the code does not really ``show'' how things will look like. \subsection{Structure of the System} The \pgfname\ system consists of different layers: \begin{description} \item[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. \pgfname's system layer ``abstracts away'' these differences. For example, the system command |\pgfsys@lineto{10pt}{10pt}| extends the current path to the coordinate $(10\mathrm{pt},10\mathrm{pt})$ 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 \pgfname\ to a new driver. As a user, you will not use the system layer directly. \item[Basic layer:] The basic layer provides a set of basic commands that allow you to produce complex graphics in a much easier manner 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 \emph{core}, which consists of several interdependent packages that can only be loaded \emph{en bloc,} and additional packages that extend the core by more special-purpose commands like node management or a plotting interface. For instance, the \textsc{beamer} package uses the core, but not all of the additional packages of the basic layer. \item[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 \textsc{metafont}-like command: \begin{verbatim} \draw (0,0) -- (1,0) -- (1,1) -- cycle; \end{verbatim} There are different frontends: \begin{itemize} \item The \tikzname\ frontend is the ``natural'' frontend for \pgfname. It gives you access to all features of \pgfname, but it is intended to be easy to use. The syntax is a mixture of \textsc{metafont} and \textsc{pstricks} and some ideas of myself. This frontend is \emph{neither} a complete \textsc{metafont} compatibility layer nor a \textsc{pstricks} compatibility layer and it is not intended to become either. \item The |pgfpict2e| frontend reimplements the standard \LaTeX\ |{picture}| environment and commands like |\line| or |\vector| using the \pgfname\ 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. \end{itemize} It would be possible to implement a |pgftricks| frontend that maps \textsc{pstricks} commands to \pgfname\ 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. \end{description} As a user of \pgfname\ 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. \subsection{Comparison with Other Graphics Packages} \pgfname\ is not the only graphics package for \TeX. In the following, I try to give a reasonably fair comparison of the \pgfname-system and other packages. \begin{enumerate} \item The standard \LaTeX\ |{picture}| environment allows you to create simple graphics, but little more. 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. \item 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. Compared to \pgfname, |pstricks| has a broader support base. There are many nice extra packages for special purpose sitations that have been contributed by users over the last decade. The \tikzname\ syntax is more consistent than the |pstricks| syntax as \tikzname\ was developed ``in a more centralized manner'' and also ``with the shortcomings on |pstricks| in mind.'' Note that a number of neat tricks that |pstricks| can do are impossible in \pgfname. In particular, |pstricks| has access to the powerful PostScript programming language, which allows trickery such as inline function plotting. \item The |xypic| package is an older package for creating graphics. However, it is more difficult to use and to learn because the syntax and the documentation are a bit cryptic. \item The |dratex| package is a small graphic package for creating a graphics. Compared to the other package, including \pgfname, it is very small, which may or may not be an advantage. \item The |metapost| program is a very powerful alternative to \pgfname. However, it is an external program, which entails a whole bunch on problems. The time needed both to create a small graphics and also to compile it is much greater than in \pgfname. The main problem with |metapost|, however, is the inclusion of labels. This is \emph{much} easier to achieve using \pgfname. \item The |xfig| program is an important alternative to \tikzname\ for users who do not wish to ``program'' their graphics as is necessary with \tikzname\ and the other packages above. Their is a conversion program that will convert |xfig| graphics to both \tikzname\ and for \pgfname, but it is still under construction. \end{enumerate} \subsection{Utilities: Page Management} The \pgfname\ 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 \pgfname\ nevertheless, mostly because its implementation uses \pgfname\ 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 \emph{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. \subsection{How to Read This Manual} This manual describes both the design of the \pgfname\ 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 \pgfname, 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 \tikzname. 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 \pgfname\ 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. \subsection{Getting Help} When you need help with \pgfname\ and \tikzname, please do the following: \begin{enumerate} \item Read the manual, at least the part that has to do with your problem. \item If that does not solve the problem, try having a look at the sourceforge development page for \pgfname\ and \tikzname\ (see the title of this document). Perhaps someone has already reported a similar problem and someone has found a solution. \item 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. \item 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. \item \emph{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 \pgfname\ mailing list (naturally, I read this list and answer questions when I have the time). \item Please, do not phone me in my office. If you need a hotline, buy a commercial product. \end{enumerate}