summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex202
1 files changed, 92 insertions, 110 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex
index 63d6ebeacf7..72dc66db700 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex
@@ -10,54 +10,51 @@
\section{Design Principles}
-This section describes the basic layer of \pgfname. This layer is
-built on top of the system layer. Whereas the system layer just
-provides the absolute minimum for drawing graphics, the basic
-layer provides numerous commands that make it possible to create
-sophisticated graphics easily and also quickly.
-
-The basic layer does not provide a convenient syntax for describing
-graphics, which is left to frontends like \tikzname. For this reason, the
-basic layer is typically used only by ``other programs.'' For example,
-the \textsc{beamer} package uses the basic layer extensively, but does
-not need a convenient input syntax. Rather, speed and flexibility are
-needed when \textsc{beamer} creates graphics.
+This section describes the basic layer of \pgfname. This layer is built on top
+of the system layer. Whereas the system layer just provides the absolute
+minimum for drawing graphics, the basic layer provides numerous commands that
+make it possible to create sophisticated graphics easily and also quickly.
+
+The basic layer does not provide a convenient syntax for describing graphics,
+which is left to frontends like \tikzname. For this reason, the basic layer is
+typically used only by ``other programs''. For example, the \textsc{beamer}
+package uses the basic layer extensively, but does not need a convenient input
+syntax. Rather, speed and flexibility are needed when \textsc{beamer} creates
+graphics.
The following basic design principles underlie the basic layer:
+%
\begin{enumerate}
-\item Structuring into a core and modules.
-\item Consistently named \TeX\ macros for all graphics commands.
-\item Path-centered description of graphics.
-\item Coordinate transformation system.
+ \item Structuring into a core and modules.
+ \item Consistently named \TeX\ macros for all graphics commands.
+ \item Path-centered description of graphics.
+ \item Coordinate transformation system.
\end{enumerate}
-
\subsection{Core and Modules}
-The basic layer consists of a \emph{core package}, called |pgfcore|,
-which provides the most basic commands, and several
-\emph{modules} like commands for plotting (in the |plot| module).
-Modules are loaded using the |\usepgfmodule| command.
-
-If you say |\usepackage{pgf}| or |\input pgf.tex| or
-|\usemodule[pgf]|, the |plot| and |shapes| modules are preloaded (as
-well as the core and the system layer).
+The basic layer consists of a \emph{core package}, called |pgfcore|, which
+provides the most basic commands, and several \emph{modules} like commands for
+plotting (in the |plot| module). Modules are loaded using the |\usepgfmodule|
+command.
+If you say |\usepackage{pgf}| or |\input pgf.tex| or |\usemodule[pgf]|, the
+|plot| and |shapes| modules are preloaded (as well as the core and the system
+layer).
\subsection{Communicating with the Basic Layer via Macros}
-In order to ``communicate'' with the basic layer you use long
-sequences of commands that start with |\pgf|. You are only allowed to
-give these commands inside a |{pgfpicture}| environment. (Note that
-|{tikzpicture}| opens a |{pgfpicture}| internally, so you can freely
-mix \pgfname\ commands and \tikzname\ commands inside a
-|{tikzpicture}|.) It is possible to ``do other things'' between the
-commands. For example, you might use one command to move to a certain
-point, then have a complicated computation of the next point, and then
-move there.
-
+In order to ``communicate'' with the basic layer you use long sequences of
+commands that start with |\pgf|. You are only allowed to give these commands
+inside a |{pgfpicture}| environment. (Note that |{tikzpicture}| opens a
+|{pgfpicture}| internally, so you can freely mix \pgfname\ commands and
+\tikzname\ commands inside a |{tikzpicture}|.) It is possible to ``do other
+things'' between the commands. For example, you might use one command to move
+to a certain point, then have a complicated computation of the next point, and
+then move there.
+%
\begin{codeexample}[]
\newdimen\myypos
\begin{pgfpicture}
@@ -71,94 +68,79 @@ move there.
\end{codeexample}
The following naming conventions are used in the basic layer:
-
+%
\begin{enumerate}
-\item
- All commands and environments start with |pgf|.
-\item
- All commands that specify a point (a coordinate) start with |\pgfpoint|.
-\item
- All commands that extend the current path start with |\pgfpath|.
-\item
- All commands that set/change a graphics parameter start with |\pgfset|.
-\item
- All commands that use a previously declared object (like a path,
- image or shading) start with |\pgfuse|.
-\item
- All commands having to do with coordinate transformations start with
- |\pgftransform|.
-\item
- All commands having to do with arrow tips start with |\pgfarrows|.
-\item
- All commands for ``quickly'' extending or drawing a path start with
- |\pgfpathq| or |\pgfusepathq|.
-\item
- All commands having to do with matrices start with |\pgfmatrix|.
+ \item All commands and environments start with |pgf|.
+ \item All commands that specify a point (a coordinate) start with
+ |\pgfpoint|.
+ \item All commands that extend the current path start with |\pgfpath|.
+ \item All commands that set/change a graphics parameter start with
+ |\pgfset|.
+ \item All commands that use a previously declared object (like a path,
+ image or shading) start with |\pgfuse|.
+ \item All commands having to do with coordinate transformations start with
+ |\pgftransform|.
+ \item All commands having to do with arrow tips start with |\pgfarrows|.
+ \item All commands for ``quickly'' extending or drawing a path start with
+ |\pgfpathq| or |\pgfusepathq|.
+ \item All commands having to do with matrices start with |\pgfmatrix|.
\end{enumerate}
\subsection{Path-Centered Approach}
-In \pgfname\ the most important entity is the \emph{path}. All
-graphics are composed of numerous paths that can be stroked,
-filled, shaded, or clipped against. Paths can be closed or open, they
-can self-intersect and consist of unconnected parts.
-
-Paths are first \emph{constructed} and then \emph{used}. In order to
-construct a path, you can use commands starting with |\pgfpath|. Each
-time such a command is called, the current path is extended in some
-way.
-
-Once a path has been completely constructed, you can use it using the
-command |\pgfusepath|. Depending on the parameters given to this
-command, the path will be stroked (drawn) or filled or subsequent
-drawings will be clipped against this path.
+In \pgfname\ the most important entity is the \emph{path}. All graphics are
+composed of numerous paths that can be stroked, filled, shaded, or clipped
+against. Paths can be closed or open, they can self-intersect and consist of
+unconnected parts.
+Paths are first \emph{constructed} and then \emph{used}. In order to construct
+a path, you can use commands starting with |\pgfpath|. Each time such a command
+is called, the current path is extended in some way.
+Once a path has been completely constructed, you can use it using the command
+|\pgfusepath|. Depending on the parameters given to this command, the path will
+be stroked (drawn) or filled or subsequent drawings will be clipped against
+this path.
\subsection{Coordinate Versus Canvas Transformations}
-
\label{section-design-transformations}
-\pgfname\ provides two transformation systems: \pgfname's own
-\emph{coordinate} transformation matrix and \pdf's or PostScript's
-\emph{canvas} transformation matrix. These two systems are quite
-different. Whereas a scaling by a factor of, say, $2$ of the canvas
-causes \emph{everything} to be scaled by this factor (including
-the thickness of lines and text), a scaling of two in the coordinate
-system causes only the \emph{coordinates} to be scaled, but not the
-line width nor text.
-
-By default, all transformations only apply to the coordinate
-transformation system. However, using the command |\pgflowlevel|
-it is possible to apply a transformation to the canvas.
-
-Coordinate transformations are often preferable over canvas
-transformations. Text and lines that are transformed using canvas
-transformations suffer from differing sizes and lines whose thickness
-differs depending on whether the line is horizontal or vertical. To
-appreciate the difference, consider the following two ``circles'' both
-of which have been scaled in the $x$-direction by a factor of $3$ and
-by a factor of $0.5$ in the $y$-direction. The left circle uses a
-canvas transformation, the right uses \pgfname's coordinate
-transformation (some viewers will render the left graphic incorrectly
-since they do no apply the low-level transformation the way they
-should):
+\pgfname\ provides two transformation systems: \pgfname's own \emph{coordinate}
+transformation matrix and \pdf's or PostScript's \emph{canvas} transformation
+matrix. These two systems are quite different. Whereas a scaling by a factor
+of, say, $2$ of the canvas causes \emph{everything} to be scaled by this factor
+(including the thickness of lines and text), a scaling of two in the coordinate
+system causes only the \emph{coordinates} to be scaled, but not the line width
+nor text.
+
+By default, all transformations only apply to the coordinate transformation
+system. However, using the command |\pgflowlevel| it is possible to apply a
+transformation to the canvas.
+
+Coordinate transformations are often preferable over canvas transformations.
+Text and lines that are transformed using canvas transformations suffer from
+differing sizes and lines whose thickness differs depending on whether the line
+is horizontal or vertical. To appreciate the difference, consider the following
+two ``circles'' both of which have been scaled in the $x$-direction by a factor
+of $3$ and by a factor of $0.5$ in the $y$-direction. The left circle uses a
+canvas transformation, the right uses \pgfname's coordinate transformation
+(some viewers will render the left graphic incorrectly since they do no apply
+the low-level transformation the way they should):
\begin{tikzpicture}[line width=5pt]
- \useasboundingbox (-1.75,-1) rectangle (14,1);
-
- \begin{scope}
- \pgflowlevel{\pgftransformxscale{3}}
- \pgflowlevel{\pgftransformyscale{.5}}
-
- \draw (0,0) circle (0.5cm);
- \draw (.55cm,0pt) node[right] {canvas};
- \end{scope}
- \begin{scope}[xshift=9cm,xscale=3,yscale=.5]
- \draw (0,0) circle (0.5cm);
- \draw (.55cm,0pt) node[right] {coordinate};
- \end{scope}
+ \useasboundingbox (-1.75,-1) rectangle (14,1);
+
+ \begin{scope}
+ \pgflowlevel{\pgftransformxscale{3}}
+ \pgflowlevel{\pgftransformyscale{.5}}
+
+ \draw (0,0) circle (0.5cm);
+ \draw (.55cm,0pt) node[right] {canvas};
+ \end{scope}
+ \begin{scope}[xshift=9cm,xscale=3,yscale=.5]
+ \draw (0,0) circle (0.5cm);
+ \draw (.55cm,0pt) node[right] {coordinate};
+ \end{scope}
\end{tikzpicture}
-