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.tex441
1 files changed, 206 insertions, 235 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 ece53e719e6..42493010673 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,280 +10,251 @@
\section{Introduction}
-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
-\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.
+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-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
+\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} 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
- 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\'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\'ezier 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:
+ \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 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.
+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}
-\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.
+\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 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. There is a conversion
- program that will convert |xfig| graphics to \tikzname.
+ \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 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. 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:
+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.
+ \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.
+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.
+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.
+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.
+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.
-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!
+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:
+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
- sourceforge 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 timely
- 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).
+ \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
+ sourceforge 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 timely
+ 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}