summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-introduction.tex
diff options
context:
space:
mode:
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.tex261
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}