diff options
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.tex | 236 |
1 files changed, 236 insertions, 0 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 new file mode 100644 index 00000000000..fd67dafc38c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex @@ -0,0 +1,236 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + + +\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. The package 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 using \pgfname\ you ``program'' your graphics, just as you +``program'' your document when using \TeX. This means that you get +the advantages of the ``\TeX-approach to typesetting'' also 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: + +\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. Currently, only drivers that produce PostScript or + \textsc{pdf} output are supported and only few of these (hence the + name \emph{portable} graphics format is currently a bit + boastful). However, in principle, the system layer could be ported + to many different drivers quite easily. It should even be possible + to produce, say, \textsc{svg} output in conjunction with + \textsc{tex4ht}. + + 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 way 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 is consists of a \emph{core}, which consists of + several interdependent packages that can only be loaded \emph{en + bloc,} and additional packages that extend the core by more + special-purpose commands like node management or a plotting + interface. For instance, the \textsc{beamer} package uses the core, + but not all of the additional packages of the basic layer. +\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: +\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 + \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. + + + +\subsection{Comparison with Other Graphics Packages} + +There were two main motivations for creating \pgfname: +\begin{enumerate} +\item + The standard \LaTeX\ |{picture}| environment is not powerful enough to + create anything but really simple graphics. 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 portable at all. Most + importantly, it does not work with |pdftex| nor with any other + driver that produces anything but PostScript code. +\end{enumerate} + +The \pgfname\ package is a trade-off between portability and expressive +power. It is not as portable as |{picture}| and perhaps not quite as +powerful as |{pspicture}|. However, it is more powerful than +|{picture}| and more portable than |{pspicture}|. + +\subsection{Utilities: Page Management} + +The \pgfname\ package include a special subpackage called |pgfpages|, +which is used to assemble several pages into a single page. This +package is not really about creating graphics, but it is part of \pgfname\ +nevertheless, mostly because its implementation uses \pgfname\ heavily. + +The subpackage |pgfpages| 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. + + + + +\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 +``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 +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 +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{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 + 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 (the author). 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 + Please, do not phone me in my office. If you need a hotline, buy a + commercial product. +\end{enumerate} + |