% 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 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 \LaTeX\ style for creating the graphics in my (Till
Tantau's) PhD thesis directly with pdf\LaTeX\ has now grown to become a
full-blown 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 of 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
acronym in the tradition of ``\textsc{gnu}'s 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 these 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é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 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 intended
more 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 built 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
        GitHub 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 in a 
        timely fashion 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}