% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>.
%
% This program can be redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt.



\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. The package 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 using \pgfname\ 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 \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. Currently, only drivers that produce PostScript or
  \textsc{pdf} output are supported and only few of these (hence the
  name \emph{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, \textsc{svg} output in conjunction with
  \textsc{tex4ht}.

  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 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 \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}

There were two main motivations for creating \pgfname:
\begin{enumerate}
\item
  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.
\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.
\end{enumerate}

The \pgfname\ 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}|.

\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}

