summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex188
1 files changed, 91 insertions, 97 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex
index 7db4aa68733..ece53e719e6 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex
@@ -10,29 +10,48 @@
\section{Introduction}
-The \pgfname\ package, where ``\pgfname'' is supposed to mean ``portable
-graphics format'' (or ``pretty, good, functional'' if you
-prefer\dots), is a package for creating graphics in an ``inline''
-manner. It defines a number of \TeX\ commands that draw
+Welcome to the documentation of \tikzname\ and the underlying
+\pgfname\ system. What began as a small La\TeX\ style for creating the
+graphics in my (Till Tantau's) PhD thesis directly with pdf\LaTeX\ has now
+grown to become a full-flung 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 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 \pgfname\ you ``program'' your graphics, just
-as you ``program'' your document when you use \TeX. 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.
-
-
-
-\subsection{Structure of the System}
-
-The \pgfname\ system consists of different layers:
+\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 accronym in the tradition of ``\textsc{gnu} is 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 theses 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
@@ -59,74 +78,62 @@ The \pgfname\ system consists of different layers:
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
+ the more basic B\'ezier 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
+ B\'ezier curve support coordinates. Thus, the basic layer provides a
command |\pgfpathcircle| that generates the necessary curve
coordinates for you.
- The basic layer is consists of a \emph{core}, which consists of
+ 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.
-\item[Frontend layer:]
- A frontend (of which there can be several) is a set 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 |tikz| frontend
- all this boils down to a single simple \textsc{metafont}-like
- command:
+\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}
- There are different frontends:
- \begin{itemize}
- \item
- The \tikzname\ frontend is the ``natural'' 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. This frontend is % TODOsp: change all `pstricks' to `PStricks'? (ff)
- \emph{neither} a complete \textsc{metafont} compatibility layer nor
- a \textsc{pstricks} compatibility layer and it is not intended to
- become either.
- \item
- 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.
- \end{itemize}
-
- It would be possible to implement a |pgftricks| frontend that maps
- \textsc{pstricks} commands to \pgfname\ commands. However, I have not
- done this and even if fully implemented, many things that work in
- \pstricks\ will not work, namely whenever some \pstricks\ command
- relies too heavily on PostScript trickery. Nevertheless, such a
- package might be useful in some situations.
-\end{description}
-
-As a user of \pgfname\ you will use the commands of a
-frontend plus perhaps some commands of the basic layer. For this
-reason, this manual explains the frontends first, then the basic
-layer, and finally the system layer.
-
+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 more intended 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}
-\pgfname\ is not the only graphics package for \TeX. In the following,
-I try to give a reasonably fair comparison of the \pgfname-system and
+\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
@@ -138,48 +145,38 @@ other packages.
backend drivers.
\item
The |pstricks| package is certainly powerful enough to create
- any conceivable kind of graphic, but it is not portable at all. Most
+ 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 \pgfname, |pstricks| has a broader support base. There
+ 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.''
-
- Note that a number of neat tricks that |pstricks| can do are
- impossible in \pgfname. In particular, |pstricks| has access to the
- powerful PostScript programming language, which allows trickery
- such as inline function plotting.
\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 \pgfname, it is
+ 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 very powerful alternative to
- \pgfname. However, it is an external program, which entails a
- bunch of problems. The time needed both to create a small graphic
- and also to compile it is much greater than in \pgfname.
- The main problem with |metapost|, however, is the inclusion of
- labels. This is \emph{much} easier to achieve using \pgfname.
+ 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 build 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. Their is a conversion
- program that will convert |xfig| graphics to both \tikzname\ and
- for \pgfname, but it is still under construction.
+ 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
@@ -215,20 +212,20 @@ closely intertwined with \pgfname. These utility packages are:
\subsection{How to Read This Manual}
-This manual describes both the design of the \pgfname\ system and
-its usage. The organization is very roughly according to
+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 \pgfname, please read the installation
+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 |pgf| package
+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.
@@ -289,7 +286,4 @@ following:
somewhat higher if you mail to the \pgfname\ mailing list
(naturally, I read this list and answer questions when I have the
time).
-\item
- Please, do not phone me in my office (unless, of course, you attend
- one of my lectures).
\end{enumerate}