Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-introduction.tex

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