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