summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-introduction.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-introduction.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-introduction.tex261
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}