diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-introduction.tex')
| -rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-introduction.tex | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-introduction.tex b/graphics/pgf/base/doc/pgfmanual-en-introduction.tex new file mode 100644 index 0000000000..36670f4853 --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-introduction.tex @@ -0,0 +1,261 @@ +% 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} |