| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Introduction} |
| 12 |
|
| 13 |
Welcome to the documentation of \tikzname\ and the underlying \pgfname\ system. |
| 14 |
What began as a small \LaTeX\ style for creating the graphics in my (Till |
| 15 |
Tantau's) PhD thesis directly with pdf\LaTeX\ has now grown to become a |
| 16 |
full-blown graphics language with a manual of over a thousand pages. The wealth |
| 17 |
of options offered by \tikzname\ is often daunting to beginners; but |
| 18 |
fortunately this documentation comes with a number of slowly-paced tutorials that |
| 19 |
will teach you almost all you should know about \tikzname\ without your having |
| 20 |
to read the rest. |
| 21 |
|
| 22 |
I wish to start with the question ``What is \tikzname?'' Basically, it just |
| 23 |
defines a number of \TeX\ commands that draw graphics. For example, the code |
| 24 |
|\tikz \draw (0pt,0pt) -- (20pt,6pt);| yields the line \tikz \draw (0pt,0pt) -- |
| 25 |
(20pt,6pt); and the code |\tikz \fill[orange] (1ex,1ex) circle (1ex);| yields |
| 26 |
\tikz \fill[orange] (1ex,1ex) circle (1ex);. In a sense, when you use |
| 27 |
\tikzname\ you ``program'' your graphics, just as you ``program'' your document |
| 28 |
when you use \TeX. This also explains the name: \tikzname\ is a recursive |
| 29 |
acronym in the tradition of ``\textsc{gnu}'s Not Unix'' and means ``\tikzname\ |
| 30 |
ist \emph{kein} Zeichenprogramm'', which translates to ``\tikzname\ is not a |
| 31 |
drawing program'', cautioning the reader as to what to expect. With \tikzname\ |
| 32 |
you get all the advantages of the ``\TeX-approach to typesetting'' for your |
| 33 |
graphics: quick creation of simple graphics, precise positioning, the use of |
| 34 |
macros, often superior typography. You also inherit all the disadvantages: |
| 35 |
steep learning curve, no \textsc{wysiwyg}, small changes require a long |
| 36 |
recompilation time, and the code does not really ``show'' how things will look |
| 37 |
like. |
| 38 |
|
| 39 |
Now that we know what \tikzname\ is, what about ``\pgfname''? As mentioned |
| 40 |
earlier, \tikzname\ started out as a project to implement \TeX\ graphics macros |
| 41 |
that can be used both with pdf\LaTeX\ and also with the classical |
| 42 |
(PostScript-based) \LaTeX. In other words, I wanted to implement a ``portable |
| 43 |
graphics format'' for \TeX\ -- hence the name \pgfname. These early macros are |
| 44 |
still around and they form the ``basic layer'' of the system described in this |
| 45 |
manual, but most of the interaction an author has these days is with |
| 46 |
\tikzname\ -- which has become a whole language of its own. |
| 47 |
|
| 48 |
|
| 49 |
\subsection{The Layers Below \tikzname} |
| 50 |
|
| 51 |
It turns out that there are actually \emph{two} layers below \tikzname: |
| 52 |
% |
| 53 |
\begin{description} |
| 54 |
\item[System layer:] This layer provides a complete abstraction of what |
| 55 |
is going on ``in the driver''. The driver is a program like |dvips| |
| 56 |
or |dvipdfm| that takes a |.dvi| file as input and generates a |.ps| |
| 57 |
or a |.pdf| file. (The |pdftex| program also counts as a driver, even |
| 58 |
though it does not take a |.dvi| file as input. Never mind.) Each |
| 59 |
driver has its own syntax for the generation of graphics, causing |
| 60 |
headaches to everyone who wants to create graphics in a portable way. |
| 61 |
\pgfname's system layer ``abstracts away'' these differences. For |
| 62 |
example, the system command |\pgfsys@lineto{10pt}{10pt}| extends the |
| 63 |
current path to the coordinate $(10\mathrm{pt},10\mathrm{pt})$ of |
| 64 |
the current |{pgfpicture}|. Depending on whether |dvips|, |dvipdfm|, |
| 65 |
or |pdftex| is used to process the document, the system command will |
| 66 |
be converted to different |\special| commands. The system layer is as |
| 67 |
``minimalistic'' as possible since each additional command makes it |
| 68 |
more work to port \pgfname\ to a new driver. |
| 69 |
|
| 70 |
As a user, you will not use the system layer directly. |
| 71 |
\item[Basic layer:] The basic layer provides a set of basic commands that |
| 72 |
allow you to produce complex graphics in a much easier manner than by |
| 73 |
using the system layer directly. For example, the system layer provides |
| 74 |
no commands for creating circles since circles can be composed from the |
| 75 |
more basic Bézier curves (well, almost). However, as a user you will |
| 76 |
want to have a simple command to create circles (at least I do) instead |
| 77 |
of having to write down half a page of Bézier curve support |
| 78 |
coordinates. Thus, the basic layer provides a command |\pgfpathcircle| |
| 79 |
that generates the necessary curve coordinates for you. |
| 80 |
|
| 81 |
The basic layer consists of a \emph{core}, which consists of several |
| 82 |
interdependent packages that can only be loaded \emph{en bloc}, and |
| 83 |
additional \emph{modules} that extend the core by more |
| 84 |
special-purpose commands like node management or a plotting |
| 85 |
interface. For instance, the \textsc{beamer} package uses only the |
| 86 |
core and not, say, the |shapes| modules. |
| 87 |
\end{description} |
| 88 |
|
| 89 |
In theory, \tikzname\ itself is just one of several possible ``frontends''. |
| 90 |
which are sets of commands or a special syntax that makes using the basic layer |
| 91 |
easier. A problem with directly using the basic layer is that code written for |
| 92 |
this layer is often too ``verbose''. For example, to draw a simple triangle, |
| 93 |
you may need as many as five commands when using the basic layer: One for |
| 94 |
beginning a path at the first corner of the triangle, one for extending the |
| 95 |
path to the second corner, one for going to the third, one for closing the |
| 96 |
path, and one for actually painting the triangle (as opposed to filling it). |
| 97 |
With the \tikzname\ frontend all this boils down to a single simple |
| 98 |
\textsc{metafont}-like command: |
| 99 |
% |
| 100 |
\begin{verbatim} |
| 101 |
\draw (0,0) -- (1,0) -- (1,1) -- cycle; |
| 102 |
\end{verbatim} |
| 103 |
|
| 104 |
In practice, \tikzname\ is the only ``serious'' frontend for \pgfname. It gives |
| 105 |
you access to all features of \pgfname, but it is intended to be easy to use. |
| 106 |
The syntax is a mixture of \textsc{metafont} and \textsc{pstricks} and some |
| 107 |
ideas of myself. There are other frontends besides \tikzname, but they are intended |
| 108 |
more as ``technology studies'' and less as serious alternatives to |
| 109 |
\tikzname. In particular, the |pgfpict2e| frontend reimplements the standard |
| 110 |
\LaTeX\ |{picture}| environment and commands like |\line| or |\vector| using |
| 111 |
the \pgfname\ basic layer. This layer is not really ``necessary'' since the |
| 112 |
|pict2e.sty| package does at least as good a job at reimplementing the |
| 113 |
|{picture}| environment. Rather, the idea behind this package is to have a |
| 114 |
simple demonstration of how a frontend can be implemented. |
| 115 |
|
| 116 |
Since most users will only use \tikzname\ and almost no one will use the system |
| 117 |
layer directly, this manual is mainly about \tikzname\ in the first parts; the |
| 118 |
basic layer and the system layer are explained at the end. |
| 119 |
|
| 120 |
|
| 121 |
\subsection{Comparison with Other Graphics Packages} |
| 122 |
|
| 123 |
\tikzname\ is not the only graphics package for \TeX. In the following, I try |
| 124 |
to give a reasonably fair comparison of \tikzname\ and other packages. |
| 125 |
% |
| 126 |
\begin{enumerate} |
| 127 |
\item The standard \LaTeX\ |{picture}| environment allows you to create |
| 128 |
simple graphics, but little more. This is certainly not due to a lack |
| 129 |
of knowledge or imagination on the part of \LaTeX's designer(s). |
| 130 |
Rather, this is the price paid for the |{picture}| environment's |
| 131 |
portability: It works together with all backend drivers. |
| 132 |
\item The |pstricks| package is certainly powerful enough to create any |
| 133 |
conceivable kind of graphic, but it is not really portable. Most |
| 134 |
importantly, it does not work with |pdftex| nor with any other driver |
| 135 |
that produces anything but PostScript code. |
| 136 |
|
| 137 |
Compared to \tikzname, |pstricks| has a similar support base. There |
| 138 |
are many nice extra packages for special purpose situations that have |
| 139 |
been contributed by users over the last decade. The \tikzname\ syntax |
| 140 |
is more consistent than the |pstricks| syntax as \tikzname\ was |
| 141 |
developed ``in a more centralized manner'' and also ``with the |
| 142 |
shortcomings on |pstricks| in mind''. |
| 143 |
\item The |xypic| package is an older package for creating graphics. |
| 144 |
However, it is more difficult to use and to learn because the syntax |
| 145 |
and the documentation are a bit cryptic. |
| 146 |
\item The |dratex| package is a small graphic package for creating a |
| 147 |
graphics. Compared to the other package, including \tikzname, it is |
| 148 |
very small, which may or may not be an advantage. |
| 149 |
\item The |metapost| program is a powerful alternative to \tikzname. It |
| 150 |
used to be an external program, which entailed a bunch of problems, |
| 151 |
but in Lua\TeX\ it is now built in. An obstacle with |metapost| is |
| 152 |
the inclusion of labels. This is \emph{much} easier to achieve using |
| 153 |
\pgfname. |
| 154 |
\item The |xfig| program is an important alternative to \tikzname\ for |
| 155 |
users who do not wish to ``program'' their graphics as is necessary |
| 156 |
with \tikzname\ and the other packages above. There is a conversion |
| 157 |
program that will convert |xfig| graphics to \tikzname. |
| 158 |
\end{enumerate} |
| 159 |
|
| 160 |
|
| 161 |
\subsection{Utility Packages} |
| 162 |
|
| 163 |
The \pgfname\ package comes along with a number of utility package that are not |
| 164 |
really about creating graphics and which can be used independently of \pgfname. |
| 165 |
However, they are bundled with \pgfname, partly out of convenience, partly |
| 166 |
because their functionality is closely intertwined with \pgfname. These utility |
| 167 |
packages are: |
| 168 |
% |
| 169 |
\begin{enumerate} |
| 170 |
\item The |pgfkeys| package defines a powerful key management facility. |
| 171 |
It can be used completely independently of \pgfname. |
| 172 |
\item The |pgffor| package defines a useful |\foreach| statement. |
| 173 |
\item The |pgfcalendar| package defines macros for creating calendars. |
| 174 |
Typically, these calendars will be rendered using \pgfname's graphic |
| 175 |
engine, but you can use |pgfcalendar| also typeset calendars using |
| 176 |
normal text. The package also defines commands for ``working'' with |
| 177 |
dates. |
| 178 |
\item The |pgfpages| package is used to assemble several pages into a |
| 179 |
single page. It provides commands for assembling several ``virtual |
| 180 |
pages'' into a single ``physical page''. The idea is that whenever |
| 181 |
\TeX\ has a page ready for ``shipout'', |pgfpages| interrupts this |
| 182 |
shipout and instead stores the page to be shipped out in a special |
| 183 |
box. When enough ``virtual pages'' have been accumulated in this way, |
| 184 |
they are scaled down and arranged on a ``physical page'', which then |
| 185 |
\emph{really} shipped out. This mechanism allows you to create ``two |
| 186 |
page on one page'' versions of a document directly inside \LaTeX\ |
| 187 |
without the use of any external programs. However, |pgfpages| can do |
| 188 |
quite a lot more than that. You can use it to put logos and watermark |
| 189 |
on pages, print up to 16 pages on one page, add borders to pages, and |
| 190 |
more. |
| 191 |
\end{enumerate} |
| 192 |
|
| 193 |
|
| 194 |
\subsection{How to Read This Manual} |
| 195 |
|
| 196 |
This manual describes both the design of \tikzname\ and its usage. The |
| 197 |
organization is very roughly according to ``user-friendliness''. The commands |
| 198 |
and subpackages that are easiest and most frequently used are described first, |
| 199 |
more low-level and esoteric features are discussed later. |
| 200 |
|
| 201 |
If you have not yet installed \tikzname, please read the installation first. |
| 202 |
Second, it might be a good idea to read the tutorial. Finally, you might wish |
| 203 |
to skim through the description of \tikzname. Typically, you will not need to |
| 204 |
read the sections on the basic layer. You will only need to read the part on |
| 205 |
the system layer if you intend to write your own frontend or if you wish to |
| 206 |
port \pgfname\ to a new driver. |
| 207 |
|
| 208 |
The ``public'' commands and environments provided by the system are described |
| 209 |
throughout the text. In each such description, the described command, |
| 210 |
environment or option is printed in red. Text shown in green is optional and |
| 211 |
can be left out. |
| 212 |
|
| 213 |
|
| 214 |
\subsection{Authors and Acknowledgements} |
| 215 |
\label{section-authors} |
| 216 |
|
| 217 |
The bulk of the \pgfname\ system and its documentation was written by Till |
| 218 |
Tantau. A further member of the main team is Mark Wibrow, who is responsible, |
| 219 |
for example, for the \pgfname\ mathematical engine, many shapes, the decoration |
| 220 |
engine, and matrices. The third member is Christian Feuers\"anger who |
| 221 |
contributed the floating point library, image externalization, extended key |
| 222 |
processing, and automatic hyperlinks in the manual. |
| 223 |
|
| 224 |
Furthermore, occasional contributions have been made by Christophe Jorssen, |
| 225 |
Jin-Hwan Cho, Olivier Binda, Matthias Schulz, Ren\'ee Ahrens, Stephan Schuster, |
| 226 |
and Thomas Neumann. |
| 227 |
|
| 228 |
Additionally, numerous people have contributed to the \pgfname\ system by |
| 229 |
writing emails, spotting bugs, or sending libraries and patches. Many thanks to |
| 230 |
all these people, who are too numerous to name them all! |
| 231 |
|
| 232 |
|
| 233 |
\subsection{Getting Help} |
| 234 |
|
| 235 |
When you need help with \pgfname\ and \tikzname, please do the following: |
| 236 |
|
| 237 |
\begin{enumerate} |
| 238 |
\item Read the manual, at least the part that has to do with your |
| 239 |
problem. |
| 240 |
\item If that does not solve the problem, try having a look at the |
| 241 |
GitHub development page for \pgfname\ and \tikzname\ (see the |
| 242 |
title of this document). Perhaps someone has already reported a |
| 243 |
similar problem and someone has found a solution. |
| 244 |
\item On the website you will find numerous forums for getting help. |
| 245 |
There, you can write to help forums, file bug reports, join mailing |
| 246 |
lists, and so on. |
| 247 |
\item Before you file a bug report, especially a bug report concerning |
| 248 |
the installation, make sure that this is really a bug. In particular, |
| 249 |
have a look at the |.log| file that results when you \TeX\ your |
| 250 |
files. This |.log| file should show that all the right files are |
| 251 |
loaded from the right directories. Nearly all installation problems |
| 252 |
can be resolved by looking at the |.log| file. |
| 253 |
\item \emph{As a last resort} you can try to email me (Till Tantau) or, |
| 254 |
if the problem concerns the mathematical engine, Mark Wibrow. I do |
| 255 |
not mind getting emails, I simply get way too many of them. Because |
| 256 |
of this, I cannot guarantee that your emails will be answered in a |
| 257 |
timely fashion or even at all. Your chances that your problem will |
| 258 |
be fixed are somewhat higher if you mail to the \pgfname\ mailing |
| 259 |
list (naturally, I read this list and answer questions when I have |
| 260 |
the time). |
| 261 |
\end{enumerate} |