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

Welcome to the documentation of \tikzname\ and the underlying
\pgfname\ system. What began as a small La\TeX\ style for creating the 
graphics in my (Till Tantau's) PhD thesis directly with pdf\LaTeX\ has now
grown to become a full-flung graphics language with a manual of over a
thousand pages. The wealth of options offered by \tikzname\ is often
daunting to beginners; but fortunately this documentation comes with a
number slowly-paced tutorials that will teach you almost all you
should know about \tikzname\ without your having to read the rest.

I wish to start with the questions ``What is \tikzname?''
Basically, it just 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
\tikzname\ you ``program'' your graphics, just as you ``program'' your
document when you use \TeX. This also explains the name: \tikzname\
is a recursive accronym in the tradition of ``\textsc{gnu} is not
unix'' and means ``\tikzname\ ist \emph{kein} Zeichenprogramm,'' which
translates to ``\tikzname\ is not a drawing program,'' cautioning the
reader as to what to expect. With \tikzname\ 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. 

Now that we know what \tikzname\ is, what about ``\pgfname''?
As mentioned earlier, \tikzname\ started out as a project to implement
\TeX\ graphics macros that can be used both with pdf\LaTeX\ and also
with the classical (PostScript-based) \LaTeX. In other words, I wanted
to implement a ``portable graphics format'' for \TeX\ -- hence the
name \pgfname. These early macros are still around and they form the
``basic layer'' of the system described in this manual, but most of
the interaction an author has theses days is with \tikzname\ -- which
has become a whole language of its own.


\subsection{The Layers Below \tikzname}

It turns out that there are actually \emph{two} layers below \tikzname:

\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\'ezier 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\'ezier curve support coordinates. Thus, the basic layer provides a
  command |\pgfpathcircle| that generates the necessary curve
  coordinates for you.

  The basic layer consists of a \emph{core}, which consists of
  several interdependent packages that can only be loaded \emph{en
    bloc,} and additional \emph{modules} that extend the core by more
  special-purpose commands like node management or a plotting
  interface. For instance, the \textsc{beamer} package uses only the
  core and not, say, the |shapes| modules.
\end{description}  

In theory, \tikzname itself is just one of several possible
``frontends,'' which are sets 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 \tikzname\ 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}

In practice, \tikzname\ is the only ``serious'' 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. There are other frontends
besides \tikzname, but they are more intended as ``technology
studies'' and less as serious alternatives to \tikzname. In
particular, 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. 

Since most users will only use \tikzname\ and almost no one will use
the system layer directly, this manual is mainly about \tikzname\ in
the first parts; the basic layer and the system layer are explained at
the end.


\subsection{Comparison with Other Graphics Packages}

\tikzname\ is not the only graphics package for \TeX. In the following,
I try to give a reasonably fair comparison of \tikzname\ 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 really portable. Most
  importantly, it does not work with |pdftex| nor with any other
  driver that produces anything but PostScript code.

  Compared to \tikzname, |pstricks| has a similar support base. There
  are many nice extra packages for special purpose situations 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.''
\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 \tikzname, it is
  very small, which may or may not be an advantage.
\item
  The |metapost| program is a powerful alternative to
  \tikzname. It used to be an external program, which entailed a
  bunch of problems, but in Lua\TeX\ it is now build in. An obstacle
  with |metapost| 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. There is a conversion
  program that will convert |xfig| graphics to \tikzname.
\end{enumerate}


\subsection{Utility Packages}

The \pgfname\ package comes along with a number of utility package that
are not really about creating graphics and which can be used
independently of \pgfname. However, they are bundled with \pgfname,
partly out of convenience, partly because their functionality is
closely intertwined with \pgfname. These utility packages are:
\begin{enumerate}
\item The |pgfkeys| package defines a powerful key management
  facility. It can be used completely independently of \pgfname.
\item The |pgffor| package defines a useful |\foreach| statement.
\item The |pgfcalendar| package defines macros for creating
  calendars. Typically, these calendars will be rendered using
  \pgfname's graphic engine, but you can use |pgfcalendar| also
  typeset calendars using normal text. The package also defines
  commands for ``working'' with dates.
\item The |pgfpages| package is used to assemble several pages into a
  single page. It 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.
\end{enumerate}



\subsection{How to Read This Manual}

This manual describes both the design of \tikzname\ 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 \tikzname, 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 system
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{Authors and Acknowledgements}
\label{section-authors}

The bulk of the \pgfname\ system and its documentation was written by
Till Tantau. A further member of the main team is Mark Wibrow, who
is responsible, for example, for the \pgfname\ mathematical engine,
many shapes, the decoration engine, and matrices. The third member is
Christian Feuers\"anger who contributed the floating point library,
image externalization, extended key processing, and automatic hyperlinks
in the manual.

Furthermore, occasional contributions have been made by Christophe
Jorssen, Jin-Hwan Cho, Olivier Binda, Matthias Schulz, Ren\'ee Ahrens,
Stephan Schuster, and Thomas Neumann.

Additionally, numerous people have contributed to the \pgfname\ system
by writing emails, spotting bugs, or sending libraries and patches.
Many thanks to all these people, who are too numerous to name them
all!



\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 (Till Tantau) or, if
  the problem concerns the mathematical engine, Mark Wibrow. 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).
\end{enumerate}
