summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex63
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex435
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex428
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex90
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex26
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex18
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex19
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex20
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex884
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex123
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex250
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex340
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex127
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex74
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex306
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex104
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex641
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex473
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex15
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex9
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex57
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex725
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex441
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex577
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex13
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex23
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex39
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-main.tex338
28 files changed, 5681 insertions, 977 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 ef4315b9172..b700cb1db1e 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
@@ -39,38 +39,49 @@ The basic layer consists of a \emph{core package}, called |pgfcore|,
which provides the most basic commands, and several optional package
like |pgfbaseshade| that offer more special-purpose commands.
-You can include the core by saying |\usepackage{pgfcore}| or, as a
-plain \TeX\ user, |\input pgfcore.tex|.
-
-The following optional packages are provided by the basic layer:
-\begin{itemize}
-\item
- |pgfbaseplot| provides commands for plotting functions.
-\item
- |pgfbaseshapes| provides commands for drawing shapes and
- nodes.
-\item
- |pgfbasepatterns| provides commands for declaring and using tiling
- patterns.
-\item
- |pgfbaseimage| provides commands for including external
- images. The |graphicx| package does a much better job at this than
- the |pgfbaseimage| package does, so you should normally use
+\begin{package}{pgfbaseplot}
+ provides commands for plotting functions
+\end{package}
+
+\begin{package}{pgfbaseshapes}
+ provides commands for drawing shapes and nodes
+\end{package}
+
+\begin{package}{pgfbasepatterns}
+ provides commands for declaring and using tiling
+ patterns
+\end{package}
+
+\begin{package}{pgfbaseimage}
+ This package provides commands for including external
+ images. For \LaTeX-users the |graphicx| package does a better job at
+ this than the |pgfbaseimage| package does, so you should normally use
|\includegraphics| and not |\pgfimage|. However, in some situations
(like when masking is needed or when plain \TeX\ is used) this
package is needed.
-\item
- |pgfbaselayers| provides commands for creating layered
+\end{package}
+
+\begin{package}{pgfbaselayers}
+ This package provides commands for creating layered
graphics. Using layers you can later on say that a certain path
should be behind a path that was specified earlier.
-\item
- |pgfbasesnakes| provides commands for adding snaked lines to the
+\end{package}
+
+\begin{package}{pgfbasesnakes}
+ This package provides commands for adding snaked lines to the
path. Such lines are not straight but rather wind in some specific
- fashion.
-\end{itemize}
+ fashion.
+\end{package}
+
+
+\begin{package}{pgfbasematrix}
+ This package provides the |\pgfmatrix| command.
+\end{package}
+
+If you say |\usepackage{pgf}| or |\input pgf.tex| or
+|\usemodule[pgf]|, all of the optional packages are loaded (as well as
+the core and the system layer).
-If you say |\usepackage{pgf}| or |\input pgf.tex|, all of the optional
-packages are loaded (as well as the core and the system layer).
\subsection{Communicating with the Basic Layer via Macros}
@@ -119,6 +130,8 @@ The following naming conventions are used in the basic layer:
\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}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex
new file mode 100644
index 00000000000..83fc1fe0385
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex
@@ -0,0 +1,435 @@
+% Copyright 2007 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{Externalizing Graphics}
+\label{section-external}
+
+
+\subsection{Overview}
+
+There are two fundamentally different ways of inserting graphics into
+a \TeX-document. First, you can create a graphic using some external
+program like |xfig| or |InDesign| and then include this graphic in
+your text. This is done using commands like |\includegraphics| or
+|\pgfimage|. In this case, the graphic file contains all the low-level
+graphic commands that describe the picture. When such a file is
+included, all \TeX\ has to worry about is the size of the picture; the
+internals of the picture are unknown to \TeX\ and it does not care
+about them.
+
+The second method of creating graphics is to use a special package
+that transforms \TeX-commands like |\draw| or |\psline| into
+appropriate low-level graphic commands. In this case, \TeX\ has to do
+all the hard work of ``typesetting'' the picture and if a picture has
+a complicated internal structure this may take a lot of time.
+
+While \pgfname\ was created to facilitate the second method of
+creating pictures, there are two main reasons why you may need to
+employ the first method of image-inclusion, nevertheless:
+
+\begin{enumerate}
+\item Typesetting a picture using \TeX\ can be a very time-consuming
+ process. If \TeX\ needs a minute to typeset a picture, you do not
+ want to wait this minute when you re\TeX\ your document after having
+ changed a single comma.
+\item Some users, especially journal editors, may not be able to
+ process files that contain \pgfname\ commands -- for the simple
+ reason that the systems of many publishing houses do not have
+ \pgfname\ installed.
+\end{enumerate}
+
+In both cases, the solution is to ``extract'' or ``externalize''
+pictures that would normally be typeset every time a document is \TeX
+ed. Once the pictures have been extracted into separate graphics
+files, these graphic files can be reinserted into the text using the
+first method.
+
+Extracting a graphic from a file is not as easy as it may sound at
+first since \TeX\ cannot write parts of its output into different
+files. A bit of trickery is needed and the |pgfbaseimage| package
+provides macros that simplify the following workflow:
+
+\begin{enumerate}
+\item You have to tell \pgfname\ which files will be used for which
+ pictures. To do so, you enclose each picture that you wish to be
+ ``externalized'' in a pair of |\beginpgfgraphicnamed| and
+ |\endpgfgraphicnamed| macros.
+\item The next step is to generate the extracted graphics. For this
+ you run \TeX\ with the |\jobname| set to the graphic file's
+ name. This will cause |\pgfname| to behave in a very special way:
+ All of your document will simply be thrown away, \emph{except} for
+ the single graphic having the same name as the current jobname.
+\item After you have run \TeX\ once for each graphic that your wish to
+ externalize, you can rerun \TeX\ on your document normally. This
+ will have the following effect: Each time a |\beginpgfgraphicnamed|
+ is encountered, \pgfname\ checks whether a graphic file of the given
+ name exists (if you did step 2, it will). If this graphic file
+ exists, it will be input and the text till the corresponding
+ |\endpgfgraphicnamed| will be ignored.
+\end{enumerate}
+
+In the rest of this section, the above workflow is explained in more
+detail.
+
+
+\subsection{Workflow Step 1: Naming Graphics}
+
+In order to put each graphic in an external file, you first need to
+tell \pgfname\ the names of these files. For this, you use a pair of
+commands that are declared in the package |pgfbaseimage|.
+
+\begin{command}{\beginpgfgraphicnamed\marg{file name prefix}}
+ This command indicates that everything up to
+ the next call of |\endpgfgraphicnamed| is part of a graphic that
+ should be placed in a file named \meta{file name
+ prefix}|.|\meta{suffix}, where the \meta{suffix} depends on your
+ backend driver. Typically, \meta{suffix} will be |dvi| or |pdf|.
+
+ Here is a typical example of how this command is used:
+\begin{codeexample}[code only]
+% In file main.tex:
+...
+As we see in Figure~\ref{fig1}, the world is flat.
+\begin{figure}
+ \beginpgfgraphicnamed{graphic-of-flat-world}
+ \begin{tikzpicture}
+ \fill (0,0) circle (1cm);
+ \end{tikzpicture}
+ \endpgfgraphicnamed
+ \caption{The flat world.}
+ \label{fig1}
+\end{figure}
+\end{codeexample}
+
+ Each graphic that is be externalized should have a unique name. Note
+ that this name will be used as the name of a file in the file
+ system, so it should not contain any funny characters.
+
+ This command can have three different effects:
+ \begin{enumerate}
+ \item The easiest situation arises if there does not yet exist a
+ graphic file called \meta{file name prefix}|.|\meta{suffix},
+ where the \meta{suffix} is one of the suffixes understood by your
+ current backend driver (so |pdf| or |jpg| if you use |pdftex|,
+ |eps| if you use |dvips|, and so on). In this case, both this
+ command and the |\endpgfgraphicnamed| command simply have no
+ effect.
+ \item A more complex situation arises when a graphic file named
+ \meta{file name prefix}|.|\meta{suffix} \emph{does} exist. In
+ this case, this graphic file is included using the
+ |\includegraphics| command. Furthermore, the text between
+ |\beginpgfgraphicnamed| and |\endpgfgraphicnamed| is ignored.
+
+ When the text is ``ignored,'' what actually happens is that all
+ text up to the next occurrence of |\endpgfgraphicnamed| is thrown
+ away without any macro expansion. This means, in particular, that
+ (a) you cannot put |\endpgfgraphicnamed| inside a macro and (b)
+ the macros used in the graphics need not be defined at all when
+ the graphic file is included.
+ \item The most complex behaviour arises when current the |\jobname|
+ equals the \meta{file name prefix} and, furthermore, the
+ a \emph{real job name} has been declared. The behaviour for this
+ case is explained later.
+ \end{enumerate}
+
+ Note that the |\beginpgfgraphicnamed| does not really have any
+ effect until you have generated the graphic files named. Till then,
+ this command is simply ignored. Also, if you delete the graphics
+ file later on, the graphics are typeset normally once more.
+\end{command}
+
+\begin{command}{\endpgfgraphicnamed}
+ This command just marks the end of the graphic that should be
+ externalized.
+\end{command}
+
+
+\subsection{Workflow Step 2: Generating the External Graphics}
+
+We have now indicated all the graphics for which we would like graphic
+files to be generated. In order to generate the files, you now need to
+modify the |\jobname| appropriately. This is done in two steps:
+
+\begin{enumerate}
+\item You use the following command to tell \pgfname\ the real name of
+ your |.tex| file:
+ \begin{command}{\pgfrealjobname\marg{name}}
+ Tells \pgfname\ the real name of your job. For instance, if you
+ have a file called |survey.tex| that contains two graphics that
+ you wish to be called |survey-graphic1| and |survey-graphic2|,
+ then you should write the following.
+\begin{codeexample}[code only]
+% This is file survey.tex
+\documentclass{article}
+...
+\usepackage{tikz}
+\pgfrealjobname{survey}
+\end{codeexample}
+ \end{command}
+\item You run \TeX\ with the |\jobname| set to the name of
+the graphic for which you need an external graphic to be generated.
+To set the |\jobname|, you use the |--jobname=| option of \TeX:
+
+\begin{codeexample}[code only]
+bash> latex --jobname=survey-graphic1 survey.tex
+\end{codeexample}
+\end{enumerate}
+
+The following things will now happen:
+\begin{enumerate}
+\item |\pgfrealjobname| notices that the |\jobname|
+ is not the ``real'' jobname and, thus, must be the name of a graphic
+ that is to be put in an external file.
+\item At the beginning of the document, \pgfname\ changes the
+ definition of \TeX's internal |\shipout| macro. The new shipout
+ macro simply throws away the output. This means that the document is
+ typeset normally, but no output is produced.
+\item When the |\beginpgfgraphicnamed{|\meta{name}|}| command is
+ encountered where the \meta{name} is the same as the current
+ |\jobname|, then a \TeX-box is started and \meta{everything} up to the
+ following |\endpgfgraphicnamed| command is stored inside this box.
+
+ Note that, typically, \meta{everything} will contain just a single
+ |{tikzpicture}| or |{pgfpicture}| environment. However, this need
+ not be the case, you use, say, a |{pspicture}| environment as
+ \meta{everything} or even just some normal \TeX-text.
+\item At the |\endpgfgraphicnamed|, the box \emph{is} shipped out
+ using the original |\shipout| command. Thus, unlike everything else,
+ the contents of the graphic is made part of the output.
+\item When the box containing the graphic is shipped out, the paper
+ size is modified such that it exactly equal to the height and width
+ of the box.
+\end{enumerate}
+
+The net effect of everything described above is that the two
+commands
+\begin{codeexample}[code only]
+bash> latex --jobname=survey-graphic1 survey.tex
+bash> dvips survey-graphic1
+\end{codeexample}
+\noindent produce a file called |survey-graphic1.ps| that consists of a single
+page that contains exactly the graphic produced by the code between
+|\beginpgfgraphicnamed{survey-graphic1}| and
+|\endpgfgraphicnamed|. Furthermore, the size of this single page is
+exactly the size of the graphic.
+
+If you use pdf\TeX, producing the graphic is even simpler:
+\begin{codeexample}[code only]
+bash> pdflatex --jobname=survey-graphic1 survey.tex
+\end{codeexample}
+\noindent produces the single-page |pdf|-file |survey-graphic1.pdf|.
+
+\subsection{Workflow Step 3: Including the External Graphics}
+
+Once you have produced all the pictures in the text, including them
+into the main document is easy: Simply run \TeX\ again without any
+modification of the |\jobname|. In this case the
+|\pgfrealjobname| command will notice that the main file is, indeed,
+the main file. The main file will then be typeset normally and the
+|\beginpgfgraphicnamed| commands also behave normally, which means
+that they will try to include the generated graphic files -- which is
+exactly what you want.
+
+Suppose that you wish to send your survey to a journal that does not
+have \pgfname\ installed. In this case, you now have all the necessary
+external graphics, but you still need \pgfname\ to automatically
+include them instead of the executing the picture code! One way to
+solve this problem is to simply delete all of the \pgfname\ or
+\tikzname\ code from your |survey.tex| and instead insert appropriate
+|\includegraphics| commands ``by hand.'' However, there is a better
+way: You input the file |pgfexternal.tex|.
+
+\begin{filedescription}{pgfexternal.tex}
+ This file defines the command |\beginpgfgraphicnamed| and causes it
+ to have the following effect: It includes the graphic file given as
+ a parameter to it and then gobbles everything up to
+ |\endpgfgraphicnamed|.
+
+ Since |\beginpgfgraphicnamed| does not do macro expansion as it
+ searches for |\endpgfgraphicnamed|, it is not necessary to actually
+ include the packages necessary for \emph{creating} the graphics.
+ So the idea is that you comment out things like |\usepackage{tikz}|
+ and instead say |\input pgfexternal.tex|.
+
+ Indeed, the contents of this file is simply the following line:
+\begin{codeexample}[code only]
+\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}}
+\end{codeexample}
+
+ Instead of |\input pgfexternal.tex| you could also include this line
+ in your main file.
+\end{filedescription}
+
+As a final remark, note that the |baseline| option does not work
+together with pictures written to an external graphic file. The simple
+reason is that there is no way to store this baseline information is
+an external graphic file.
+
+
+\subsection{A Complete Example}
+
+Let us now have a look at a simple, but complete example. We start out
+with a normal file called |survey.tex| that has the following
+contents:
+\begin{codeexample}[code only]
+% This is the file survey.tex
+\documentclass{article}
+
+\usepackage{graphics}
+\usepackage{tikz}
+
+\begin{document}
+In the following figure, we see a circle:
+\begin{tikzpicture}
+ \fill (0,0) circle (10pt);
+\end{tikzpicture}
+
+By comparison, in this figure we see a rectangle:
+\begin{tikzpicture}
+ \fill (0,0) rectangle (10pt,10pt);
+\end{tikzpicture}
+\end{document}
+\end{codeexample}
+
+Now our editor tells us that the publisher will need all figures to be
+provided in separate PostScript or |.pdf|-files. For this, we
+enclose all figures in |...graphicnamed|-pairs and we add a call to
+the |\pgfrealjobname| macro:
+\begin{codeexample}[code only]
+% This is the file survey.tex
+\documentclass{article}
+
+\usepackage{graphics}
+\usepackage{tikz}
+\pgfrealjobname{survey}
+
+\begin{document}
+In the following figure, we see a circle:
+\beginpgfgraphicnamed{survey-f1}
+\begin{tikzpicture}
+ \fill (0,0) circle (10pt);
+\end{tikzpicture}
+\endpgfgraphicnamed
+
+By comparison, in this figure we see a rectangle:
+\beginpgfgraphicnamed{survey-f2}
+\begin{tikzpicture}
+ \fill (0,0) rectangle (10pt,10pt);
+\end{tikzpicture}
+\endpgfgraphicnamed
+\end{document}
+\end{codeexample}
+
+After these changes, typesetting the file will still yield the same
+output as it did before -- after all, we have not yet created any
+external graphics.
+
+To create the external graphics, we run |pdflatex| twice, once for
+each graphic:
+\begin{codeexample}[code only]
+bash> pdflatex --jobname=survey-f1 survey.tex
+This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
+entering extended mode
+(./survey.tex
+LaTeX2e <2005/12/01>
+...
+) [1] (./survey-f1.aux) )
+Output written on survey-f1.pdf (1 page, 1016 bytes).
+Transcript written on survey-f1.log.
+\end{codeexample}
+
+\begin{codeexample}[code only]
+bash> pdflatex --jobname=survey-f2 survey.tex
+This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
+entering extended mode
+(./survey.tex
+LaTeX2e <2005/12/01>
+...
+(./survey-f2.aux) )
+Output written on survey-f2.pdf (1 page, 1002 bytes).
+Transcript written on survey-f2.log.
+\end{codeexample}
+
+We can now send the two generated graphics (|survey-f1.pdf| and
+|survey-f2.pdf|) to the editor. However, the publisher cannot use our
+|survey.tex| file, yet. The reason is that it contains the command
+|\usepackage{tikz}| and they do not have \pgfname\ installed.
+
+Thus, we modify the main file |survey.tex| as follows:
+\begin{codeexample}[code only]
+% This is the file survey.tex
+\documentclass{article}
+
+\usepackage{graphics}
+\input pgfexternal.tex
+% \usepackage{tikz}
+% \pgfrealjobname{survey}
+
+\begin{document}
+In the following figure, we see a circle:
+\beginpgfgraphicnamed{survey-f1}
+\begin{tikzpicture}
+ \fill (0,0) circle (10pt);
+\end{tikzpicture}
+\endpgfgraphicnamed
+
+By comparison, in this figure we see a rectangle:
+\beginpgfgraphicnamed{survey-f2}
+\begin{tikzpicture}
+ \fill (0,0) rectangle (10pt,10pt);
+\end{tikzpicture}
+\endpgfgraphicnamed
+\end{document}
+\end{codeexample}
+If we now run pdf\LaTeX, then, indeed, \pgfname\ is no longer needed:
+\begin{codeexample}[code only]
+bash> pdflatex survey.tex
+This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
+entering extended mode
+(./survey.tex
+LaTeX2e <2005/12/01>
+Babel <v3.8h> and hyphenation patterns for english, ..., loaded.
+(/usr/local/gwTeX/texmf.texlive/tex/latex/base/article.cls
+Document Class: article 2005/09/16 v1.4f Standard LaTeX document class
+(/usr/local/gwTeX/texmf.texlive/tex/latex/base/size10.clo))
+(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/graphics.sty
+(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/trig.sty)
+(/usr/local/gwTeX/texmf.texlive/tex/latex/config/graphics.cfg)
+(/usr/local/gwTeX/texmf.texlive/tex/latex/pdftex-def/pdftex.def))
+(/Users/tantau/Library/texmf/tex/generic/pgf/generic/pgf/utilities/pgfexternal.
+tex) (./survey.aux)
+(/usr/local/gwTeX/texmf.texlive/tex/context/base/supp-pdf.tex
+[Loading MPS to PDF converter (version 2006.09.02).]
+) <survey-f1.pdf, id=1, 23.33318pt x 19.99973pt> <use survey-f1.pdf>
+<survey-f2.pdf, id=2, 13.33382pt x 10.00037pt> <use survey-f2.pdf> [1{/Users/ta
+ntau/Library/texmf/fonts/map/pdftex/updmap/pdftex.map} <./survey-f1.pdf> <./sur
+vey-f2.pdf>] (./survey.aux) )</usr/local/gwTeX/texmf.texlive/fonts/type1/bluesk
+y/cm/cmr10.pfb>
+Output written on survey.pdf (1 page, 10006 bytes).
+Transcript written on survey.log.
+\end{codeexample}
+
+To our editor, we send the following files:
+\begin{itemize}
+\item The last |survey.tex| shown above.
+\item The graphic file |survey-f1.pdf|.
+\item The graphic file |survey-f2.pdf|.
+\item The file |pgfexternal.tex|, whose contents is simply
+\begin{codeexample}[code only]
+\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}}
+\end{codeexample}
+ (Alternatively, we can also directly add this line to our
+ |survey.tex| file).
+\end{itemize}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End:
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex
new file mode 100644
index 00000000000..2ac22465b43
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex
@@ -0,0 +1,428 @@
+% Copyright 2006 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{Matrices}
+
+\label{section-base-matrices}
+
+\subsection{Overview}
+
+Matrices are a mechanism for aligning several so-called cell pictures
+horizontally and vertically. The resulting alignment is placed in a
+normal node and the command for creating matrices, |\pgfmatrix|, takes
+options very similar to the |\pgfnode| command.
+
+In the following, the basic idea behind the alignment mechanism is
+explained first. Then the command |\pgfmatrix| is explained. At the
+end of the section additional ways of modifying the width of columns
+and rows is discussed.
+
+
+\subsection{Cell Pictures and Their Alignment}
+
+A matrix consists of rows of \emph{cells}. Cells are separated using
+the special command |\pgfmatrixnextcell|, rows are ended using the
+command |\\|. Each cell contains a \emph{cell picture}, although cell
+pictures are not complete pictures as they lack layers. However, each
+cell picture has its own bouding box like a normal picture does. These
+bounding boxes are important for the alignment as explained
+in the following.
+
+Each cell picture will have an origin somewhere in the picture (or
+even outside the picture). The position of these origins is important
+for the alignment: On each row the origins will be on the same
+horizontal line and for each column the origins will also be on the
+same vertical line. These two requirements mean that the cell pictures
+may need to be shifted around so that the origins wind up on the same
+lines. The top of a row is given by the top of the cell picture whose
+bounding box's maximum $y$-position is largest. Similarly, the bottom
+of a row is given by the bottom of the cell picture whose bounding
+box's minimum $y$-position is the most negative. Similarly, the left
+end of a row is given by the left end of the cell whose bounding box's
+$x$-position is the most negative; and similarly for the right end of
+a row.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[x=3mm,y=3mm,fill=blue!50]
+ \def\atorig#1{\node[black] at (0,0) {\tiny #1};}
+
+ \pgfmatrix{rectangle}{center}{mymatrix}
+ {\pgfusepath{}}{\pgfpointorigin}{}
+ {
+ \fill (0,-3) rectangle (1,1);\atorig1 \pgfmatrixnextcell
+ \fill (-1,0) rectangle (1,1);\atorig2 \pgfmatrixnextcell
+ \fill (-1,-2) rectangle (0,0);\atorig3 \pgfmatrixnextcell
+ \fill (-1,-1) rectangle (0,3);\atorig4 \\
+ \fill (-1,0) rectangle (4,1);\atorig5 \pgfmatrixnextcell
+ \fill (0,-1) rectangle (1,1);\atorig6 \pgfmatrixnextcell
+ \fill (0,0) rectangle (1,4);\atorig7 \pgfmatrixnextcell
+ \fill (-1,-1) rectangle (0,0);\atorig8 \\
+ }
+\end{tikzpicture}
+\end{codeexample}
+
+
+\subsection{The Matrix Command}
+
+All matrices are typeset using the following command:
+
+\begin{command}{\pgfmatrix\marg{shape}\marg{anchor}\marg{name}%
+ \marg{usage}\marg{shift}\marg{pre-code}\marg{matrix cells}}
+
+ This command creates a node that contains a matrix. The name of the
+ node is \meta{name}, its shape is \meta{shape} and the node is
+ anchored at \meta{anchor}.
+
+ The \meta{matrix cell} parameter contains the cells of the
+ matrix. In each cell drawing commands may be given, which create a
+ so-called cell picture. For each cell picture a bounding box is
+ computed and the cells are aligned according to the rules outlined
+ in the previous section.
+
+ The resulting matrix is used as the |text| box of the node. As for a
+ normal node, the \meta{usage} commands are applied, so that the
+ path(s) of the resulting node are stroked or filled or whatever.
+
+ \medskip
+ \textbf{Specifiying the cells and rows.\ }
+ Even though this command uses |\halign| internally, there are two
+ special rules for indicating cells:
+ \begin{enumerate}
+ \item Cells in the same row must be separated using the macro
+ |\pgfmatrixnextcell| rather than |&|. Using |&| will result in an
+ error message.
+
+ However, you can make |&| an active character and have it expand
+ to |\pgfmatrixnextcell|. This way, it will ``look'' as if |&| is
+ used.
+ \item Every row \emph{including the last row} must be ended using
+ the command |\\|.
+ \end{enumerate}
+
+ Both |\pgfmatrixnextcell| and |\\| take an optional argument as
+ explained in the Section~\ref{section-matrix-spacing}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \pgfmatrix{rectangle}{center}{mymatrix}
+ {\pgfusepath{}}{\pgfpointorigin}{}
+ {
+ \node {a}; \pgfmatrixnextcell \node {b}; \\
+ \node {c}; \pgfmatrixnextcell \node {d}; \\
+ }
+\end{tikzpicture}
+\end{codeexample}
+
+ \medskip
+ \textbf{Anchoring matrices at nodes inside the matrix.\ }
+ The parameter \meta{shift} is an additional negative shift for the
+ node. Normally, such a shift could be given beforehand (that is, the
+ shift could be preapplied to the current transformation
+ matrix). However, when \meta{shift} is evaluated, you can refer to
+ \emph{temporary} positions of nodes inside the matrix. In detail,
+ the following happens: When the matrix has been typeset, all nodes
+ in the matrix temporarily get assigned their positions in the matrix
+ box. The origin of this coordinate system is at the left baseline
+ end of the matrix box, which corresponds to the |text| anchor. The
+ position \meta{shift} is then interpreted inside this coordinate
+ system and then used for shifting.
+
+ This allows you to use the parameter \meta{shift} in the following
+ way: If you use |text| as the \meta{anchor} and specify
+ |\pgfpointanchor{inner node}{some anchor}| for the parameter
+ \meta{shift}, where |inner node| is a node that
+ is created in the matrix, then the whole matrix will be shifted such
+ that |inner node.some anchor| lies at the origin of the whole
+ picture.
+
+ \medskip
+ \textbf{Rotations and scaling.\ }
+ The matrix node is never rotated or shifted, because the current
+ coordinate transformation matrix is reset (except for the
+ translational part) at the beginning of |\pgfmatrix|. This is
+ intentional and will not change in the future. If you need to rotate
+ the matrix, you must install an appropriate canvas transformation
+ yourself.
+
+ However, nodes and stuff inside the cell pictures can be rotated and
+ scaled normally.
+
+ \medskip
+ \textbf{Callbacks.\ }
+ At the beginning and at the end of each cell the special macros
+ |\pgfmatrixbegincode|, |\pgfmatrixendcode| and possibly
+ |\pgfmatrixemptycode| are called. The effect is explained in
+ Section~\ref{section-matrix-callbacks}.
+
+ \medskip
+ \textbf{Executing extra code.\ }
+ The parameter \meta{pre-code} is executed at the beginning of the
+ outermost \TeX-group enclosing the matrix node. It is inside this
+ \TeX-group, but outside the matrix itself. It can be used
+ for different purposes:
+ \begin{enumerate}
+ \item It can be used to simplify the next cell macro. For example,
+ saying |\let\&=\pgfmatrixnextcell| allows you to use |\&| instead
+ of |\pgfmatrixnextcell|. You can also set the catcode of |&| to
+ active.
+ \item It can be used to issue an |\aftergroup| command. This allows
+ you to regain control after the |\pgfmatrix| command. (If you do
+ not know the |\aftergroup| command, you are probably blessed with
+ a simple and happy life.)
+ \end{enumerate}
+
+ \medskip
+ \textbf{Special considerations concerning macro expansion.\ }
+ As said before, the matrix is typeset using |\halign|
+ internally. This command does a lot of strange and magic things like
+ expanding the first macro of every cell in a most unusual
+ manner. Here are some effects you may wish to be aware of:
+ \begin{itemize}
+ \item It is not necessary to actually mention |\pgfmatrixnextcell|
+ or |\\| inside the \meta{matrix cells}. It suffices that the
+ macros inside \meta{matrix cells} expand to these macros sooner or
+ later.
+ \item In particular, you can define clever macros that insert
+ columns and rows as needed for special effects.
+ \end{itemize}
+\end{command}
+
+
+\subsection{Row and Column Spacing}
+\label{section-matrix-spacing}
+
+It is possible to control the space between columns and rows rather
+detailedly. Two commands are important for the row spacing and two
+commands for the column spacing.
+
+\begin{command}{\pgfsetmatrixcolumnsep\marg{sep list}}
+ This macro sets the default separation list for columns. The details of the
+ format of this list are explained in the description of the next command.
+\end{command}
+
+\begin{command}{\pgfmatrixnextcell\opt{\oarg{additional sep list}}}
+ This command has two puposes: First, it is used to separate
+ cells. Second, by providing the optional argument \meta{additional
+ sep list} you can modify the spacing between the columns that are
+ separated by this command.
+
+ The optional \meta{additional sep list} may only be provided when
+ the |\pgfmatrixnextcell| command starts a new column. Normally, this
+ will only be the case in the first row, but sometimes a later row
+ has more elements than the first row. In this case, the
+ |\pgfmatrixnextcell| commands that start the new columns in the
+ later row may also have the optional argument. Once a column has
+ been started, subsequent uses of this optional argument for the
+ column have no effect.
+
+ To determine the space between the two columns the are separated by
+ |\pgfmatrixnextcell|, the following algorithm is executed:
+ \begin{enumerate}
+ \item Both the default separation list (as setup by
+ |\pgfsetmatrixcolumnsep|) and the \meta{additional sep list} are
+ processed, in this order. If the \meta{additional sep list}
+ argument is missing, only the default separation list is
+ processed.
+ \item Both lists may contain dimensions, separated by commas, as
+ well as occurences of the keywords |between origins| and
+ |between borders|.
+ \item All dimensions occuring in either list are added together to
+ arrive at an dimension $d$.
+ \item The last occurence of either of the keywords is located. If
+ neither keyword is present, we proceed as if |between borders|
+ were present.
+ \end{enumerate}
+ At the end of the algorithm, a dimension $d$ has been computed and
+ one of the two \emph{modes} |between borders| and |between origins|
+ has been determined. Depending on which mode has been determined,
+ the following happens:
+ \begin{itemize}
+ \item For the |between borders| mode, an additional horizontal space
+ of $d$ is added between the two columns. Note that $d$ may be
+ negative.
+ \item For the |between origins| mode, the spacing between the two
+ columns is computed differently: Recall that the origins of the
+ cell pictures in both pictures lie on two vertical lines. The
+ spacing between the two columns is setup such that the horizontal
+ distance between these two lines is exactly $d$.
+
+ This mode may only be used between columns \emph{already
+ introduced in the first row}.
+ \end{itemize}
+ All of the above rules boil down to the following effects:
+ \begin{itemize}
+ \item A default spacing between columns should be setup using
+ |\pgfsetmatrixcolumnsep|. For example, you might say
+ |\pgfsetmatrixcolumnsep{5pt}| to have columns be spaced apart by
+ |5pt|. You could say
+\begin{verbatim}
+\pgfsetmatrixcolumnsep{1cm,between origins}
+\end{verbatim}
+ to specify that horizontal space between the origins of cell
+ pictures in adjacent columns should be 1cm by default --
+ regardless of the actual size of the cell pictures.
+ \item You can now use the optional argument of |\pgfmatrixnextcell|
+ to locally overrule the spacing between two columns. By saying
+ |\pgfmatrixnextcell[5pt]| you \emph{add} 5pt to the space between
+ of the two columns, regadless of the mode.
+
+ You can also (locally) change the spacing mode for these two
+ columns. For example, even if the normal spacing mode is
+ |between origins|, you can say
+\begin{verbatim}
+\pgfmatrixnextcell[5pt,between borders]
+\end{verbatim}
+ to locally change the mode for these columns to
+ |between borders|.
+ \end{itemize}
+
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every node}=[draw]
+ \pgfsetmatrixcolumnsep{1mm}
+ \pgfmatrix{rectangle}{center}{mymatrix}
+ {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
+ {
+ \node {8}; \&[2mm] \node{1}; \&[-1mm] \node {6}; \\
+ \node {3}; \& \node{5}; \& \node {7}; \\
+ \node {4}; \& \node{9}; \& \node {2}; \\
+ }
+\end{tikzpicture}
+ \end{codeexample}
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every node}=[draw]
+ \pgfsetmatrixcolumnsep{1mm}
+ \pgfmatrix{rectangle}{center}{mymatrix}
+ {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
+ {
+ \node {8}; \&[2mm] \node(a){1}; \&[1cm,between origins] \node(b){6}; \\
+ \node {3}; \& \node {5}; \& \node {7}; \\
+ \node {4}; \& \node {9}; \& \node {2}; \\
+ }
+ \tikzstyle{every node}=[]
+ \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {11mm};
+\end{tikzpicture}
+ \end{codeexample}
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every node}=[draw]
+ \pgfsetmatrixcolumnsep{1cm,between origins}
+ \pgfmatrix{rectangle}{center}{mymatrix}
+ {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
+ {
+ \node (a) {8}; \& \node (b) {1}; \&[between borders] \node (c) {6}; \\
+ \node {3}; \& \node {5}; \& \node {7}; \\
+ \node {4}; \& \node {9}; \& \node {2}; \\
+ }
+ \tikzstyle{every node}=[]
+ \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm};
+ \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway] {10mm};
+\end{tikzpicture}
+ \end{codeexample}
+\end{command}
+
+The mechanism for the between-row-spacing is the same, only the
+commands are called differently.
+
+
+\begin{command}{\pgfsetmatrixrowsep\marg{sep list}}
+ This macro sets the default separation list for rows.
+\end{command}
+
+
+
+\begin{pgfmanualentry}
+ \pgfmanualentryheadline{\declare{\doublebs}\opt{\oarg{additional sep list}}}
+ \index{*bs@\protect\doublebs}
+ \pgfmanualbody
+ This command ends a line. The optional \meta{additional sep list} is
+ used to determine the spacing between the row being ended and the
+ next row. The modes and the computation of $d$ is done in the same
+ way as for columns. For the last row the optional argument has no
+ effect.
+
+ This command is defined in this special way only inside matrices.
+\end{pgfmanualentry}
+
+\subsection{Callbacks}
+\label{section-matrix-callbacks}
+
+There are three macros that get called at the beginning and end of
+cells. By redefining these macros, which are empty by default, you can
+change the appearance of cells in a very general manner.
+
+\begin{command}{\pgfmatrixemptycode}
+ This macro is executed for empty cells. This means that \pgfname\
+ uses some macro magic to determine whether a cell is empty (it
+ immediatly ends with |\pgfmatrixemptycode| or |\\|) and, if so, put
+ this macro inside the cell.
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \def\pgfmatrixemptycode{\node{empty};}
+ \pgfmatrix{rectangle}{center}{mymatrix}
+ {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
+ {
+ \node {a}; \& \& \node {b}; \\
+ \& \node{c}; \& \node {d}; \& \\
+ }
+\end{tikzpicture}
+ \end{codeexample}
+ As can be seen, the macro is not executed for empty cells at the end
+ of row when columns are added only later on.
+\end{command}
+
+
+\begin{command}{\pgfmatrixbegincode}
+ This macro is executed at the beginning of non-empty
+ cells. Correspondingly, |\pgfmatrixendcode| is added at
+ the end of every non-empty cell.
+ \begin{codeexample}[]
+\begin{tikzpicture}
+ \def\pgfmatrixbegincode{\node[draw]\bgroup}
+ \def\pgfmatrixendcode{\egroup;}
+ \pgfmatrix{rectangle}{center}{mymatrix}
+ {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
+ {
+ a \& b \& c \\
+ d \& \& e \\
+ }
+\end{tikzpicture}
+ \end{codeexample}
+ Note that between |\pgfmatrixbegincode| and |\pgfmatrixendcode|
+ there will \emph{not} only be the contents of the cell. Rather,
+ \pgfname\ will add some (invisible) commands for book-keeping
+ purposes that involve |\let| and |\gdef|. In particular, it is not a
+ good idea to have |\pgfmatrixbegincode| end with |\csname| and
+ |\pgfmatrixendcode| start with |\endcsname|.
+\end{command}
+
+\begin{command}{\pgfmatrixendcode}
+ See the explanation above.
+\end{command}
+
+
+The following two counters allow you to access the current row and
+current column in a callback:
+
+\begin{command}{\pgfmatrixcurrentrow}
+ This counter stores the current row of the current cell of the
+ matrix. Do not even think of changing this counter.
+\end{command}
+
+\begin{command}{\pgfmatrixcurrentcolumn}
+ This counter stores the current column of the current cell of the
+ matrix.
+\end{command}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End:
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
index 95b59642c19..13d1ff21419 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex
@@ -23,62 +23,11 @@ This section describes the |pgfbaseplot| package.
\subsection{Overview}
-\subsubsection{When Should One Use PGF for Generating Plots? }
-
-There exist many powerful programs that produce plots, examples are
-\textsc{gnuplot} or \textsc{mathematica}. These programs can produce
-two different kinds of output: First, they can output a complete plot
-picture in a certain format (like \pdf) that includes all low-level
-commands necessary for drawing the complete plot (including axes and
-labels). Second, they can usually also produce ``just plain data'' in
-the form of a long list of coordinates. Most of the powerful programs
-consider it a to be ``a bit boring'' to just output tabled data and
-very much prefer to produce fancy pictures. Nevertheless, when coaxed,
-they can also provide the plain data.
-
-The plotting mechanism described in the following deals only with
-plotting data given in the form of a list of coordinates. Thus, this
-section is about using \pgfname\ to turn lists of coordinates into
-plots.
-
-\emph{Note that is often not necessary to use \pgfname\ for this.}
-Programs like \textsc{gnuplot} can produce very sophisticated plots
-and it is usually much easier to simply include these plots as a
-finished \textsc{pdf} or PostScript graphics.
-
-However, there are a number of reasons why you may wish to invest time
-and energy into mastering the \pgfname\ commands for creating plots:
-
-\begin{itemize}
-\item
- Virtually all plots produced by ``external programs'' use different
- fonts from the one used in your document.
-\item
- Even worse, formulas will look totally different, if they can be
- rendered at all.
-\item
- Line width will usually be too large or too small.
-\item
- Scaling effects upon inclusion can create a mismatch between sizes
- in the plot and sizes in the text.
-\item
- The automatic grid generated by most programs is mostly
- distracting.
-\item
- The automatic ticks generated by most programs are cryptic
- numerics. (Try adding a tick reading ``$\pi$'' at the right point.)
-\item
- Most programs make it very easy to create ``chart junk'' in a most
- convenient fashion. All show, no content.
-\item
- Arrows and plot marks will almost never match the arrows used in the
- rest of the document.
-\end{itemize}
-
-The above list is not exhaustive, unfortunately.
-
-
-\subsubsection{How PGF Handles Plots}
+There are different reasons for using \pgfname\ for creating plots
+rather than some more powerful program such as \textsc{gnuplot} or
+\textsc{mathematica}, as discussed in
+Section~\ref{section-why-pgname-for-plots}. So, let us assume that --
+for whatever reason -- you wish to use \pgfname\ for generating a plot.
\pgfname\ (conceptually) uses a two-stage process for generating
plots. First, a \emph{plot stream} must be produced. This stream
@@ -211,6 +160,35 @@ should be used. However, it would not be terribly difficult to write a
intelligently.
+\begin{command}{\pgfplotfunction\marg{variable}\marg{sample list}\marg{point}}
+ This command will produce coordinates by iterating the
+ \meta{variable} over all values in \meta{sample list}, which should
+ be a list in the |\foreach| syntax. For each value of
+ \meta{variable}, the \meta{point} is evaluated and the resulting
+ coordinate is inserted into the plot stream.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[x=3.8cm/360]
+ \pgfplothandlerlineto
+ \pgfplotfunction{\x}{0,5,...,360}{\pgfpointxy{\x}{sin(\x)+sin(3*\x)}}
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}[y=3cm/360]
+ \pgfplothandlerlineto
+ \pgfplotfunction{\y}{0,5,...,360}{\pgfpointxyz{sin(2*\y)}{\y}{cos(2*\y)}}
+ \pgfusepath{stroke}
+\end{tikzpicture}
+\end{codeexample}
+
+ Be warnded that if the expressions that need to evaluated for each
+ point are complex, then this command can be very slow.
+\end{command}
+
+
+
\begin{command}{\pgfplotgnuplot\oarg{prefix}\marg{function}}
This command will ``try'' to call the \textsc{gnuplot} program to
generate the coordinates of the \meta{function}. In detail, the
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex
index c8a38014dba..572e262dc50 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex
@@ -211,18 +211,20 @@ using spherical and cylindrical coordinates.
the $xy$-plane.
\begin{codeexample}[]
\begin{tikzpicture}
- \draw [->] (0,0) -- (1,0,0) node [right] {$x$};
- \draw [->] (0,0) -- (0,1,0) node [above] {$y$};
- \draw [->] (0,0) -- (0,0,1) node [below left] {$z$};
-
- \foreach \angle in {0,10,...,90}
- {\pgfpathcircle{\pgfpointspherical{\angle}{0}{1}}{2pt}}
- \pgfusepath{fill}
-
- \pgfsetcolor{red}
- \foreach \angle in {0,10,...,90}
- {\pgfpathcircle{\pgfpointspherical{80}{\angle}{1}}{2pt}}
- \pgfusepath{fill}
+ \pgfsetfillcolor{lightgray}
+
+ \foreach \latitude in {-90,-75,...,30}
+ {
+ \foreach \longitude in {0,20,...,360}
+ {
+ \pgfpathmoveto{\pgfpointspherical{\longitude}{\latitude}{1}}
+ \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude}{1}}
+ \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude+15}{1}}
+ \pgfpathlineto{\pgfpointspherical{\longitude}{\latitude+15}{1}}
+ \pgfpathclose
+ }
+ \pgfusepath{fill,stroke}
+ }
\end{tikzpicture}
\end{codeexample}
\end{command}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
index f90ed614363..6c0bc68d1d4 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
@@ -610,6 +610,24 @@ user.
\end{contextenvironment}
+
+\begin{environment}{{pgfinterruptboundingbox}}
+ This environment temporarily interrupts the computation of the
+ bounding box and sets up a new bounding box. At the beginning of the
+ environment the old bounding box is saved and an empty bounding box
+ is installed. After the environment the orginal bounding box is
+ reinstalled as if nothing has happened.
+\end{environment}
+
+\begin{plainenvironment}{{pgfinterruptboundingbox}}
+ Plain \TeX\ version of the environment.
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfinterruptboundingbox}}
+ Con\TeX t version of the environment.
+\end{contextenvironment}
+
+
\subsubsection{Inserting Text and Images}
\label{section-text-command}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex
index 0fc8c076b9d..163bf835abf 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex
@@ -49,14 +49,19 @@ include files in the directory |generic/pgf|. For example, here is the
content of the file |latex/pgf/frontends/tikz.sty|:
\begin{codeexample}[code only]
-% Copyright 2005 by Till Tantau <tantau@users.sourceforge.net>.
+% Copyright 2006 by Till Tantau
+%
+% This file may be distributed and/or modified
+%
+% 1. under the LaTeX Project Public License and/or
+% 2. under the GNU Public License.
%
-% This program can be redistributed and/or modified under the terms
-% of the GNU Public License, version 2.
+% See the file doc/generic/pgf/licenses/LICENSE for more details.
-\RequirePackage{pgf,calc,pgffor,pgflibraryplothandlers,xkeyval}
-\input{tikz.code}
+\RequirePackage{pgf,calc,pgffor,xkeyval}
+
+\input{tikz.code.tex}
\endinput
\end{codeexample}
@@ -336,6 +341,8 @@ graphic in your text.
\item
Unlike for other output formats, the bounding box of a picture
``really crops'' the picture.
+ \item
+ Matrices do not work.
\end{enumerate}
The driver basically works as follows: When a |{pgfpicture}| is
@@ -376,7 +383,7 @@ graphic in your text.
Note that, say, even filling is not supported! (Let alone color or
anything fancy.)
- This driver has only one real applications: It might be useful when
+ This driver has only one real application: It might be useful when
you only need horizontal or vertical lines in a picture. Then, the
results are quite satisfactory.
\end{filedescription}
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 826648cb9ec..7bd8de69275 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
@@ -164,8 +164,8 @@ other packages.
very small, which may or may not be an advantage.
\item
The |metapost| program is a very powerful alternative to
- \pgfname. However, it is an external program, which entails a whole
- bunch on problems. The time needed both to create a small graphics
+ \pgfname. However, it is an external program, which entails a
+ bunch of problems. The time needed both to create a small graphic
and also to compile it is much greater than in \pgfname.
The main problem with |metapost|, however, is the inclusion of
labels. This is \emph{much} easier to achieve using \pgfname.
@@ -225,6 +225,15 @@ 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. The \pgfname\ mathematical engine was written and
+documented by Mark Wibrow. Additionally, numerous people have
+contributed to the \pgfname\ system by writing emails, spotting bugs,
+or sending libraries. Many thanks to all these people, who are too
+numerous to name them all!
\subsection{Getting Help}
@@ -251,7 +260,8 @@ following:
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
+ \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
@@ -259,7 +269,7 @@ following:
(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.
+ Please, do not phone me in my office (unless, of course, you attend
+ one of my lectures).
\end{enumerate}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex
new file mode 100644
index 00000000000..fda9a875d75
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex
@@ -0,0 +1,884 @@
+% Copyright 2006 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{Calendar Library}
+
+\label{section-calender-snakes}
+
+\begin{tikzlibrary}{calendar}
+ The library defines the |\calendar| command, which can be used to
+ typeset calendars. The command relies on the |\pgfcalendar| command
+ from the |pgfcalendar| package, which is loaded automatically.
+
+ The |\calendar| command is quite configurable, allowing you to
+ produce all kinds of different calendars.
+\end{tikzlibrary}
+
+
+\subsection{Calendar Command}
+
+The core command for creating calendars in \tikzname\ is the
+|\calendar| command. It is available only inside |{tikzpicture}|
+environments (similar to, say, the |\draw| command).
+
+\begin{command}{\calendar \meta{calendar specification}|;|}
+ The syntax for this command is similar to commands like |\node| or
+ |\matrix|. However, it has its complete own parser and only those
+ commands described in the following will be recognized, nothing
+ else. Note, furthermore, that a \meta{calendar specification} is not
+ a path specification, indeed, no path is created for the calendar.
+
+ \medskip
+ \textbf{The specification syntax.}
+ The \meta{calendar specification} must be a sequence of
+ elements, each of which has one of the following structures:
+ \begin{itemize}
+ \item |[|\meta{options}|]|
+
+ You provide \meta{options} in square brackets as
+ in |[red,draw=none]|. These \meta{options} can be any \tikzname\
+ option and they apply to the whole calendar. You can provide this
+ element multiple times, the effect accumulates.
+ \item |(|\meta{name}|)|
+
+ This has the same effect as saying |[name=|\meta{name}|]|. The
+ effect of providing a \meta{name} is explained later. Note
+ alreadys that \emph{a calendar is not a node} and the \meta{name}
+ is \emph{not the name of a node}.
+ \item |at (|\meta{coordinate}|)|
+
+ This has the same effect as saying |[at=(|\meta{coordinate}|)]|.
+ \item |if (|\meta{date condition}|)| \meta{options or
+ commands}\opt{|else|\meta{else options or commands}}
+
+ The effect of such an |if| is explained later.
+ \end{itemize}
+
+ At the beginning of every calendar, the following style is used:
+ \begin{itemize}
+ \itemstyle{every calendar} This style is empty be default.
+ \end{itemize}
+
+ \medskip
+ \textbf{The date range.}
+ The overall effect of the |\calendar| command is to execute code for
+ each day of a range of dates. This range of dates is set using the
+ following option:
+ \begin{itemize}
+ \itemoption{dates}|=|\meta{start date}| to |\meta{end date} This
+ option specifies the date range. Both the start and end date are
+ specified as described on page~\pageref{calendar-date-format}. In
+ short: You can provide ISO-format type dates like |2006-01-02|, you
+ can replace the day of month by |last| to refer to the last day of a
+ month (so |2006-02-last| is the same as |2006-02-28|), and you can
+ add a plus sign followed by a number to specify an offset (so
+ |2006-01-01+-1| is the same as |2005-12-31|).
+ \end{itemize}
+ It will be useful to fix two pieces of terminology for the following
+ descriptions: The |\calendar| command iterates over the dates in the
+ range. The \emph{current date} refers to the current date the
+ command is processing as it iterates over the dates. For each
+ current date code is executed, which will be called the
+ \emph{current date code}. The current date code consists of
+ different parts, to be detailed later.
+
+ The central part of the current date code is the execution of the
+ code |\tikzdaycode|. By default, this code simply produces a node
+ whose text is set to the day of month. This means that unless further
+ action is taken, all days of a calendar will be put on top of each
+ other! To avoid this, you must modify the current date code to shift
+ days around appropriately. Predefined arrangements like
+ |day list downward| or |week list| do this for you, but you can
+ define arrangements yourself. Since defining an arrangement is a bit
+ tricky, it is explained only later on. For the time being, let us
+ use a predefined arrangement to produce our first calendar:
+
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list];
+\end{codeexample}
+
+ \medskip
+ \textbf{Changing the spacing.}
+ In the above calendar, the spacing between the days is determined by
+ the numerous options. Most arrangement do not use all of these
+ options, but only those that apply naturally.
+ \begin{itemize}
+ \itemoption{day xshift}|=|\meta{dimension} specifies the
+ horizontal shift between days. This is not the gap between days,
+ but the shift between the anchors of their nodes. The default is
+ |3.5ex|.
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day xshift=3ex];
+\end{codeexample}
+ \itemoption{day yshift}|=|\meta{dimension} specifies the
+ vertical shift between days. Again, this is the shift between the
+ anchors of their nodes. The default is |3ex|.
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day yshift=2ex];
+\end{codeexample}
+ \itemoption{month xshift}|=|\meta{dimension} specifies an
+ additional horizontal shift between different months.
+ \itemoption{month yshift}|=|\meta{dimension} specifies an
+ additional vertical shift between different months.
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
+ month yshift=0pt];
+\end{codeexample}
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
+ month yshift=1cm];
+\end{codeexample}
+ \end{itemize}
+
+ \medskip
+ \textbf{Changing the position of the calendar.}
+ The calendar is placed in such a way that, normally, the anchor of
+ the first day label is at the origin. This can be changed by using
+ the |at| option. When you say |at={(1,1)}|, this anchor of the first
+ day will lie at coordinate $(1,1)$.
+
+ In general, arrangements will not always place the anchor of the
+ first day at the origin. Sometimes, additional spacing rules get in
+ the way. There are different ways of addressing this problem: First,
+ you can just ignore it. Since calendars are often placed in their own
+ |{tikzpicture}| and since their size if computed automatically, the
+ exact position of the origin often does not matter at all. Second,
+ you can put the calendar inside a node as in
+ |...node {\tikz \calendar...}|. This allows you to position the node
+ in the normal ways using the node's anchors. Third, you can be very
+ clever and use a single-cell matrix. The advantage is that a matrix
+ allows you to provide any anchor of any node inside the matrix as an
+ anchor for the whole matrix. For example, the following calendar is
+ placed in such a way the center of 2000-01-20 lies on the position
+ $(2,2)$:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+ \matrix [anchor=cal-2000-01-20.center] at (2,2)
+ { \calendar(cal)[dates=2000-01-01 to 2000-01-31,week list]; \\};
+\end{tikzpicture}
+\end{codeexample}
+ Unfortunately, the matrix-base positions, which is the cleanest way,
+ isnot as portable as the other approaches (it currently does not
+ work with the \textsc{svg} backend for instance).
+
+ \medskip
+ \textbf{Changing the appearance of days.}
+ As mentioned before, each day in the above calendar is produced by
+ an execution of the |\tikzdaycode|. Each time this code is executed,
+ the coordinate system will have been setup appropriately to place
+ the day of the month correctly. You can change both the code and its
+ appearance using the following options.
+ \begin{itemize}
+ \itemoption{day code}|=|\meta{code}
+ This option allows you to change the code that is executed for
+ each day. The default is to create a node with an appropriate
+ name, but you can change this:
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
+ day code={\fill[blue] (0,0) circle (2pt);}];
+\end{codeexample}
+ The default code is the following:
+\begin{codeexample}[code only]
+\node[name=\pgfcalendarsuggestedname,every day]{\tikzdaytext};
+\end{codeexample}
+ The first part causes the day nodes to be accessible via the
+ following names: If \meta{name} is the name given to the calendar
+ via a |name=| option or via the specification element
+ |(|\meta{name}|)|, then |\pgfcalendarsuggestedname| will expand to
+ \meta{name}|-|\meta{date}, where \meta{date} is the date of the
+ day that is currently being processed in ISO format .
+
+ For example, if January 1, 2006 is being processed and the
+ calendar has been named |mycal|, then the node containg the |1|
+ for this date will be names |mycal-2006-01-01|. You can later
+ reference this node.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \calendar (mycal) [dates=2000-01-01 to 2000-01-31,week list];
+
+ \draw[red] (mycal-2000-01-20) circle (4pt);
+\end{tikzpicture}
+\end{codeexample}
+
+ \itemoption{day text}|=|\meta{text}
+ This option changes the setting of the |\tikzdaytext|. By default,
+ this macro simply yields the current day of month, but you can
+ change it arbitrarily. Here is a silly example:
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
+ day text=x];
+\end{codeexample}
+ More useful examples are based on using the |\%| command. This
+ command is redefined inside a |\pgfcalendar| to mean the same as
+ |\pgfcalendarshorthand|. (The original meaning of |\%| is lost
+ inside the calendar, you need to save if before the calendar if
+ you really need it.)
+
+ The |\%| inserts the current day/month/year/day of week in a
+ certain format into the text. The first letter following the |\%|
+ selects the type (permisslbe values are |d|, |m|, |y|, |w|), the
+ second letter specifies how the value should be displayed (|-|
+ means numerically, |=| means numerically with leading
+ space, |0| means numerically with leading zeros, |t| means
+ textual, and |.| means textual, abbreviated). For example |\%d0|
+ gives the day with a leading zero (for more details see
+ the description of |\pgfcalendarshorthand| on
+ page~\pageref{pgfcalendarshorthand}).
+
+ Let us redefine the |day text| so that it yields the day with a
+ leading zero:
+\begin{codeexample}[leave comments]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
+ day text=\%d0];
+\end{codeexample}
+ \itemstyle{every day}
+ This style is executed by the default node code for each day. The
+ default setting is
+\begin{codeexample}[code only]
+anchor=base east
+\end{codeexample}
+ The |every day| style is useful for changing the way days
+ look. For example, let us make all days red:
+\begin{codeexample}[leave comments]
+\tikzstyle{every day}+=[red]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list];
+\end{codeexample}
+ \end{itemize}
+
+ \medskip
+ \textbf{Changing the appearance of month and year labels.}
+ In addition to the days of a calendar, labels for the months and
+ even years (for really long calendars) can be added. These labels
+ are only added once per month or year and this is not done by
+ default. Rather, special styles starting with |month label|
+ place these labels and make them visible:
+\begin{codeexample}[]
+\tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
+ month label above centered];
+\end{codeexample}
+
+ The following options change the appearance of the month and year
+ label:
+ \begin{itemize}
+ \itemoption{month code}|=|\meta{code}
+ This option allows you to specify what the macro |\tikzmonthcode|
+ should expand to.
+
+ By default, the |\tikzmonthcode| it is set to
+\begin{codeexample}[code only]
+\node[every month]{\tikzmonthtext};
+\end{codeexample}
+ Note that this node is not named by default.
+ \itemoption{month text}|=|\meta{text}
+ This option allows you to change the macro |\tikzmonthtext|. By
+ default, the month text is a long textual presentation of the
+ current month being typeset.
+\begin{codeexample}[leave comments]
+\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
+ month label above centered,
+ month text=\textcolor{red}{\%mt} \%y-];
+\end{codeexample}
+ \itemstyle{every month}
+ This style, which is empty by default, can be used to change the
+ appearance of month labels.
+ \itemoption{year code}|=|\meta{code} Works like |month code|,
+ only for years.
+ \itemoption{year text}|=|\meta{text} Works like |month text|,
+ only for years.
+ \itemstyle{every year} Works like |every month|,
+ only for years.
+ \end{itemize}
+
+ \medskip
+ \textbf{Date ifs.}
+ Much of the power of the |\calendar| command comes from the use of
+ conditionals. There are two equivalent way of specifying such a
+ conditional. First, you can add the text
+ |if (|\meta{conditions}|) |\meta{code or options} to your
+ \meta{calendar specification}, possibly followed by |else|\meta{else
+ code or options}. You can have multiple such conditionals (but
+ you cannot nest them in this simple manner). The second way is to
+ use the following option:
+ \begin{itemize}
+ \itemoption{if}|=(|\meta{coditions}|)|\meta{code or
+ options}\opt{|else|\meta{else code or options}} This option has
+ the same effect as giving a corresponding if in the \meta{calendar
+ specification}. The option is mostly useful for use in the
+ |every calendar| style, where you cannot provide if conditionals
+ otherwise.
+ \end{itemize}
+ Now, regardless of how you specify a conditional, it has the
+ following effect (individually and independently for each date in
+ the calendar):
+ \begin{enumerate}
+ \item It is checked whether the current date is one of the
+ possibilities listed in \meta{coditions}. An example of such a
+ condition is |Sunday|. Thus, when you write
+ |if (Saturday,Sunday) {foo}|, then |foo| will be executed for
+ every day in the calendar that is a Saturday \emph{or} a Sunday.
+
+ The command |\ifdate| and, thereby, |\pgfcalendarifdate| are used
+ to evaluate the \meta{conditions}, see
+ page~\pageref{pgfcalendarifdate} for a complete list of possible
+ tests. The most useful tests are: Tests like |Monday| and so on,
+ |workday| for the days Monday to Friday, |weekend| for Saturday
+ and Sunday, |equals| for testing whether the current date equals a
+ given date, |at least| and |at least| for comparing the current
+ date with a given date.
+ \item If the date passes the check, the \meta{code or options} is
+ evaluated in a manner to be described in a moment; if the date
+ fails, the \meta{else code or options} is evaluated, if present.
+
+ The \meta{code or options} can either be some code. This is
+ indicated by surrounding the code with curly braces. It can also
+ be a list of \tikzname\ options. This is indicated by surrounding
+ the options with square brackets. For example in the date test
+ |if (Sunday) {\draw...} else {\fill...}| there are two pieces of
+ code involved. By comparison, |if (Sunday) [red] else [green]|
+ involves two options.
+
+ If \meta{code or options} is code, it is simply executed (for the
+ current day). If it is a list of options, these options are passed
+ to a scope surrounding the current date.
+ \end{enumerate}
+ Let us now have a look at some examples. First, we use a conditional
+ to make all Sundays red.
+\begin{codeexample}[]
+\tikz
+ \calendar
+ [dates=2000-01-01 to 2000-01-31,week list]
+ if (Sunday) [red];
+\end{codeexample}
+ Next, let us do something on a specific date:
+\begin{codeexample}[]
+\tikz
+ \calendar
+ [dates=2000-01-01 to 2000-01-31,week list]
+ if (Sunday) [red]
+ if (equals=2000-01-20) {\draw (0,0) circle (8pt);};
+\end{codeexample}
+ You might wonder why the circle seems to be ``off'' the
+ date. Actually, it is centered on the date, it is just that the date
+ label uses the |base east| anchor, which shifts the label up and
+ right. To overcome this problem we can change the anchor:
+\begin{codeexample}[]
+\tikzstyle{every day}=[anchor=mid]
+\tikz
+ \calendar
+ [dates=2000-01-01 to 2000-01-31,week list]
+ if (Sunday) [red]
+ if (equals=2000-01-20) {\draw (0,0) circle (8pt);};
+\end{codeexample}
+ However, the single day dates are now no longer aligned
+ correctly. For this, we can change the day text to |\%d=|,
+ which adds a space at the beginning of single day
+ text.
+
+ In the following, more technical information is covered. Most
+ readers may wish to skip it.
+
+ \medskip
+ \textbf{The current date code.}
+ As mentioned earlier, for each date in the calendar the current date
+ code is executed. It is the job of this code to shift around date
+ nodes, to render the date nodes, to draw the month labels and to do
+ all other stuff that is necessary to draw a calendar.
+
+ The current daet code consists of the following parts, in this order:
+ \begin{enumerate}
+ \item The before-scope code.
+ \item A scope is opened.
+ \item The at-begin-scope code.
+ \item All date-ifs from the \meta{calendar specification} are
+ executed.
+ \item The at-end-scope code.
+ \item The scope is closed.
+ \item The after-scope code.
+ \end{enumerate}
+ All of the codes mentioned above can be changed using appropriate
+ options, see below. In case you wonder why so many are needed, the
+ reason is that the current date code as a whole is not
+ surrounded by a scope or \TeX\ group. This means that code executed
+ in the before-scope code and in the after-scope code has an effect
+ on all following days. For example, if the after-scope code modifies
+ the transformation matrix by shifting everything downward, all
+ following days will be shifted downward. If each day does this, you
+ get a list of days, one below the other.
+
+ However, you do not always want code to have an effect on everything
+ that follows. For instance, if a day has the date-if
+ |if (Sunday) [red]|, we only want this Sunday to red, not all
+ following days also. Similarly, sometimes it is easier to compute
+ the position of a day relative to a fixed origin and we do not want
+ any modifications of the transformation matrix to have an effect
+ outside the scope.
+
+ By cleverly adjusting the different codes, all sorts of different
+ day arrangements are possible.
+
+ \begin{itemize}
+ \itemoption{execute before day scope}|=|\meta{code} This
+ code is executed before everything else for each date. Multiple
+ calls of this option have an accumulative effect. Thus, if you use
+ this option twice, the code from the first use is used first for
+ each day, followed by the code given the second time.
+ \itemoption{execute at begin day scope}|=|\meta{code}
+ This code is execute before everything else inside the scope of
+ the current date. Again, the effect is accumulative.
+ \itemoption{execute at end day scope}|=|\meta{code}
+ This code is executed just before the day scope is
+ closed. The effect is also accumulative, however, in reverse
+ order. This is useful to pair, say, |\scope| and |\endscope|
+ commands in at-begin- and at-end-code.
+ \itemoption{execute after day scope}|=|\meta{code} This
+ is executed at the very end of the current date, outside the
+ scope. The accumulation is also in reverse.
+ \end{itemize}
+\end{command}
+
+
+In the rest of the following subsections we have a look at how the
+different scope codes can be used to create different calendar
+arrangements.
+
+
+\subsubsection{Creating a Simple List of Days}
+
+We start with a list the days of the calendar, one day below the
+other. For this, we simply shift the coordinate system downward at the
+end of the code for each day. This shift must be \emph{outside} the
+day scope as we want day shifts to accumulate. Thus, we use the
+following code:
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-01 to 2000-01-08,
+ execute after day scope=
+ {\pgftransformyshift{-1em}}];
+\end{codeexample}
+Clearly, we can use this approach to create day lists going up,
+down, right, left, or even diagonally.
+
+
+\subsubsection{Adding a Month Label}
+
+We now want to add a month label to the left of the beginning of each
+month. The idea is to do two things:
+\begin{enumerate}
+\item We add code that is executed only on the first of each month.
+\item The code is executed before the actual day is rendered. This
+ ensures that options applying to the days do not affect the month
+ rendering.
+\end{enumerate}
+We have two options where we should add the month code: Either we add
+it at the beginning of the day scope or before. Either will work fine,
+but it might be safer to put the code inside the scope to ensure that
+settings to not inadventerdly ``leak outside.''
+\begin{codeexample}[]
+\tikz
+ \calendar
+ [dates=2000-01-01 to 2000-01-08,
+ execute after day scope={\pgftransformyshift{-1em}},
+ execute at begin day scope=
+ {\ifdate{day of month=1}{\tikzmonthcode}{}},
+ set style={{every month}+=[anchor=base east,xshift=-2em]}];
+\end{codeexample}
+
+In the above code we used the |\ifdate|\marg{condition}\marg{then
+ code}\marg{else code} command, which is described on
+page~\pageref{ifdate} in detail and which has much the same effect as
+|if (|\meta{condition}|)|\marg{then code}| else |\marg{else code}, but
+works in normal code.
+
+
+\subsubsection{Creating a Week List Arrangement}
+
+Let us now address a more complicated arrangement: A week list. In
+this arrangement there is line for each week. The horizontal placement
+of the days is thus that all Mondays lie below each other, likewise
+for all Tuesdays, and so on.
+
+In order to typeset this arrangement, we can use the following
+approach: The origin of the coordinate system rests at the anchor for
+the Monday of each week. That means that at the end of each week the
+origin is moved downward one line. On all other days, the origin at
+the end of the day code is the same as at the beginning. To position
+each day correctly, we use code inside and at the beginning of the day
+scope to horizontally shift the day according to its day of week.
+\begin{codeexample}[]
+\tikz
+ \calendar
+ [dates=2000-01-01 to 2000-01-20,
+ % each day is shifted right according to the day of week
+ execute at begin day scope=
+ {\pgftransformxshift{\pgfcalendarcurrentweekday em}},
+ % after each week, the origin is shifted downward:
+ execute after day scope=
+ {\ifdate{Sunday}{\pgftransformyshift{-1em}}{}}];
+\end{codeexample}
+
+
+\subsubsection{Creating a Month List Arrangement}
+
+For another example, let us create an arrangment that contains one
+line for each month. This is easy enough to do as for weeks, unless we
+add the following requirement: Again, we want all days in a column to
+have the same day of week. Since months start on different days of
+week, this means that each row has to have an individual offset.
+
+One possible way is to use the following approach: After each month
+(or at the beginning of each month) we advance the vertical position
+of the offset by one line. For horizontal placement, inside the day
+scope we locally shift the day by its day of month. Furthermore, we
+must additionally shift the day to ensure that the first day of the
+month lies on the correct day of week column. For this, we remember
+this day of week the first time we see it.
+\begin{codeexample}[]
+\newcount\mycount
+\tikz
+ \calendar
+ [dates=2000-01-01 to 2000-02-last,
+ execute before day scope=
+ {
+ \ifdate{day of month=1} {
+ % Remember the weekday of first day of month
+ \mycount=\pgfcalendarcurrentweekday
+ % Shift downward
+ \pgftransformyshift{-1em}
+ }{}
+ },
+ execute at begin day scope=
+ {
+ % each day is shifted right according to the day of month
+ \pgftransformxshift{\pgfcalendarcurrentday em}
+ % and additionally according to the weekday of the first
+ \pgftransformxshift{\the\mycount em}
+ }];
+\end{codeexample}
+
+
+\subsection{Arrangements}
+
+An \emph{arrangement} specifies how the days of calendar are arranged
+on the page. The calendar library defines a number of predefined
+arrangements.
+
+We start with arrangements in which the days are listed in a long
+line.
+
+\begin{itemize}
+ \itemstyle{day list downward}
+ This style causes the days of a month to be typeset one below the
+ other. The shift between days is given by |day yshift|. Between
+ month an additional shift of |month yshift| is added.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list downward,month yshift=1em];
+\end{codeexample}
+ \itemstyle{day list upward}
+ works as above, only the list grows upward instead of downward.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list upward,month yshift=1em];
+\end{codeexample}
+ \itemstyle{day list right}
+ This style also works as before, but the list of days grows to the
+ right. Instead of |day yshift| and |month yshift|, the values of
+ |day xshift| and |month xshift| are used.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list right,month xshift=1em];
+\end{codeexample}
+ \itemstyle{day list left}
+ as above, but the list grows left.
+\end{itemize}
+
+The next arrangement lists days weekwise.
+
+\begin{itemize}
+ \itemstyle{week list}
+ This style creates one row for each week in the range. The value
+ of |day xshift| is used for the distance between days in each week
+ row, the value of |day yshift| is used for the distance between
+ rows. In both cases, ``distance'' refers to the distance between
+ the anchors of the nodes of the days (or, more generally, the
+ distance between the origins of the little pictures created for each
+ day).
+
+ The days inside each week are shifted such that Monday is always
+ at the first position (to change this, you need to copy and then
+ modify the code appropriately). If the date range does not start on
+ a Monday, the first line will not start in the first column, but
+ rather in the column appropriate for the first date in the range.
+
+ At the beginning of each month (except for the first month in the
+ range) an additional vertical space of |month yshift| is added. If
+ this is set to |0pt| you get a continuous list of days.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-01 to 2000-02-last,week list];
+\end{codeexample}
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-01 to 2000-02-last,week list,
+ month yshift=0pt];
+\end{codeexample}
+\end{itemize}
+
+The following arrangement gives a very compact view of a whole year.
+\begin{itemize}
+ \itemstyle{month list}
+ In this arrangement there is a row for each month. As for the
+ |week list|, the |day xshift| is used for the horizontal distance.
+ For the vertical shft, |month yshift| is used.
+
+ In each row, all days of the month are listed alongside each
+ other. However, it is once more ensured that days in each column lie
+ on the same day of week. Thus, the very first column contains only
+ Mondays. If a month does not start with a Monday, its days are
+ shifted to the right such that the days lie on the correct columns.
+\end{itemize}
+\begin{codeexample}[]
+\sffamily\scriptsize
+\tikz
+ \calendar [dates=2000-01-01 to 2000-12-31,
+ month list,month label left,month yshift=1.25em]
+ if (Sunday) [black!50];
+\end{codeexample}
+
+
+\subsection{Month Labels}
+
+For many calendars you may wish to add a labels to each month. We have
+already covered how month nodes are created and rendered in the
+description of the |\calendar| command: use |month text|,
+|every month|, and also |month code| (if necessary) to change the
+appearance of the month labels.
+
+What we have not yet covered is where these labels are placed. By
+default, they are not placed at all as there is no good ``default
+position'' for them. Instead, you can use one of the following options
+to specify a position for the labels:
+\begin{itemize}
+ \itemstyle{month label left}
+ Places the month label to the left of the first day of the
+ month. (For |week list| and |month list| where a month does not
+ start on a Monday, the position is chosen ``as if'' the month had
+ started on a Monday -- which is usually exactly what you want.)
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list downward,month yshift=1em,
+ month label left];
+\end{codeexample}
+ \itemstyle{month label left vertical}
+ This style works like the above style, only the label is rotated
+ counterclockwise by 90 degrees.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list downward,month yshift=1em,
+ month label left vertical];
+\end{codeexample}
+ \itemstyle{month label right}
+ This style places the month label to the right of the row in which
+ the first day of the month lies. This means that for a day list the
+ label is to the right of the first day, for a week list it is to the
+ right of the first week, and for a month list it is to the right of
+ the whole month.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list downward,month yshift=1em,
+ month label right];
+\end{codeexample}
+ \itemstyle{month label right vertical}
+ as above, only the label is rotated clockwise by 90 degrees.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list downward,month yshift=1em,
+ month label right vertical];
+\end{codeexample}
+
+ \itemstyle{month label above left}
+ This style places the month label above of the row of the first day,
+ flushed left to the leftmost column. The amount by which the label
+ is raised is fixed to |1.25em|; use the |yshift| option with the
+ month node to modify this.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-28 to 2000-02-03,
+ day list right,month xshift=1em,
+ month label above left];
+\end{codeexample}
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-20 to 2000-02-10,
+ week list,month label above left];
+\end{codeexample}
+
+ \itemstyle{month label above centered}
+ works as above, only the label is centered above the row containing
+ the first day.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-02-01 to 2000-02-last,
+ day list right,month label above centered];
+\end{codeexample}
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-20 to 2000-02-10,
+ week list,month label above centered];
+\end{codeexample}
+
+ \itemstyle{month label above right}
+ works as above, but flushed right
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-01-20 to 2000-02-10,
+ week list,month label above right];
+\end{codeexample}
+
+ \itemstyle{month label below left}
+ Works like |month label above left|, only the label is placed below
+ the row. This placement is not really useful with the |week list|
+ arrangement, but rather with the |day list right| or |month list|
+ arrangement.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-02-01 to 2000-02-last,
+ day list right,month label below left];
+\end{codeexample}
+ \itemstyle{month label below centered}
+ works like |month label above centered|, only below.
+\begin{codeexample}[]
+\tikz
+ \calendar [dates=2000-02-01 to 2000-02-last,
+ day list right,month label below centered];
+\end{codeexample}
+\end{itemize}
+
+
+\subsection{Examples}
+
+In the following, some example calendars are shown that come either
+from real applications or are just nice to look at.
+
+Let us start with a year-2100-countdown, in which we cross out dates
+as we approach the big celebration. For
+this, we set the shape to |strike out| for these dates.
+
+\begin{codeexample}[leave comments]
+\begin{tikzpicture}
+ \calendar
+ [
+ dates=2099-12-01 to 2100-01-last,
+ week list,inner sep=2pt,month label above centered,
+ month text=\%mt \%y0
+ ]
+ if (at most=2099-12-29) [nodes={strike out,draw}]
+ if (weekend) [black!50,nodes={draw=none}]
+ ;
+\end{tikzpicture}
+\end{codeexample}
+
+The next calendar shows a deadline, which is 10 days in the future
+from the current date. The last three days before the deadline are in
+red, because we really should be done by then. All days on which we
+can no longer work on the project are crossed out.
+
+\begin{codeexample}[leave comments]
+\begin{tikzpicture}
+ \calendar
+ [
+ dates=\year-\month-\day+-25 to \year-\month-\day+25,
+ week list,inner sep=2pt,month label above centered,
+ month text=\textit{\%mt \%y0}
+ ]
+ if (at least=\year-\month-\day) {}
+ else [nodes={strike out,draw}]
+ if (at most=\year-\month-\day+7)
+ [green!50!black]
+ if (between=\year-\month-\day+8 and \year-\month-\day+10)
+ [red]
+ if (Sunday)
+ [gray,nodes={draw=none}]
+ ;
+\end{tikzpicture}
+\end{codeexample}
+
+The following example is a futuristic calendar that is all about circles:
+
+\begin{codeexample}[]
+\sffamily
+
+\colorlet{winter}{blue}
+\colorlet{spring}{green!60!black}
+\colorlet{summer}{orange}
+\colorlet{fall}{red}
+
+% A counter, since TikZ is not clever enough (yet) to handle
+% arbitrary angle systems.
+\newcount\mycount
+
+\begin{tikzpicture}[transform shape]
+ \tikzstyle{every day}=[anchor=mid,font=\fontsize{6}{6}\selectfont]
+ \node{\normalsize\the\year};
+ \foreach \month/\monthcolor in
+ {1/winter,2/winter,3/spring,4/spring,5/spring,6/summer,
+ 7/summer,8/summer,9/fall,10/fall,11/fall,12/winter}
+ {
+ % Computer angle:
+ \mycount=\month
+ \advance\mycount by -1
+ \multiply\mycount by 30
+ \advance\mycount by -90
+
+ % The actual calendar
+ \calendar at (\the\mycount:6.4cm)
+ [
+ dates=\the\year-\month-01 to \the\year-\month-last,
+ ]
+ if (day of month=1) {\color{\monthcolor}\tikzmonthcode}
+ if (Sunday) [red]
+ if (all)
+ {
+ % Again, compute angle
+ \mycount=1
+ \advance\mycount by -\pgfcalendarcurrentday
+ \multiply\mycount by 11
+ \advance\mycount by 90
+ \pgftransformshift{\pgfpointpolar{\mycount}{1.4cm}}
+ };
+ }
+\end{tikzpicture}
+\end{codeexample}
+
+Next, lets us have a whole year in a tight column:
+\begin{codeexample}[leave comments]
+\begin{tikzpicture}
+ \small\sffamily
+ \colorlet{darkgreen}{green!50!black}
+ \calendar[dates=\year-01-01 to \year-12-31,week list,
+ month label left,month yshift=0pt,
+ month text=\textcolor{darkgreen}{\%m0}]
+ if (Sunday) [black!50];
+\end{tikzpicture}
+\end{codeexample}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual-pdftex-version"
+%%% End:
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex
new file mode 100644
index 00000000000..b8ac1b0b022
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex
@@ -0,0 +1,123 @@
+% Copyright 2006 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{Paper Folding Diagrams Library}
+
+\label{section-calender-folding}
+
+\begin{tikzlibrary}{folding}
+ This library defines commands for creating paper folding
+ diagrams. Currently, it just contains a single command for creating
+ a single diagram, but that one is really useful for creating
+ calendars for your (real) desktop.
+\end{tikzlibrary}
+
+\begin{command}{\tikzfoldingdodecahedron|[|\meta{options}|];|}
+ This command draws a folding diagram for a dodecahedron. The syntax
+ is intended to remind of the |\path| command, but (currently) you
+ must specify the \meta{options} and nothing else may be specified
+ between the command name and the closing semicolon.
+
+ The following \meta{options} apply:
+ \begin{itemize}
+ \itemoption{folding line length}|=|\meta{dimension} sets the length
+ of the base line for folding. For the dodecahedron this is the
+ length of all the sides of the pentagons.
+ \itemoption{face 1}|=|\meta{code}
+ The \meta{code} is executed for the first face of the
+ dodecahedron. When it is executed, the coordinate system will have
+ been shifted and rotated such that it lies at the middle of the
+ first face of the dodecahedron.
+ \itemoption{face 2}|=|\meta{code}
+ Same as |face 1|, but for the second face.
+ \itemoption{face 3}|=|\meta{code}
+ Same as |face 1|, but for the third face.
+
+ There are further similar options, ending with the following:
+ \itemoption{face 12}|=|\meta{code}
+ Same as |face 1|, but for the last face.
+ \end{itemize}
+
+ Here is a simple example:
+\begin{codeexample}[]
+\begin{tikzpicture}[transform shape]
+ \tikzfoldingdodecahedron
+ [folding line length=6mm,
+ face 1={ \node[red] {1};},
+ face 2={ \node {2};},
+ face 3={ \node {3};},
+ face 4={ \node {4};},
+ face 5={ \node {5};},
+ face 6={ \node {6};},
+ face 7={ \node {7};},
+ face 8={ \node {8};},
+ face 9={ \node {9};},
+ face 10={\node {10};},
+ face 11={\node {11};},
+ face 12={\node {12};}];
+\end{tikzpicture}
+\end{codeexample}
+
+ The appearance of the cut and folding lines can be influenced using
+ the following styles:
+ \begin{itemize}
+ \itemstyle{every cut} Executed for every line that should be cut using
+ scissors. Empty by default.
+ \itemstyle{every fold} Executed for every line that should be
+ folded. Equal to |help lines| by default.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every cut}=[red]
+ \tikzstyle{every fold}=[dotted]
+ \tikzfoldingdodecahedron[folding line length=6mm];
+\end{tikzpicture}
+\end{codeexample}
+ \end{itemize}
+\end{command}
+
+Here is a big example that produces a diagram for a calendar:
+
+\begin{codeexample}[leave comments]
+\sffamily\scriptsize
+\begin{tikzpicture}[transform shape]
+ \tikzstyle{every calendar}=
+ [
+ at={(-8ex,4ex)},
+ week list,
+ month label above centered,
+ month text=\bfseries\textcolor{red}{\%mt} \%y0,
+ if={(Sunday) [black!50]}
+ ]
+ \tikzfoldingdodecahedron
+ [
+ folding line length=2.5cm,
+ face 1={ \calendar [dates=\the\year-01-01 to \the\year-01-last];},
+ face 2={ \calendar [dates=\the\year-02-01 to \the\year-02-last];},
+ face 3={ \calendar [dates=\the\year-03-01 to \the\year-03-last];},
+ face 4={ \calendar [dates=\the\year-04-01 to \the\year-04-last];},
+ face 5={ \calendar [dates=\the\year-05-01 to \the\year-05-last];},
+ face 6={ \calendar [dates=\the\year-06-01 to \the\year-06-last];},
+ face 7={ \calendar [dates=\the\year-07-01 to \the\year-07-last];},
+ face 8={ \calendar [dates=\the\year-08-01 to \the\year-08-last];},
+ face 9={ \calendar [dates=\the\year-09-01 to \the\year-09-last];},
+ face 10={\calendar [dates=\the\year-10-01 to \the\year-10-last];},
+ face 11={\calendar [dates=\the\year-11-01 to \the\year-11-last];},
+ face 12={\calendar [dates=\the\year-12-01 to \the\year-12-last];}
+ ];
+\end{tikzpicture}
+\end{codeexample}
+
+
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual-pdftex-version"
+%%% End:
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex
new file mode 100644
index 00000000000..4bb3de3da93
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex
@@ -0,0 +1,250 @@
+% Copyright 2006 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{Matrix Library}
+
+\begin{tikzlibrary}{matrix}
+ This library packages defines additional styles and options for
+ creating matrices.
+\end{tikzlibrary}
+
+
+\subsection{Matrices of Nodes}
+
+A \emph{matrix of nodes} is a \tikzname\ matrix in which each cell
+contains a node. In this case it is bothersome having to write
+|\node{| at the beginning of each cell and |};| at the end of each
+cell. The following style simplifies typesetting such matrices.
+
+\begin{itemize}
+ \itemstyle{matrix of nodes}
+ Conceptually, this style adds |\node{| at the beginning and |};| at
+ the end of each cell and sets the |anchor| of the node to
+ |base|. Furthermore, it adds the option |name| option to each node,
+ where the name is set to \meta{matrix name}|-|\meta{row
+ number}|-|\meta{column number}. For example, if the matrix has
+ the name |my matrix|, then the node in the upper left cell will get
+ the name |my matrix-1-1|.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix (magic) [matrix of nodes]
+ {
+ 8 & 1 & 6 \\
+ 3 & 5 & 7 \\
+ 4 & 9 & 2 \\
+ };
+
+ \draw[thick,red,->] (magic-1-1) |- (magic-2-3);
+\end{tikzpicture}
+\end{codeexample}
+
+ You may wish to add options to certain nodes in the matrix. This can
+ be achieved in three ways.
+ \begin{enumerate}
+ \item You can modify, say, the
+ |row 2 column 5| option to pass special options to this particular
+ cell.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{row 2 column 3}=[red]
+ \matrix [matrix of nodes]
+ {
+ 8 & 1 & 6 \\
+ 3 & 5 & 7 \\
+ 4 & 9 & 2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+ \item At the beginning of a cell, you can use a special syntax. If a
+ cell starts with a vertical bar, then everything between this bar
+ and the next bar is passed on to the |node| command.
+{\catcode`\|=12
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of nodes]
+ {
+ 8 & 1 & 6 \\
+ 3 & 5 & |[red]| 7 \\
+ 4 & 9 & 2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+}
+ You can also use an option like \verb!|[red] (seven)|! to give a
+ different name to the node.
+
+ Note that the |&| character also takes an optional argument, which
+ is an extra column skip.
+{\catcode`\|=12
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of nodes]
+ {
+ 8 &[1cm] 1 &[3mm] |[red]| 6 \\
+ 3 & 5 & |[red]| 7 \\
+ 4 & 9 & 2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+}
+ \item If your cell starts with a |\path| command or any command that
+ expands to |\path|, which includes |\draw|, |\node|, |\fill| and
+ other, the |\node{| startup code and the |};| code are
+ suppressed. This means that for this particular cell you can
+ provide a totally different contents.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of nodes]
+ {
+ 8 & 1 & 6 \\
+ 3 & 5 & \node[red]{7}; \draw(0,0) circle(10pt);\\
+ 4 & 9 & 2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+ \end{enumerate}
+ \itemstyle{matrix of math nodes}
+ This style is almost the same as the previous style, only |$| is %$
+ added at the beginning and at the end of each node, so math mode
+ will be switched on in all nodes.
+{\catcode`\|=12
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of math nodes]
+ {
+ a_8 & a_1 & a_6 \\
+ a_3 & a_5 & |[red]| a_7 \\
+ a_4 & a_9 & a_2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+}
+ \itemoption{nodes in empty cells}\opt{|=|\meta{true or false}}
+ When set to |true|, a node (with an empty contents) is put in empty
+ cells. Normally, empty cells are just, well, empty. The style can be
+ used together with both a |matrix of nodes| and a
+ |matrix of math nodes|.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of math nodes,nodes={circle,draw}]
+ {
+ a_8 & & a_6 \\
+ a_3 & & a_7 \\
+ a_4 & a_9 & \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of math nodes,nodes={circle,draw},nodes in empty cells]
+ {
+ a_8 & & a_6 \\
+ a_3 & & a_7 \\
+ a_4 & a_9 & \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\end{itemize}
+
+
+\subsection{Delimiters}
+
+Delimiters are parantheses or braces to the left and right of a
+formula or a matrix. The matrix library offers options for adding such
+delimiters to a matrix. However, delimiters can actually be added to
+any node that has the standard anchors |north|, |south|, |north west|
+and so on. In particular, you can add delimiters to any |rectangle|
+box. They are implemented by ``measuring the height'' of the node and
+then adding a delimiter of the correct size to the left or right using
+some after node magic.
+
+\begin{itemize}
+ \itemoption{left delimiter}|=|\meta{delimiter}
+ This option can be given to a any node that has the standard anchors
+ |north|, |south| and so on. The \meta{delimiter} can be any
+ delimiter that is acceptable to \TeX's |\left| command.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
+ {
+ a_8 & a_1 & a_6 \\
+ a_3 & a_5 & a_7 \\
+ a_4 & a_9 & a_2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [fill=red!20,left delimiter=(,right delimiter=\}]
+ {$\displaystyle\int_0^1 x\,dx$};
+\end{tikzpicture}
+\end{codeexample}
+
+ \itemstyle{every delimiter}
+ This style is executed for every delimiter. You can use it to shift
+ or color delimiters or do whatever.
+
+ \itemstyle{every left delimiter}
+ This style is additionally executed for every left delimiter.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every left delimiter}=[red,xshift=1ex]
+ \tikzstyle{every right delimiter}=[xshift=-1ex]
+ \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
+ {
+ a_8 & a_1 & a_6 \\
+ a_3 & a_5 & a_7 \\
+ a_4 & a_9 & a_2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+ \itemoption{right delimiter}|=|\meta{delimiter}
+ Works as above.
+
+ \itemstyle{every right delimiter}
+ Works as above.
+
+ \itemoption{above delimiter}|=|\meta{delimiter}
+ This option allows you to add a delimiter above the node. It is
+ implementing by rotating a left delimiter.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of math nodes,%
+ left delimiter=\|,right delimiter=\rmoustache,%
+ above delimiter=(,below delimiter=\}]
+ {
+ a_8 & a_1 & a_6 \\
+ a_3 & a_5 & a_7 \\
+ a_4 & a_9 & a_2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+ \itemstyle{every above delimiter}
+ Works as above.
+
+ \itemoption{below delimiter}|=|\meta{delimiter}
+ works as above.
+
+ \itemstyle{every below delimiter}
+ Works as above.
+\end{itemize}
+
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual-pdftex-version"
+%%% End:
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex
index 91b717f13ac..29680fe657d 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex
@@ -1,4 +1,4 @@
-% Copyright 2006 by Till Tantau
+% Copyright 2006 by Till Tantau and Mark Wibrow
%
% This file may be distributed and/or modified
%
@@ -10,100 +10,269 @@
\section{Shape Library}
+In addition to the standard shapes |rectangle|, |circle| and
+|coordinate|, there exist a number of additional shapes defined in
+different shape libraries. In the present section, these shapes are
+described.
+
+
\begin{pgflibrary}{shapes}
- This library packages defines additional shapes, which are
- described in the following.
+ This library packages just includes all of the libraries defined in
+ the following. Note that it includes only those libraries starting
+ with |shapes.|, more special-purpose libraries are described in
+ dedicated sections.
\end{pgflibrary}
-\begin{shape}{circle split}
- This shape is a multi-part shape consisting of a circle with a line
- in the middle. The upper part is the main part (the |text| part),
- the lower part is the |lower| part.
-
+\subsection{Geometric Shapes}
+
+\begin{pgflibrary}{shapes.geometric}
+ This library defines different shapes that correspond to basic
+ geometric objects like ellipses or polygons.
+\end{pgflibrary}
+
+
+\begin{shape}{diamond}
+ This shape is a diamond tightly fitting the text box. The ratio
+ between width and height is 1 by default, but can be changed by
+ setting the shape aspect ratio (using the |aspect| option of
+ \tikzname). The following figure shows the anchors this
+ shape defines; the anchors |10| and |130| are example of border anchors.
\begin{codeexample}[]
+\Huge
\begin{tikzpicture}
- \node [circle split,draw,double,fill=red!20]
- {
- $q_1$
- \nodepart{lower}
- $00$
- };
+ \node[name=s,shape=diamond,style=shape example] {Diamond\vrule width 1pt height 2cm};
+ \foreach \anchor/\placement in
+ {north west/above left, north/above, north east/above right,
+ west/left, center/above, east/right,
+ mid/above,
+ base/below,
+ south west/below left, south/below, south east/below right,
+ text/left, 10/right, 130/above}
+ \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
+ node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
+\end{shape}
- The shape inherits all anchors from the |circle| shape and defines
- the |lower| anchor in addition. See also the
- following figure:
+\begin{shape}{ellipse}
+ This shape is an ellipse tightly fitting the text box, if no inner
+ separation is given. The following figure shows the anchors this
+ shape defines; the anchors |10| and |130| are example of border anchors.
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
- \node[name=s,shape=circle split,style=shape example] {text\nodepart{lower}lower};
+ \node[name=s,shape=ellipse,style=shape example] {Ellipse\vrule width 1pt height 2cm};
\foreach \anchor/\placement in
{north west/above left, north/above, north east/above right,
- west/left, center/below, east/right,
+ west/left, center/above, east/right,
mid west/right, mid/above, mid east/left,
base west/left, base/below, base east/right,
south west/below left, south/below, south east/below right,
- text/left, lower/left, 130/above}
+ text/left, 10/right, 130/above}
\draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
\end{shape}
-\begin{shape}{cross out}
- This shape ``crosses out'' the node. Its foreground path are simply
- two diagonal lines that between the corners of the node's bounding
- box. Here is an example:
+
+
+\begin{shape}{regular polygon}
+ This shape is a regular polygon, which, by default, is drawn so that a side
+ (rather than a corner) is always at the bottom.
+
\begin{codeexample}[]
\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \node [cross out,draw=red] at (1.5,1) {cross out};
+ \foreach \i in {5,...,8}
+ \node[regular polygon, regular polygon sides=\i, draw] at (\i,0) {\i};
\end{tikzpicture}
\end{codeexample}
- A useful application is inside text as in the following example:
+ Two points should be remembered regarding the dimensions of the
+ polygon border. Firstly, the border is constructed using the incircle, that is, the
+ circle that touches every side of the polygon border. The radius of
+ the incircle is calculated to tightly fit the node contents.
+
\begin{codeexample}[]
-Cross \tikz[baseline] \node [cross out,draw,anchor=text] {me}; out!
+\begin{tikzpicture}
+ \foreach \a in {3,...,7}{
+ \draw[gray!50] (\a*2,0) circle(0.5cm);
+ \node[regular polygon, regular polygon sides=\a, inner sep=0cm, draw] at (\a*2,0)
+ {\tikz\fill[red!50] rectangle(0.707cm,0.707cm);};
+ }
+\end{tikzpicture}
+\end{codeexample}
+
+ Secondly, if the node is enlarged to any specified minimum size,
+ width or height, this is interpreted as the diameter of the the
+ circumcircle, that is, the circle that passes through all the
+ corners of the polygon border.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \foreach \a in {3,...,7}{
+ \draw[gray!50] (\a*2,0) circle(0.5cm);
+ \node[regular polygon, regular polygon sides=\a, minimum size=1cm, draw] at (\a*2,0) {};
+ }
+\end{tikzpicture}
+\end{codeexample}
+
+ There are \pgfname{} commands and \tikzname{} options to set the
+ number of sides for the polygon, and the rotation of the polygon
+ border. The \pgfname{} commands are as follows:
+
+ \begin{command}{\pgfsetpolygonsides\marg{integer}}
+ Set the number of sides for the polygon.
+ \end{command}
+
+ \begin{command}{\pgfsetpolygonrotate\marg{angle}}
+ Rotate the border of the polygon independently of the node
+ contents (but in addition to any concurrent coordinate or canvas
+ transformation).
+ \end{command}
+
+ The corresponding \tikzname{} options are:
+
+ \begin{itemize}
+ \itemoption{regular polygon sides}|=|\meta{integer}
+ set the number of points for the star.
+
+ \itemoption{regular polygon rotate}|=|\meta{angle}
+ rotate the border of the polygon independently of the node
+ contents.
+ \end{itemize}
+
+ The anchors for the regular polygon shape are shown below:
+
+\begin{codeexample}[]
+\Huge
+\begin{tikzpicture}
+ \node[name=s, shape=regular polygon, regular polygon sides=5, style=shape example, inner sep=.5cm]
+ {Regular Polygon\vrule width 1pt height 2cm};
+ \foreach \anchor/\placement in
+ {corner 1/above, corner 2/above, corner 3/left, corner 4/right,
+ corner 5/above, side 1/left, side 2/left, side 3/below,
+ side 4/right, side 5/right, mid/right, base/below,
+ center/above, text/left, 75/above, west/above,
+ east/above, north/below, south/above}
+ \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
+ node[\placement] {\scriptsize\texttt{(s.\anchor)}};
+\end{tikzpicture}
\end{codeexample}
+
+\end{shape}
- This shape inherits all anchors from the |rectangle| shape, see also
- the following figure:
+\begin{shape}{star}
+ This shape is a star, which by default (minus any transformations) is
+ drawn with the first point pointing upwards.
+ A star should be thought of as having an set of ``inner points'' and
+ and ``outer points''. These points form the principle anchors for the
+ star, as shown below:
+
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
- \node[name=s,shape=cross out,style=shape example] {cross out\vrule width 1pt height 2cm};
+ \node[name=s, shape=star, star points=5, star point ratio=1.5, style=shape example, inner sep=1.5cm]
+ {Star\vrule width 1pt height 2cm};
\foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
- mid west/right, mid/above, mid east/left,
- base west/left, base/below, base east/right,
- south west/below left, south/below, south east/below right,
- text/left, 10/right, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
+ {inner point 1/above, inner point 2/above, inner point 3/below,
+ inner point 4/right, inner point 5/above, outer point 1/above,
+ outer point 2/above, outer point 3/left, outer point 4/right,
+ outer point 5/above, mid/right, base/below,
+ center/above, text/left, 75/above}
+ \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
+ node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
+
+ The inner points of the border are based on the radius of the circle
+ which tightly fits the node contents.
+ Any specified minimum size, width or height, is interpreted as the
+ diameter of the circle that passes through every outer point.
+
+ There are \pgfname{} commands and \tikzname{} options to set various
+ parameters for the star, such as the number of points, the height of
+ the points and the rotation of the star border.
+
+ The \pgfname{} commands are as follows:
+
+ \begin{command}{\pgfsetstarpoints\marg{integer}}
+ Sets the number of points for the star.
+ \end{command}
+
+ \begin{command}{\pgfsetstarpointheight\marg{distance}}
+ Sets the height of the star points. This is the distance between the
+ inner point and outer point radii. If the star is enlarged to some
+ specified minimum size, the inner radius is increased to maintain
+ the point height.
+ \end{command}
+
+ \begin{command}{\pgfsetstarpointratio\marg{number}}
+ Sets the ratio between the outer point and inner point radii.
+ If the star is enlarged to some specified minimum size, the
+ inner radius is increased to maintain the ratio.
+ \end{command}
+
+ \begin{command}{\pgfsetstarrotate\marg{angle}}
+ Rotates the border of the star, independently of the node contents,
+ but subject to any coordinate or canvas transformations.
+ \end{command}
+
+ The corresponding \tikzname{} options are:
+
+ \begin{itemize}
+ \itemoption{star points}|=|\meta{integer}
+ set the number of points for the star.
+
+ \itemoption{star point height}|=|\meta{distance}
+ set the height of the points for the star.
+
+ \itemoption{star point ratio}|=|\meta{number}
+ set the ratio between the outer point radius and the inner point
+ radius.
+
+ \itemoption{star rotate}|=|\meta{angle}
+ rotate the star shape border indepently of the node contents.
+
+ \end{itemize}
\end{shape}
-\begin{shape}{diamond}
- This shape is a diamond tightly fitting the text box. The ratio
- between width and height is 1 by default, but can be changed by
- setting the shape aspect ratio (using the |aspect| option of
- \tikzname). The following figure shows the anchors this
- shape defines; the anchors |10| and |130| are example of border anchors.
+
+\subsection{Symbol Shapes}
+
+\begin{pgflibrary}{shapes.symbols}
+ This library defines shapes that can be used for drawing symbols
+ like a forbidden sign or a cloud.
+\end{pgflibrary}
+
+
+
+\begin{shape}{forbidden sign}
+ This shape places the node inside a circle with a diagonal from the
+ lower left to the upper right added. The circle is part of the
+ background, the diagonal line part of the foreground path; thus, the
+ diagonal line is on top of the text.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [forbidden sign,line width=1ex,draw=red,fill=white] {Smoking};
+\end{tikzpicture}
+\end{codeexample}
+
+ The shape inherits all anchors from the |circle| shape, see also the
+ following figure:
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
- \node[name=s,shape=diamond,style=shape example] {Diamond\vrule width 1pt height 2cm};
+ \node[name=s,shape=forbidden sign,style=shape example] {Forbidden\vrule width 1pt height 2cm};
\foreach \anchor/\placement in
{north west/above left, north/above, north east/above right,
west/left, center/above, east/right,
- mid/above,
- base/below,
+ mid west/right, mid/above, mid east/left,
+ base west/left, base/below, base east/right,
south west/below left, south/below, south east/below right,
text/left, 10/right, 130/above}
\draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
@@ -112,45 +281,85 @@ Cross \tikz[baseline] \node [cross out,draw,anchor=text] {me}; out!
\end{codeexample}
\end{shape}
-\begin{shape}{ellipse}
- This shape is an ellipse tightly fitting the text box, if no inner
- separation is given. The following figure shows the anchors this
- shape defines; the anchors |10| and |130| are example of border anchors.
+
+
+\subsection{Shapes with Multiple Text Parts}
+
+\begin{pgflibrary}{shapes.multipart}
+ This library defines general-purpose shapes that are composed of
+ multiple (text) parts.
+\end{pgflibrary}
+
+
+\begin{shape}{circle split}
+ This shape is a multi-part shape consisting of a circle with a line
+ in the middle. The upper part is the main part (the |text| part),
+ the lower part is the |lower| part.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \node [circle split,draw,double,fill=red!20]
+ {
+ $q_1$
+ \nodepart{lower}
+ $00$
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+ The shape inherits all anchors from the |circle| shape and defines
+ the |lower| anchor in addition. See also the
+ following figure:
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
- \node[name=s,shape=ellipse,style=shape example] {Ellipse\vrule width 1pt height 2cm};
+ \node[name=s,shape=circle split,style=shape example] {text\nodepart{lower}lower};
\foreach \anchor/\placement in
{north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
+ west/left, center/below, east/right,
mid west/right, mid/above, mid east/left,
base west/left, base/below, base east/right,
south west/below left, south/below, south east/below right,
- text/left, 10/right, 130/above}
+ text/left, lower/left, 130/above}
\draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
\end{shape}
-\begin{shape}{forbidden sign}
- This shape places the node inside a circle with a diagonal from the
- lower left to the upper right added. The circle is part of the
- background, the diagonal line part of the foreground path; thus, the
- diagonal line is on top of the text.
-
+
+\subsection{Miscellaneous Shapes}
+
+\begin{pgflibrary}{shapes.misc}
+ This library defines general-purpose shapes that do not fit in the
+ previous categories.
+\end{pgflibrary}
+
+
+
+\begin{shape}{cross out}
+ This shape ``crosses out'' the node. Its foreground path are simply
+ two diagonal lines that between the corners of the node's bounding
+ box. Here is an example:
+
\begin{codeexample}[]
\begin{tikzpicture}
- \node [forbidden sign,line width=1ex,draw=red,fill=white] {Smoking};
+ \draw[help lines] (0,0) grid (3,2);
+ \node [cross out,draw=red] at (1.5,1) {cross out};
\end{tikzpicture}
\end{codeexample}
- The shape inherits all anchors from the |circle| shape, see also the
- following figure:
+ A useful application is inside text as in the following example:
+\begin{codeexample}[]
+Cross \tikz[baseline] \node [cross out,draw,anchor=text] {me}; out!
+\end{codeexample}
+
+ This shape inherits all anchors from the |rectangle| shape, see also
+ the following figure:
\begin{codeexample}[]
\Huge
\begin{tikzpicture}
- \node[name=s,shape=forbidden sign,style=shape example] {Forbidden\vrule width 1pt height 2cm};
+ \node[name=s,shape=cross out,style=shape example] {cross out\vrule width 1pt height 2cm};
\foreach \anchor/\placement in
{north west/above left, north/above, north east/above right,
west/left, center/above, east/right,
@@ -164,7 +373,6 @@ Cross \tikz[baseline] \node [cross out,draw,anchor=text] {me}; out!
\end{codeexample}
\end{shape}
-
\begin{shape}{strike out}
This shape is idential to the |cross out| shape, only its foreground
path consists of a single line from the lower left to the upper
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex
index e0e49b657d9..4850378c8e8 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex
@@ -15,11 +15,12 @@
\def\xkeyvalversion{1.8}
\usepackage[version=0.96]{pgf}
+
\usepackage{tikz}
-\usetikzlibrary{arrows,patterns,plotmarks,shapes,snakes,er,3d,automata,backgrounds,topaths,trees,petri,mindmap}
+\usetikzlibrary{arrows,patterns,plotmarks,shapes,snakes,er,3d,automata,backgrounds,topaths,trees,petri,mindmap,matrix,calendar,folding}
-\usepackage[left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
+\usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
\usepackage{amsmath,amssymb}
\usepackage{xxcolor}
\usepackage{pifont}
@@ -36,7 +37,7 @@
\renewcommand*\l@subsubsection{\@dottedtocline{3}{4.3em}{3.2em}}
\makeatother
-%\includeonly{pgfmanual-en-tutorial-nodes}
+%\includeonly{}
% Global styles:
\tikzstyle{every plot}=[prefix=plots/pgf-]
@@ -50,7 +51,7 @@
\begin{document}
-%\include{pgfmanual-en-license}
+%\include{pgfmanual-en-base-external}
%\end{document}
{
@@ -88,11 +89,14 @@ Manual for version \pgfversion
{
\vbox{}
\vskip0pt plus 1fill
- Für meinen Vater, damit er noch viele schöne \TeX-Graphiken erschaffen kann.
+ Für meinen Vater, damit er noch viele schöne \TeX-Graphiken
+ erschaffen kann.
+ \vskip1em
+ \hfill\emph{Till}
\vskip0pt plus 3fill
\parindent=0pt
- Copyright 2006 by Till Tantau
+ Copyright 2007 by Till Tantau
\medskip
Permission is granted to copy, distribute and/or modify \emph{the documentation}
@@ -124,7 +128,9 @@ Manual for version \pgfversion
\title{\bfseries The \tikzname\ and {\Large PGF} Packages\\
\large Manual for version \pgfversion\\[1mm]
\large\href{http://sourceforge.net/projects/pgf}{\texttt{http://sourceforge.net/projects/pgf}}}
-\author{Till Tantau\\
+\author{Till Tantau\footnote{Editor of this documentation. Parts of
+ this documentation have been written by other authors as indicated
+ in these parts or chapters and in Section~\ref{section-authors}.}\\
\normalsize Institut f\"ur Theoretische Informatik\\[-1mm]
\normalsize Universit\"at zu L\"ubeck}
@@ -140,6 +146,10 @@ Manual for version \pgfversion
\part{Tutorials and Guidelines}
+{\Large \emph{by Till Tantau}}
+
+\bigskip
+\noindent
To help you get started with \tikzname, instead of a long installation
and configuration section, this manual starts with tutorials. They
explain all the basic and some of the more advanced features of the
@@ -162,6 +172,11 @@ some guidelines on how you should proceed when creating graphics using
\part{Installation and Configuration}
+{\Large \emph{by Till Tantau}}
+
+
+\bigskip
+\noindent
This part explains how the system is installed. Typically, someone has
already done so for your system, so this part can be skipped; but if
this is not the case and you are the poor fellow who has to do the
@@ -189,6 +204,15 @@ installation, read the present part.
(D) edge [loop below] node {1,1,R} (D)
edge node {0,1,R} (A)
(E) edge [bend left] node {1,0,R} (A);
+
+ \node [right=1cm,text width=8cm,font=\footnotesize] at (C)
+ {
+ The current candidate for the busy beaver for five states. It is
+ presumed that this Turing machine writes a maximum number of
+ $1$'s before halting among all Turing machines with five states
+ and the tape alphabet $\{0, 1\}$. Proving this conjecture is an
+ open research problem.
+ };
\end{tikzpicture}
\end{codeexample}
@@ -200,6 +224,11 @@ installation, read the present part.
\part{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm}
\label{part-tikz}
+{\Large \emph{by Till Tantau}}
+
+
+\bigskip
+\noindent
\vskip3cm
\begin{codeexample}[graphic=white]
\begin{tikzpicture}
@@ -241,7 +270,9 @@ installation, read the present part.
\include{pgfmanual-en-tikz-paths}
\include{pgfmanual-en-tikz-actions}
\include{pgfmanual-en-tikz-shapes}
+\include{pgfmanual-en-tikz-matrices}
\include{pgfmanual-en-tikz-trees}
+\include{pgfmanual-en-tikz-plots}
\include{pgfmanual-en-tikz-transformations}
@@ -249,6 +280,11 @@ installation, read the present part.
\part{Libraries}
\label{part-libraries}
+{\Large \emph{by Till Tantau}}
+
+
+\bigskip
+\noindent
In this part the library packages are documented. They
provide additional predefined graphic objects like new arrow heads or
new plot marks. These are not loaded by default since many users will
@@ -271,7 +307,7 @@ not need them.
[level distance=1.75mm,leaf a, line width=.2ex,sibling angle=40]
\pgfarrowsdeclare{leaf}{leaf}
-{\pgfarrowsleftextend{-2pt} \pgfarrowsrightextend{1pt}}
+ {\pgfarrowsleftextend{-2pt} \pgfarrowsrightextend{1pt}}
{
\pgfpathmoveto{\pgfpoint{-2pt}{0pt}}
\pgfpatharc{150}{30}{1.8pt}
@@ -279,7 +315,6 @@ not need them.
\pgfusepathqfill
}
-
\newcommand{\tcslogo}[5]
{
\colorlet{border}{#1}
@@ -301,15 +336,12 @@ not need them.
child foreach \d in {0,1} {
child foreach \leafcolor in {leaf a,leaf b}
{ edge from parent [color=\leafcolor,-#5] }
- }
- }
- }
+ } } }
} edge from parent [shorten >=-1pt,serif cm-,cap=butt]
};
\node [text centered,text width=2cm,below] at (0pt,-.5ex)
- { \textcolor{border}{T}heoretical \\
- \textcolor{border}{C}omputer \\
+ { \textcolor{border}{T}heoretical \\ \textcolor{border}{C}omputer \\
\textcolor{border}{S}cience };
\end{tikzpicture}
}
@@ -324,7 +356,10 @@ not need them.
\include{pgfmanual-en-library-arrows}
\include{pgfmanual-en-library-automata}
\include{pgfmanual-en-library-backgrounds}
+\include{pgfmanual-en-library-calendar}
\include{pgfmanual-en-library-er}
+\include{pgfmanual-en-library-folding}
+\include{pgfmanual-en-library-matrices}
\include{pgfmanual-en-library-mindmaps}
\include{pgfmanual-en-library-patterns}
\include{pgfmanual-en-library-petri}
@@ -342,6 +377,11 @@ not need them.
\part{Utilities}
\label{part-utilities}
+{\Large \emph{by Till Tantau}}
+
+
+\bigskip
+\noindent
The utility packages are not directly involved in creating graphics,
but you may find them useful nonetheless. All of them either directly
depend on \pgfname\ or they are designed to work well together with
@@ -372,13 +412,65 @@ depend on \pgfname\ or they are designed to work well together with
\end{codeexample}
\include{pgfmanual-en-pgffor}
+\include{pgfmanual-en-pgfcalendar}
\include{pgfmanual-en-pages}
\include{pgfmanual-en-xxcolor}
+\part{Mathematical Engine}
+
+{\Large \emph{by Mark Wibrow and Till Tantau}}
+
+
+\bigskip
+\noindent
+\pgfname\ comes with its own mathematical engine. The job of this
+engine is to support mathematical operations like addition,
+subtraction, multiplication and division, using both integers and
+non-integers, but also functions such as square-roots, sine, cosine,
+and generate pseudo-random numbers.
+
+Mostly, you will use the mathematical facilities of \pgfname\
+indirectly, namely when you write a coordinate like |(5cm*3,6cm/4)|,
+but the mathematical engine can also be used independently of
+\pgfname\ and \tikzname.
+
+\vskip1cm
+\begin{codeexample}[graphic=white]
+\pgfmathsetseed{1}
+\foreach \col in {black,red,green,blue}
+{
+ \begin{tikzpicture}[x=10pt,y=10pt,ultra thick,baseline,cap=round]
+ \coordinate (current point) at (0,0);
+ \coordinate (old velocity) at (0,0);
+ \coordinate (new velocity) at (rand,rand);
+
+ \foreach \i in {0,1,...,100}
+ {
+ \draw[\col!\i] (current point)
+ .. controls ++([scale=-1]old velocity) and
+ ++(new velocity) .. ++(rand,rand)
+ coordinate (current point);
+ \coordinate (old velocity) at (new velocity);
+ \coordinate (new velocity) at (rand,rand);
+ }
+ \end{tikzpicture}
+}
+\end{codeexample}
+
+\include{pgfmanual-en-math-design}
+\include{pgfmanual-en-math-parsing}
+\include{pgfmanual-en-math-commands}
+\include{pgfmanual-en-math-algorithms}
+
\part{The Basic Layer}
+{\Large \emph{by Till Tantau}}
+
+
+\bigskip
+\noindent
\vskip1cm
\begin{codeexample}[graphic=white]
\begin{tikzpicture}
@@ -416,9 +508,11 @@ depend on \pgfname\ or they are designed to work well together with
\include{pgfmanual-en-base-actions}
\include{pgfmanual-en-base-arrows}
\include{pgfmanual-en-base-nodes}
+\include{pgfmanual-en-base-matrices}
\include{pgfmanual-en-base-transformations}
\include{pgfmanual-en-base-patterns}
\include{pgfmanual-en-base-images}
+\include{pgfmanual-en-base-external}
\include{pgfmanual-en-base-shadings}
\include{pgfmanual-en-base-plots}
\include{pgfmanual-en-base-layers}
@@ -430,6 +524,11 @@ depend on \pgfname\ or they are designed to work well together with
\part{The System Layer}
\label{part-system}
+{\Large \emph{by Till Tantau}}
+
+
+\bigskip
+\noindent
This part describes the low-level interface of \pgfname, called the
\emph{system layer}. This interface provides a complete abstraction of
the internals of the underlying drivers.
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex
new file mode 100644
index 00000000000..64332eca3ed
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex
@@ -0,0 +1,74 @@
+% Copyright 2007 by Mark Wibrow
+%
+% 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[Reimplementing the Computations of the Mathematical Engine]
+ {Reimplementing the Computations of the\\ Mathematical Engine}
+
+\label{pgfmath-reimplement}
+
+Perhaps you are not satisfied with the Maclaurin series for
+$e^x$. Perhaps you have a fantastically more accurate
+and efficient way of calculating the sine or cosine of angles. Perhaps
+ you would like the library to interface with a package such as |fp|
+ for fixed-point arithmetic (but note that |fp| is \emph{very} slow).
+In these case you will want to replace the current implementations of
+the computations done by the mathematical engine by your own code.
+
+The mathematical engine was designed with such a replacement in
+mind. For this reason, the operations and functions like |\pgfmathadd|
+are implemented in the following manner:
+
+\begin{itemize}
+\item |\pgfmath|\meta{function name}
+
+ This macro is the ``public'' interface for the function
+ \meta{function name}. All arguments passed to this macro are
+ evaluated using |\pgfmathparse| and then passed on to the following
+ function:
+
+\item |\pgfmath|\meta{function name}|@|
+
+ This macro is the ``non-public'' implementation of the functions
+ algorithm (but note that, for speed, the parser calls this macro
+ rather than the ``public'' one). Arguments passed to this macro
+ are expected to be numbers \emph{without units}. This is the macro
+ which should be rewritten with your prize-winning new algorithm.
+
+\end{itemize}
+
+The effect of |\pgfmath|\meta{function name}|@| should be to set the
+macro |\pgfmathresult| to the correct value (namely to the result of
+the computation without units). Furthermore, the function should have
+no other side effects, that is, it should not change any global
+values. One way to achieve this is to use the following code:
+
+\begin{codeexample}[code only]
+\def\pgfmath...@#1#2...{%
+ \begingroup%
+ ... code for algorithm XXX ...
+ \pgfmath@returnone\pgfmath@x%
+ \endgroup%
+}
+\end{codeexample}
+
+
+The macro |\pgfmath@returnone<macro>| uses some |\aftergroup| magic to
+save result of the algorithm, by defining |\pgfmathresult| as the
+expansion of |<macro>| \emph{without units}. |<macro>| can be a macro
+containing a number (with or without units), or a dimension or count
+(or possibly a skip) register. By performing the algorithm within a
+\TeX{} group, \pgfname{} registers such as |\pgf@x|, |\pgf@y| and
+|\c@pgf@counta|, |\c@pgfcountb|, and so forth can be used at will.
+Note that current the implementation uses |\pgfmath@x|, |\pgfmath@y|,
+and |\c@pgfmath@counta|, |\c@pgfmath@countb| throughout, so for
+consistency these should be employed. Whilst they are currently |\let|
+to their \pgfname{} equivalents (see |pgfmathutil.code.tex|), this
+could change (as could the \pgfname{} registers), so keeping things
+consistent is probably a good idea. \ No newline at end of file
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex
new file mode 100644
index 00000000000..ea88757e507
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex
@@ -0,0 +1,306 @@
+% Copyright 2007 by Mark Wibrow
+%
+% 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{Evaluating Mathematical Operations}
+
+\label{pgfmath-commands}
+
+Instead of parsing and evaluating complex expressions, you can also
+use the mathematical engine to evaluate a single mathematical
+operation. The macros used for these computations are described in the
+following.
+
+
+\subsection{Basic Operations and Functions}
+
+\label{pgfmath-operations}
+
+\begin{command}{\pgfmathadd\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as $\meta{x}+\meta{y}$.
+\end{command}
+
+\begin{command}{\pgfmathsubtract\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as $\meta{x}-\meta{y}$.
+\end{command}
+
+\begin{command}{\pgfmathmultiply\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as $\meta{x}\times\meta{y}$.
+\end{command}
+
+\begin{command}{\pgfmathdivide\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as $\meta{x}\div\meta{y}$.
+\end{command}
+
+\begin{command}{\pgfmathgreaterthan\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as 1.0 if \meta{x} $>$ \meta{y}, but 0.0 otherwise.
+\end{command}
+
+\begin{command}{\pgfmathlessthan\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as 1.0 if \meta{x} $<$ \meta{y}, but 0.0 otherwise.
+\end{command}
+
+\begin{command}{\pgfmathequalto\marg{x}\marg{y}}
+ Defines |\pgfmathresult| 1.0 if \meta{x} $=$ \meta{y}, but 0.0 otherwise.
+\end{command}
+
+\begin{command}{\pgfmathround\marg{x}}
+ Defines |\pgfmathresult| as $\left\lfloor\textrm{\meta{x}}\right\rceil$.
+ This uses asymmetric half-up rounding.
+\end{command}
+
+\begin{command}{\pgfmathfloor\marg{x}}
+ Defines |\pgfmathresult| as $\left\lfloor\textrm{\meta{x}}\right\rfloor$.
+\end{command}
+
+\begin{command}{\pgfmathceil\marg{x}}
+ Defines |\pgfmathresult| as $\left\lceil\textrm{\meta{x}}\right\rceil$.
+\end{command}
+
+\begin{command}{\pgfmathpow\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as $\meta{x}^{\meta{y}}$. \meta{y} is
+ expected to be an integer. But it can be negative.
+\end{command}
+
+\begin{command}{\pgfmathmod\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as \meta{x} modulo \meta{y}.
+\end{command}
+
+\begin{command}{\pgfmathmax\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as the maximum of \meta{x} or \meta{y}.
+\end{command}
+
+\begin{command}{\pgfmathmin\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as the minimum \meta{x} or \meta{y}.
+\end{command}
+
+\begin{command}{\pgfmathabs\marg{x}}
+ Defines |\pgfmathresult| as absolute value of \meta{x}.
+\end{command}
+
+\begin{command}{\pgfmathreciprocal\marg{x}}
+ Defines |\pgfmathresult| as $1\div\meta{x}$.
+\end{command}
+
+\begin{command}{\pgfmathexp\marg{x}}
+ Defines |\pgfmathresult| as $e^{\meta{x}}$. Here, \meta{x} can be a
+ non-integer. The algorithm uses a Maclaurin series.
+\end{command}
+
+\begin{command}{\pgfmathsqrt\marg{x}}
+ Defines |\pgfmathresult| as $\sqrt{\meta{x}}$.
+\end{command}
+
+\begin{command}{\pgfmathveclen\marg{x}\marg{y}}
+ Defines |\pgfmathresult| as $\sqrt{\meta{x}^2+\meta{y}^2}$. This uses
+ a polynomial approximation, based on ideas due to Rouben Rostamian.
+\end{command}
+
+\subsection{Trignometric Functions}
+
+\label{pgfmath-trigonmetry}
+
+\begin{command}{\pgfmathpi}
+ Defines |\pgfmathresult| as $3.14159$.
+\end{command}
+
+\begin{command}{\pgfmathdeg{\marg{x}}}
+ Defines |\pgfmathresult| as \meta{x} (given in radians) converted to
+ degrees.
+\end{command}
+
+\begin{command}{\pgfmathrad{\marg{x}}}
+ Defines |\pgfmathresult| as \meta{x} (given in degrees) converted to
+ radians.
+\end{command}
+
+\begin{command}{\pgfmathsin{\marg{x}}}
+ Defines |\pgfmathresult| as the sine of \meta{x}.
+\end{command}
+
+\begin{command}{\pgfmathcos{\marg{x}}}
+ Defines |\pgfmathresult| as the cosine of \meta{x}.
+\end{command}
+
+\begin{command}{\pgfmathtan{\marg{x}}}
+ Defines |\pgfmathresult| as the tangant of \meta{x}.
+\end{command}
+
+\begin{command}{\pgfmathasin{\marg{x}}}
+ the arcsine of \meta{x}.
+\end{command}
+
+\begin{command}{\pgfmathacos{\marg{x}}}
+ Defines |\pgfmathresult| as the arccosine of \meta{x}.
+\end{command}
+
+\begin{command}{\pgfmathatan{\marg{x}}}
+ Defines |\pgfmathresult| as the arctangent of \meta{x}.
+\end{command}
+
+
+
+\subsection{Pseudo-Random Numbers}
+
+\label{pgfmath-random}
+
+
+\begin{command}{\pgfmathgeneratepseudorandomnumber}
+ Defines |\pgfmathresult| as a pseudo-random integer between 1 and
+ $2^{31}-1$. This uses a linear congruency generator, based on ideas
+ due to Erich Janka.
+\end{command}
+
+\begin{command}{\pgfmathrnd}
+ Defines |\pgfmathresult| as a pseudo-random number between 0.0 and 1.0
+\end{command}
+
+\begin{command}{\pgfmathrand}
+ Defines |\pgfmathresult| as a pseudo-random number between -1.0 and 1.0
+\end{command}
+
+\begin{command}{\pgfmathrandominteger\marg{macro}\marg{maximum}\marg{minimum}}
+ This defines \meta{macro} as a pseudo-randomly generated integer from
+ the range \meta{maximum} to \meta{minimum} (inclusive).
+
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \foreach \x in {1,...,50}{
+ \pgfmathrandominteger{\a}{1}{50}
+ \pgfmathrandominteger{\b}{1}{50}
+ \pgfpathcircle{\pgfpoint{+\a pt}{+\b pt}}{+2pt}
+ \color{blue!40!white}
+ \pgfsetstrokecolor{blue!80!black}
+ \pgfusepath{stroke, fill}
+ }
+\end{pgfpicture}
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfmathdeclarerandomlist\marg{list name}\{\marg{item-1}\marg{item 2}...\}}
+ This creates a list of items with the name \meta{list name}.
+\end{command}
+
+\begin{command}{\pgfmathrandomitem\marg{macro}\marg{list name}}
+ Select an item from a random list \meta{list name}. The
+ selected item is placed in \meta{macro}.
+\end{command}
+
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \pgfmathdeclarerandomlist{color}{{red}{blue}{green}{yellow}{white}}
+ \foreach \a in {1,...,50}{
+ \pgfmathrandominteger{\x}{1}{85}
+ \pgfmathrandominteger{\y}{1}{85}
+ \pgfmathrandominteger{\r}{5}{10}
+ \pgfmathrandomitem{\c}{color}
+ \pgfpathcircle{\pgfpoint{+\x pt}{+\y pt}}{+\r pt}
+ \color{\c!40!white}
+ \pgfsetstrokecolor{\c!80!black}
+ \pgfusepath{stroke, fill}
+ }
+\end{pgfpicture}
+\end{codeexample}
+
+\begin{command}{\pgfmathsetseed\marg{integer}}
+ Explicitly set seed for the pseudo-random number generator. By
+ default it is set to the value of |\time|$\times$|\year|.
+\end{command}
+
+
+
+\subsection{Conversion Between Bases}
+
+\label{pgfmath-bases}
+
+\pgfname{} provides limited support for conversion between
+\emph{representations} of numbers. Currently the numbers must be
+positive integers in the range $0$ to $2^{31}-1$, and the bases in the
+range $2$ to $36$. All digits representing numbers greater than 9 (in
+base ten), are alphabetic, but may be upper or lower case. Note, that
+again, examples in this section, show the result of the calculation
+\emph{not} what is displayed in the document.
+
+\begin{command}{\pgfmathbasetodec\marg{macro}\marg{number}\marg{base}}
+ Defines \meta{macro} as the result of converting \meta{number} from
+ base \meta{base} to base 10. Alphabetic digits can be upper or lower
+ case.
+
+\medskip{\def\medskip{}
+
+\begin{codeexample}[post=\tt\footnotesize\mynumber]
+\pgfmathbasetodec\mynumber{107f}{16}
+\end{codeexample}
+
+
+\begin{codeexample}[post=\tt\footnotesize\mynumber]
+\pgfmathbasetodec\mynumber{33FC}{20}
+\end{codeexample}
+
+}\medskip
+
+\end{command}
+
+\begin{command}{\pgfmathdectobase\marg{macro}\marg{number}\marg{base}}
+ Defines \meta{macro} as the result of converting \meta{number} from
+ base 10 to base \meta{base}. Any resulting alphabetic digits are in
+ \emph{lower case}.
+
+\begin{codeexample}[post=\tt\footnotesize\mynumber]
+\pgfmathdectobase\mynumber{65535}{16}
+\end{codeexample}
+
+\end{command}
+
+\begin{command}{\pgfmathdectoBase\marg{macro}\marg{number}\marg{base}}
+ Defines \meta{macro} as the result of converting \meta{number} from
+ base 10 to base \meta{base}. Any resulting alphabetic digits are in
+ \emph{upper case}.
+
+\begin{codeexample}[post=\tt\footnotesize\mynumber]
+\pgfmathdectoBase\mynumber{65535}{16}
+\end{codeexample}
+
+\end{command}
+
+\begin{command}{\pgfmathbasetobase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
+ Defines \meta{macro} as the result of converting \meta{number} from
+ base \meta{base-1} to base \meta{base-2}. Alphabetic digits in
+ \meta{number} can be upper or lower case, but any resulting
+ alphabetic digits are in \emph{lower case}.
+
+\begin{codeexample}[post=\tt\footnotesize\mynumber]
+\pgfmathbasetobase\mynumber{11011011}{2}{16}
+\end{codeexample}
+
+\end{command}
+
+\begin{command}{\pgfmathbasetoBase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
+ Defines \meta{macro} as the result of converting \meta{number} from
+ base \meta{base-1} to base \meta{base-2}. Alphabetic digits in
+ \meta{number} can be upper or lower case, but any resulting
+ alphabetic digits are in \emph{upper case}.
+
+\begin{codeexample}[post=\tt\footnotesize\mynumber]
+\pgfmathbasetoBase\mynumber{121212}{3}{12}
+\end{codeexample}
+
+\end{command}
+
+
+\begin{command}{\pgfmathsetbasenumberlength\marg{integer}}
+ Set the number of digits in the result of a base conversion to
+ \meta{integer}. If the result of a conversion has less digits
+ than this number it is prefixed with zeros.
+
+\begin{codeexample}[post=\tt\footnotesize\mynumber]
+\pgfmathsetbasenumberlength{8}
+\pgfmathdectobase\mynumber{15}{2}
+\end{codeexample}
+
+\end{command} \ No newline at end of file
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex
new file mode 100644
index 00000000000..d63d506db3a
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex
@@ -0,0 +1,104 @@
+% Copyright 2007 by Mark Wibrow and 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{Design Principles}
+
+\pgfname{} needs to perform many computations while typesetting a
+picture. For this, \pgfname\ relies on a mathematical engine, which
+can also be used independently of \pgfname, but which is distributed
+as part of the \pgfname\ package nevertheless. Basically, the engine
+provides a parsing mechanism similar to the \calcname{} package so
+that expressions like |2*3cm+5cm| can be parsed; but the \pgfname\
+engine is more powerful and can be extended and enhanced.
+
+\pgfname{} provides enhanced functionality, which permits the parsing
+of mathematical operations involving integers and non-integers
+with or without units. Furthermore, various functions, including
+trigonometric functions and random number generators can also be
+parsed (see Section~\ref{pgfmath-parsing}).
+The \calcname{} macros |\setlength| and friends have \pgfname{} versions
+which can parse these operations and functions
+(see Section~\ref{pgfmath-registers}). Additionally, each operation
+and function has an independent \pgfname{} command associated with it
+(see Section~\ref{pgfmath-commands}), and can be
+accessed outside the parser.
+
+The mathematical engine of \pgfname\ is implicitly used whenever you
+specify a number or dimension in a higher-level macro. For instance,
+you can write |\pgfpoint{2cm+4cm/2}{3cm*sin(30)}| or
+suchlike. However, the mathematical engine can also be used
+independently of the \pgfname\ core, that is, you can also just load
+it to get access to a mathematical parser.
+
+
+\subsection{Loading the Mathematical Engine}
+
+The mathematical engine of \pgfname\ is loaded automatically by
+\pgfname, but if you wish to use the mathematical engine but you do
+not need \pgfname\ itself, you can load the following package:
+
+\begin{package}{pgfmath}
+ This command will load the mathematical engine of \pgfname, but not
+ \pgfname\ itself. It defines commands like |\pgfmathparse|.
+\end{package}
+
+
+\subsection{Layers of the Mathematical Engine}
+
+Like \pgfname\ itself, the mathematical engine is also structured into
+different layers:
+
+\begin{enumerate}
+\item The top layer, which you will typically use directly, provides
+ the command |\pgfmathparse|. This command parses a mathematical
+ expression and evaluates it.
+
+ Additionally, the top layer also defines some additional functions
+ similar to the macros of the |calc| package for setting dimensions
+ and counters. These macros are just wrappers around the
+ |\pgfmathparse| macro.
+\item The calculation layer provides macros for performing one
+ specific computation like computing a reciprocal or a
+ multiplication. The parser uses these macros for the actual
+ computation.
+\item The implementation layer provides the actual implementations of
+ the computations. These can be changed (and possibly be made more
+ efficient) without affecting the higher layers.
+\end{enumerate}
+
+
+
+\subsection{Efficiency and Accuracy of the Mathematical Engine}
+
+Currently, the mathematical algorithms are all implemented in \TeX.
+This poses some intriguing programming challenges as \TeX{} is a
+typesetting language not a mathematical one, and as with any
+programming language, there is a trade-off between accuracy and
+efficiency. If you find the level of accuracy insufficient for you
+purposes, you will have to replace the algorithms in the
+implementation layer.
+
+All the fancy mathematical ``bells-and-whistles'' that the parser
+provides, come with an additional processing cost, and in some
+instances, such as simply setting a length to |1cm|, with no other
+operations involved, the addition processing time is undesirable.
+To overcome this, the following feature is implemented: when no
+mathematical operations are required, the value in \meta{expression}
+can be preceded by |+|. This will bypass the parsing process and the
+assignment will be orders of magnitude faster. This feature
+\emph{only} works with the macros for setting registers described in
+Section~\ref{pgfmath-registers}.
+
+\begin{codeexample}[code only]
+\pgfmathsetlength\mydimen{1cm} % parsed : slower.
+\pgfmathsetlength\mydimen{+1cm} % not parsed : much faster.
+\end{codeexample}
+
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex
new file mode 100644
index 00000000000..0ff8c958520
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex
@@ -0,0 +1,641 @@
+% Copyright 2007 by Mark Wibrow
+%
+% 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{Evaluating Mathematical Expressions}
+
+The easiest way of using \pgfname's mathematical engine is to provide
+a mathematical expression given in the usual infix notation (such as
+|1cm+4*2cm/5.5| or |2*3+3*sin(30)|). This expression can be parsed by
+the mathematical engine and the result be placed in a dimension
+register, a counter, or a macro. Supported are infix mathematical
+operations involving integers and non-integers, with or without
+units.
+
+It should be noted that all
+calculations must not exceed $\pm16383.99999$ at \emph{any} point,
+because the underlying algorithms relie on \TeX{} dimensions. This
+means that many of the underlying algorithms are necessarily
+approximate. It also means that some of the algorithms are not very
+fast. \TeX{} is, after all, a typesetting language and not ideally
+suited to relatively advanced mathematical operations. However, it is
+possible to change the algorithms as described in
+Section~\ref{pgfmath-reimplement}.
+
+In the present section, the high-level macros for parsing an
+expression are explained first, then the syntax for expression is
+explained.
+
+
+\subsection{Commands for Parsing Expressions}
+
+\label{pgfmath-registers}
+
+\label{pgfmath-parsing}
+
+The basic command for invoking the parser of \pgfname's mathematical
+engine is the following:
+
+\begin{command}{\pgfmathparse\marg{expression}}
+ This macro parses \meta{expression} and returns the result without
+ units in the macro |\pgfmathresult|.
+
+ \example |\pgfmathparse{2pt+3.5pt}| will set |\pgfmathresult| to the
+ text |5.5|.
+
+ In the following, the special properties of this command are
+ explained. The exact syntax of mathematical expressions is explained
+ in Section~\ref{pgfmath-syntax}. Note that unlike the rest of the
+ manual, the examples show the result of the calculation (that is,
+ the value of the macro |\pgfmathresult|), not what is displayed in
+ the document.
+
+ \begin{itemize}
+ \item
+ The result stored in the macro |\pgfmathresult| is a decimal
+ \emph{without units}. This is true regardless of whether the
+ \meta{expression} contains any unit specification. But, any units
+ specified will be converted to points first.
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2pt+3.4pt}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2cm+3.4cm}
+\end{codeexample}
+
+ \item If no units are specified \emph{at any point} in the
+ expression, the result will be multiplied by the value in
+ |\pgfmathresultunitscale|, which can be a number or a dimension
+ (which will be converted to points). By default it is set to 1,
+ but can be changed with |\pgfmathsetresultunitscale|. Note that
+ the result will still be a number \emph{without} units.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2pt+3.4pt}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathsetresultunitscale{1cm}
+\pgfmathparse{2+3.4}
+\end{codeexample}
+
+ \pgfmathsetresultunitscale{1pt}
+
+ \item You can check whether an expression contained a unit using
+ the \TeX-if |\||ifpgfmathunitsdeclared|. After a call
+ of |\pgfmathparse| this if will be true exactly if some unit was
+ encountered in the expression.
+
+ \item The parser handles numbers with or without units regardless
+ of the operation.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{54pt/3cm*2.1}
+\end{codeexample}
+
+ \item the parser can cope with \TeX{} registers, including those
+ preceded by |\the|.
+
+ \makeatletter
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgf@x=12.34pt
+\c@pgf@counta=5
+\pgfmathparse{\pgf@x+\c@pgf@counta*6}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgf@x=56.78pt
+\pgfmathparse{\pgf@x+\the\pgf@x}
+\end{codeexample}
+
+ \item \TeX{} dimension registers can be multiplied without the |*|
+ operator by preceding them with a number (\emph{not} a function),
+ or a count register.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\c@pgf@counta=-4
+\pgf@x=10pt
+\pgfmathparse{.5\pgf@x-\c@pgf@counta\pgf@x}%
+\end{codeexample}
+
+ \item Parenthesis can be used to group operations.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{(4pt+0.5)*3}
+\end{codeexample}
+
+ \item functions are recognized, so it is possible to parse
+ |sin(.5*pi r)*60|, which means ``the sine of $0.5$ times $\pi$
+ radians, multiplied by 60''. The argument of most functions can
+ be any expression.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{sin(pi/2 r)*60}
+\end{codeexample}
+
+ \item Scientific notation in the form |1.234e+4| is recognised (but
+ the restriction on the range of values still applies). The exponent
+ symbol can be upper or lower case (i.e., |E| or |e|).
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{1.234567891e-2}
+\end{codeexample}
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{1.234567891e4}
+\end{codeexample}
+ \end{itemize}
+\end{command}
+
+\begin{command}{\pgfmathqparse\marg{expression}}
+ This macro is similar to |\pgfmathparse|: it parses
+ \meta{expression} and returns the result in the macro
+ |\pgfmathresult|. It differs in two respects. Firstly,
+ |\pgfmathqparse| does not parse functions or scientific
+ notation.
+ Secondly, numbers in \meta{expression} \emph{must}
+ specify a \TeX{} unit (except in such instances as |0.5\pgf@x|),
+ which greatly simplifies the problem of parsing
+ of non-integers. As a result of these restrictions |\pgfmathqparse|
+ is about twice as fast as |\pgfmathparse|. Note that the result
+ will still be a number \emph{without} units.
+\end{command}
+
+\begin{command}{\pgfmathsetresultunitscale\marg{number or dimension}}
+ Sets the value in |\pgfmathresultunitscale|, which scales the result
+ of an expression parsed with |\pgfmathparse|, if that expression
+ contains no units \emph{at any point}. The argument can be an integer,
+ non-integer or a dimension, but the result will still be a number
+ \emph{without} units. Note, that this will affect |\pgfmathsetlength|
+ and friends, but not if the expression starts with |+| (which
+ switches parsing off). By default the value in
+ |\pgfmathresultunitscale| is 1.
+\end{command}
+
+Instead of the |\pgfmathparse| macro you can also wrapper commands,
+whose usage is very similar to their cousins in the \calcname{}
+package. The only difference is that the expressions can be any
+expression that is handled by |\pgfmathparse|.
+
+For all of the following commands, if \meta{expression} starts with
+|+|, no parsing is done and a simple assignment or increment is done
+using normal \TeX\ assignments or increments. This will be orders of
+magnitude faster than calling the parser.
+
+\begin{command}{\pgfmathsetlength\marg{dimension register}\marg{expression}}
+ Sets the length of the \TeX{} \meta{dimension register}, to the value
+ (in points) specified by \meta{expression}. The \meta{expression}
+ will be parsed using |\pgfmathparse|.
+\end{command}
+
+\begin{command}{\pgfmathaddtolength\marg{dimension register}\marg{expression}}
+ Adds the value (in points) of \meta{expression} to the \TeX{}
+ \meta{dimension register}.
+\end{command}
+
+\begin{command}{\pgfmathsetcount\marg{count register}\marg{expression}}
+ Sets the value of the \TeX{} \meta{count register}, to the
+ \emph{truncated} value specified by \meta{expression}.
+\end{command}
+
+\begin{command}{\pgfmathaddtocount\marg{count register}\marg{expression}}
+ Adds the \emph{truncated} value of \meta{expression} to the \TeX{}
+ \meta{count register}.
+\end{command}
+
+\begin{command}{\pgfmathsetcounter\marg{counter}\marg{expression}}
+ Sets the value of the \meta{counter}, to the \emph{truncated} value
+ specified by \meta{expression}.
+\end{command}
+
+\begin{command}{\pgfmathaddtocounter\marg{counter}\marg{expression}}
+ Adds the \emph{truncated} value of \meta{expression} to
+ \meta{counter}.
+\end{command}
+
+% \begin{command}{\pgfmathnewcounter\marg{counter}}
+% This is simply a version of the \LaTeX{} macro |\newcounter|,
+% implemented to maintain consistency (consistency is good,
+% inconsistency is evil). Considering |\pgfmathnewcounter{foo}|, this
+% creates a new count register |\c@foo|, and a macro |\thefoo|, which
+% returns the value in |\c@foo|.
+% \end{command}
+
+\begin{command}{\pgfmathsetmacro\marg{macro}\marg{expression}}
+ Defines \meta{macro} as the value of \meta{expression}. The result
+ is a decimal \emph{without} units.
+\end{command}
+
+
+
+\subsection{Syntax for mathematical expressions}
+
+\label{pgfmath-syntax}
+
+The syntax for the expressions recognized by |\pgfmathparse| and
+friends is based on the syntax recognized by \textsc{matlab}. The
+following operations and functions are currently recognized:
+
+\begin{math-operator}{\mvar{x}\ +\ \mvar{y}}
+ Adds \mvar{y} to \mvar{x}.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{4+2pt}
+\end{codeexample}
+\end{math-operator}
+
+\begin{math-operator}{\mvar{x}\ -\ \mvar{y}}
+ Subtracts \mvar{y} from \mvar{x}.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{155.35-4cm}
+\end{codeexample}
+\end{math-operator}
+\begin{math-operator}{\mvar{x}\ *\ \mvar{y}}
+ Multiplies \mvar{x} by \mvar{y}.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{3.9pt*4.56}
+\end{codeexample}
+
+\end{math-operator}
+\begin{math-operator}{\mvar{x}\ /\ \mvar{y}}
+ Divides \mvar{x} by \mvar{y}.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{-31.6pt/17}
+\end{codeexample}
+
+\end{math-operator}
+\begin{math-operator}{\mvar{x}\ {\char94}\ \mvar{y}}
+
+Raises \mvar{x} to the power \mvar{y}. \mvar{y} should be an integer, but it can be negative.
+
+{
+\catcode`\^=7
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2.3^4}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2^-4}
+\end{codeexample}
+}
+\end{math-operator}
+
+\begin{math-operator}{\mvar{x}\ ==\ \mvar{y}}
+
+ This evaluates to |1| if \mvar{x} equals \mvar{y}, or |0| if \mvar{x}
+ does not equal \mvar{y}.
+ Note that equalities (and inequalities) are evaluated left to right,
+ and are only evaluated when another equality (or inequality) operator
+ is scanned, or the end of the current group or parse is reached. So
+ |5+4==3+2==9| results in |0| because |5+4| does not equal |3+2|,
+ resulting in zero, and the second equality is therefore evaluating
+ |0==9|.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{3*5 == 15}
+\end{codeexample}
+
+\end{math-operator}
+
+
+\begin{math-operator}{\mvar{x}\ >\ \mvar{y}}
+
+ This evaluates to |1| if \mvar{x} is greater than \mvar{y}, or |0| if
+ \mvar{x} is smaller or equal to \mvar{y}.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{17 > 4.2*1.97+4}
+\end{codeexample}
+
+\end{math-operator}
+
+\begin{math-operator}{\mvar{x}\ <\ \mvar{y}}
+
+ This evaluates to |1| if \mvar{x} is smaller than \mvar{y}, or |0| if
+ \mvar{x} is greater or equal to \mvar{y}.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2 < -5.2/-3.6-2}
+\end{codeexample}
+
+\end{math-operator}
+
+\begin{math-function}{mod(\mvar{x},\mvar{y})}
+ This evaluates \mvar{x} modulo \mvar{y}. This function cannot be
+ nested inside itself or the functions |max|, |min| or |veclen|.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{mod(20,6)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{max(\mvar{x},\mvar{y})}
+ This evaluates to the maximum of \mvar{x} or \mvar{y}. This function
+ cannot be nested inside itself or the functions |min|, |mod| or
+ |veclen|.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{max(17,23)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{min(\mvar{x},\mvar{y})}
+ This evaluates to the minimum of \mvar{x} or \mvar{y}. This function
+ cannot be nested inside itself or the functions |max|, |mod| or
+ |veclen|.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{min(17,23)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{abs(\mvar{x})}
+
+ Evaluates the absolute value of $x$.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{abs(-5)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{-abs(4*-3)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{round(\mvar{x})}
+
+ Rounds \mvar{x} to the nearest integer. It uses ``asymmetric half-up''
+ rounding. So |1.5| is rounded to |2|, but |-1.5| is rounded to |-2|
+ (\emph{not} |0|).
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{round(32.5/17)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{round(398/12)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{floor(\mvar{x})}
+
+ Rounds \mvar{x} down to the nearest integer.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{floor(32.5/17)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{floor(398/12)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{ceil(\mvar{x})}
+
+ Rounds \mvar{x} up to the nearest integer.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{ceil(32.5/17)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{ceil(398/12)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{exp(\mvar{x})}
+{
+\catcode`\^=7
+
+ Maclaurin series for $e^\textrm{\mvar{x}}$.
+}
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{exp(1)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{exp(2.34)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{pow(\mvar{x},\mvar{y})}
+
+ Raises \mvar{x} to the power \mvar{y}. \mvar{y} should be an integer, but it can be negative.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{pow(2,7)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{sqrt(\mvar{x})}
+
+ Calculates $\sqrt{\textrm{\mvar{x}}}$.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{sqrt(10)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{sqrt(8765.432)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{veclen(\mvar{x},\mvar{y})}
+
+ Evaluates the Euclidean distance from |(0,0)| to |(|\mvar{x}|,|\mvar{y}|)|.
+ This function cannot be nested inside itself, or the functions |max|,
+ |min| or |mod|.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{veclen(15,14)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{veclen(3,4)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-constant}{pi}
+
+ The constant $\pi=3.14159$.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{pi}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{pi r}
+\end{codeexample}
+
+\end{math-constant}
+
+\begin{math-operator}{\mvar{x}\ r}
+
+ This converts \mvar{x} from radians to degrees. Note that |r| will
+ evaluate any preceding series of multiplication or division
+ \emph{before} conversion, but not other operations. So |3*4/6r|
+ converts 2 radians to degrees, but |3-4+6r|, converts 6 radians to
+ degrees and adds the result to |-1|.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2*pi r-pi r}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2*pi/8 r}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{sin(3*pi/2r)*60}
+\end{codeexample}
+
+\end{math-operator}
+
+\begin{math-function}{rad(\mvar{x})}
+
+ Convert \mvar{x} to radians. \mvar{x} is assumed to be in degrees.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{rad(90)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{deg(\mvar{x})}
+
+ Convert \mvar{x} to degrees. \mvar{x} is assumed to be in radians.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{deg(3*pi/2)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{sin(\mvar{x})}
+
+ Sine of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
+ radians.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{sin(60)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{sin(pi/3 r)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{cos(\mvar{x})}
+
+ Cosine of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
+ radians.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{cos(60)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{cos(pi/3 r)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{tan(\mvar{x})}
+
+ Tangent of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
+ radians.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{tan(45)}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{tan(2*pi/8 r)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{asin(\mvar{x})}
+
+ Arcsine of \mvar{x}. The result is in degrees.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{asin(0.7071)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{acos(\mvar{x})}
+
+ Arccosine of \mvar{x} in degrees.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{acos(0.5)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{atan(\mvar{x})}
+
+ Arctangent of $x$ in degrees.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{atan(1)}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{rnd}
+
+ Generates a pseudo-random number between 0 and 1.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{rnd}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{2*rnd}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{-rnd+5}
+\end{codeexample}
+
+\end{math-function}
+
+\begin{math-function}{rand}
+
+ Generates a pseudo-random number between -1 and 1.
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{rand}
+\end{codeexample}
+
+\begin{codeexample}[post=\tt\footnotesize\pgfmathresult]
+\pgfmathparse{rand*15}
+\end{codeexample}
+
+\end{math-function}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex
new file mode 100644
index 00000000000..9e792f468cb
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex
@@ -0,0 +1,473 @@
+% Copyright 2006 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{Date and Calendar Utility Macros}
+\label{section-calendar}
+
+This section describes the package |pgfcalendar|.
+
+\begin{package}{pgfcalendar}
+ This package can be used independently of \pgfname. It has two
+ purposes:
+ \begin{enumerate}
+ \item It provides functions for working with dates. Most noticably,
+ it can convert a date in ISO-standard format (like 1975-12-26) to
+ a so-called Julian day number, which is defined in Wikipedia as
+ follows: ``The Julian day or Julian day number is the
+ (integer) number of days that have elapsed since the initial epoch
+ at noon Universal Time (UT) Monday, January 1, 4713 BC in the
+ proleptic Julian calendar.'' The package also provides a function
+ for converting a Julian day number to an ISO-format date.
+
+ Julian day numbers make it very easy to work with days. For
+ example, the date ten days in the future of 2008-02-20 can
+ be computed by converting this date to a Julian day number, adding
+ 10, and then converting it back. Also, the day of week of a given
+ date can be computed by taking the Julian day number modulo~7.
+ \item It provides a macro for typesetting a calendar. This macro
+ is highly configurable and flexible (for example, it can produce
+ both plain text calendars and also complicated \tikzname-based
+ calendars), but most users will not use the macro directly. It is
+ the job of a frontend to provide useful configruations for
+ typesetting calendars based on this command.
+ \end{enumerate}
+\end{package}
+
+
+\subsection{Handling Dates}
+
+\subsubsection{Conversions Between Date Types}
+
+\begin{command}{\pgfcalendardatetojulian\marg{date}\marg{counter}}
+ This macro converts a date in a format to be described in a moment
+ to the Julian day number in the Gregorian calendar. The \meta{date}
+ should expand to a string of the following form:
+ \begin{enumerate}\label{calendar-date-format}
+ \item It should start with a number representing the year. Use
+ |\year| for the current year, that is, the year the file is being
+ typeset.
+ \item The year must be followed by a hyphen.
+ \item Next should come a number representing the month. Use |\month|
+ for the current month. You can, but need not, use leading
+ zeros. For example, |02| represents February, just like |2|.
+ \item The month must also be followed by a hyphen.
+ \item Next you must either provide a day of month (again, a number
+ and, again, |\day| yields the current day of month) or the keyword
+ |last|. This keyword refers to the last day of the month, which is
+ automatically computed (and which is a bit tricky to compute,
+ especially for February).
+ \item Optionally, you can next provide a plus sign followed by
+ positive or negative number. This number of days will be added to
+ the computed date.
+ \end{enumerate}
+
+ Here are some examples:
+ \begin{itemize}
+ \item |2006-01-01| refers to the first day of 2006.
+ \item |2006-02-last| refers to February 28, 2006.
+ \item |\year-\month-\day| refers to today.
+ \item |2006-01-01+2| refser to January 3, 2006.
+ \item |\year-\month-\day+1| refers to tomorrow.
+ \item |\year-\month-\day+-1| refers to yesterday.
+ \end{itemize}
+
+ The conversion method is taken from the English Wikipedia entry on
+ Julian days.
+
+ \newcount\mycount
+ \example |\pgfcalendardatetojulian{2007-01-14}{\mycount}| sets
+ |\mycount| to
+ \pgfcalendardatetojulian{2007-01-14}{\mycount}\the\mycount.
+
+
+\end{command}
+
+\begin{command}{\pgfcalendarjuliantodate\marg{Julian day}\marg{year
+ macro}\marg{month macro}\marg{day macro}}
+ This command converts a Julian day number to an ISO-date. The
+ \meta{Julian day} must be a number or \TeX\ counter, the \meta{year macro},
+ \meta{month macro} and \meta{day macro} must be \TeX\ macro
+ names. They will be set to numbers representing the year, month, and
+ day of the given Julian day in the Gregorian calendar.
+
+ The \meta{year macro} will be assigned the year without leading
+ zeros. Note that this macro will produce year 0 (as opposed to other
+ calendars, where year 0 does not exist). However, if you really need
+ calendars for before the year 1, it is expected that you know what
+ you are doing anyway.
+
+ The \meta{month macro} gets assigned a two-digit number representing
+ the month (with a leading zero, if necessary). Thus, the macro is
+ set to |01| for January.
+
+ The \meta{day macro} gets assigned a two-digit number representing
+ the day of the month (again with a possible leading zero).
+
+ To convert a Julian day number to an ISO-date you use code like the
+ following:
+\begin{verbatim}
+\pgfcalendardatetojulian{2454115}{\myyear}{\mymonth}{\myday}
+\edef\isodate{\myyear-\mymonth-\myday}
+\end{verbatim}
+ The above code sets |\isodate| to
+ \pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday}%
+ \edef\isodate{\myyear-\mymonth-\myday}\texttt{\isodate}.
+\end{command}
+
+
+\begin{command}{\pgfcalendarjuliantoweekday\marg{Julian day}\marg{week day counter}}
+ This command converts a Julian day to a week day by computing the
+ day modulo 7. The \meta{week day counter} must be a \TeX\
+ counter. It will be set to 0 for a Monday, to 1 for a Tuesday, and
+ so on.
+
+ \example |\pgfcalendarjuliantoweekday{2454115}{\mycount}| sets
+ |\mycount| to
+ \pgfcalendarjuliantoweekday{2454115}{\mycount}\the\mycount.
+\end{command}
+
+
+\subsubsection{Checking Dates}
+
+
+\begin{command}{\pgfcalendarifdate\marg{date}\marg{tests}\marg{code}\marg{else code}}
+ \label{pgfcalendarifdate}
+ This command is used to execute code based on properties of
+ \meta{date}. The \meta{date} must be a date in ISO-format. For
+ this date, the \meta{tests} are checked (to be detailed later)
+ and if one of the tests applied, the \meta{code} is
+ executed. If none of the tests applies, the \meta{else code} is
+ executed.
+
+ \example |\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is not a Wednesday}|
+ yields \texttt{\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a
+ Wednesday}{Is not a Wednesday}}.
+
+ The \meta{tests} is a comma-separated list of key-value
+ pairs. The following are defined by default:
+ \begin{itemize}
+ \itemcalendaroption{all} This test is passed by all dates.
+ \itemcalendaroption{Monday} This test is passed by all dates that
+ are Mondays.
+ \itemcalendaroption{Tuesday} as above.
+ \itemcalendaroption{Wednesday} as above.
+ \itemcalendaroption{Thursday} as above.
+ \itemcalendaroption{Friday} as above.
+ \itemcalendaroption{Saturday} as above.
+ \itemcalendaroption{Sunday} as above.
+ \itemcalendaroption{workday} Passed by Mondays, Tuesdays,
+ Wednesdays, Thursdays, and Fridays.
+ \itemcalendaroption{weekend} Passed Saturdays and Sundays.
+ \itemcalendaroption{equals}|=|\meta{reference} The \meta{reference}
+ can be in one of two forms: Either, it is a full ISO format date
+ like |2007-01-01| or the year may be missing as in |12-31|. In the
+ first case, the test is passed if \meta{date} is the same as
+ \meta{reference}. In the second case, the test is passed if the
+ month and day part of \meta{date} is the same as \meta{reference}.
+
+ For example, the test |equals=2007-01-10| will only be passed by this
+ particular date. The test |equals=05-01| will be passed by every first
+ of May on any year.
+ \itemcalendaroption{at least}|=|\meta{reference} This test works
+ similarly to the |equals| test, only it is checked whether
+ \meta{date} is equal to \meta{reference} or to any later
+ date. Again, the \meta{reference} can be a full date like
+ |2007-01-01| or a short version like |07-01|. For example,
+ |at least=07-01| is true for every day in the second half of any
+ year.
+ \itemcalendaroption{at most}|=|\meta{reference} as above.
+ \itemcalendaroption{between}|=|\meta{start reference}| and |\meta{end
+ refernce} This test checks whether the current date lies between
+ the two given reference dates. Both full and short version may be
+ given.
+
+ For example |between=2007-01-01 and 2007-02-28| is true for the days
+ in January and February of 2007.
+
+ For another example, |between=05-01 and 05-07| is true for the
+ days of the first week of May of any year.
+ \itemcalendaroption{day of month}|=|\meta{number} Passed by the day
+ of month of the \meta{date} is \meta{number}. For example, the test
+ |day of month=1| is passed by every first of every month.
+ \itemcalendaroption{end of month}\opt{|=|\meta{number}} Passed by
+ the day of month of the \meta{date} that is \meta{number} from the
+ end of the month. For example, the test |end of month=1| is passed
+ by the last day of every month, the test |end of month=2| is passed
+ by the second last day of every month. If \meta{number} is omitted,
+ it is assumed to be |1|.
+ \end{itemize}
+
+ In addition to the above checks, you can also define new checks. To
+ do so, you must add a new key to the key-value group |pgfcalendar|
+ using |\define@key|. The job of the code of this new key is to
+ possibly set the \TeX-if |\ifpgfcalendarmatches| to true (if it is
+ already true, no action should be taken) to indicate that the
+ \meta{date} passes the test setup by this new key.
+
+ In order to perform the test, the key code needs to know the date
+ that should be checked. The date is available through a macro, but a
+ whole bunch of additional information about this date is also
+ available through the following macros:
+ \begin{itemize}
+ \item |\pgfcalendarifdatejulian|
+ is the Julian day number of the \meta{date} to be checked.
+ \item |\pgfcalendarifdateweekday|
+ is the weekday of the \meta{date} to be checked.
+ \item |\pgfcalendarifdateyear|
+ is the year of the \meta{date} to be checked.
+ \item |\pgfcalendarifdatemonth|
+ is the month of the \meta{date} to be checked.
+ \item |\pgfcalendarifdateday|
+ is the day of month of the \meta{date} to be checked.
+ \end{itemize}
+
+ For example, let us define a new key that checks whether the
+ \meta{date} is a Workers day (first of May). This can be done as
+ follows:
+\begin{verbatim}
+\define@key{pgfcalendar}{workers day}[]
+{
+ \ifnum\pgfcalendarifdatemonth=5\relax
+ \ifnum\pgfcalendarifdateday=1\relax
+ \pgfcalendarmatchestrue
+ \fi
+ \fi
+}
+\end{verbatim}
+\end{command}
+
+
+\subsubsection{Typesetting Dates}
+
+
+
+
+\begin{command}{\pgfcalendarweekdayname\marg{week day number}}
+ This command expands to a textual representation of the day of week,
+ given by the \meta{week day number}. Thus,
+ |\pgfcalendarweekdayname{0}| expands to |Monday| if the current
+ language is English and to |Montag| if the current language is
+ German, and so on. See Section~\ref{section-calendar-locale} for
+ more details on translations.
+
+ \example |\pgfcalendarweekdayname{2}| yields
+ \texttt{\pgfcalendarweekdayname{2}}.
+\end{command}
+
+
+\begin{command}{\pgfcalendarweekdayshortname\marg{week day number}}
+ This command works similiarly to the previous command, only an
+ abbreviated version of the week day is produced.
+
+ \example |\pgfcalendarweekdayshortname{2}| yields
+ \texttt{\pgfcalendarweekdayshortname{2}}.
+\end{command}
+
+
+\begin{command}{\pgfcalendarmonthname\marg{month number}}
+ This command expands to a textual representation of the month, which
+ is given by the \meta{month number}.
+
+ \example |\pgfcalendarmonthname{12}| yields
+ \texttt{\pgfcalendarmonthname{12}}.
+\end{command}
+
+
+\begin{command}{\pgfcalendarmonthshortname\marg{month number}}
+ As above, only an abbreviated version is produced.
+
+ \example |\pgfcalendarmonthshortname{12}| yields
+ \texttt{\pgfcalendarmonthshortname{12}}.
+\end{command}
+
+
+
+\subsubsection{Localization}
+
+\label{section-calendar-locale}
+All textual representations of week days or months (like ``Monday'' or
+``February'') are wrapped with |\translate| commands from the
+|translator| package (it this package is not loaded, no translation
+takes place). Furthermore, the |pgfcalendar| package will try to load
+the |translator-months-dictionary|, if the |translator| package is
+loaded.
+
+The net effect of all this is that all dates will be translated to the
+current language setup in the |translator| package. See the
+documentation of this package for more details.
+
+
+
+\subsection{Typesetting Calendars}
+
+\begin{command}{\pgfcalendar\marg{prefix}\marg{start date}\marg{end
+ date}\marg{rendering code}}
+ This command can be used to typeset a calendar. It is a very general
+ command, the actual work has to be done by giving clever
+ implementations of \meta{rendering code}. Note that this macro need
+ \emph{not} be called inside a |{pgfpicture}| environment (even
+ though it typically will be) and you can use it to typeset calendars
+ in normal \TeX\ or using packages other than \pgfname.
+
+ \medskip
+ \textbf{Basic typesetting process.}
+ A calendar is typeset as follows: The \meta{start date} and
+ \meta{end date} specify a range of dates. For each date in this
+ range the \meta{rendering code} is executed with certain macros
+ setup to yield information about the \emph{current date}
+ (the current date in the enumeration of dates of the
+ range). Typically, the \meta{rendering code} places nodes inside a
+ picture, but it can do other things as well. Note that it is also
+ the job of the \meta{rendering code} to position the calendar
+ correctly.
+
+ The different calls of the \meta{rending code} are not
+ surrounded by \TeX\ groups (though you can do so yourself, of
+ course). This means that settings can accumulate between different
+ calls, which is often desirable and useful.
+
+ \medskip
+ \textbf{Information about the current date.}
+ Inside the \meta{rendering code}, different macros can be access:
+
+ \begin{itemize}
+ \item |\pgfcalendarprefix|
+ The \meta{prefix} parameter. This prefix is recomended for nodes
+ inside the calendar, but you have to use it yourself explicitly.
+ \item |\pgfcalendarbeginiso|
+ The \meta{start date} of range being typeset in ISO format (like 2006-01-10).
+ \item |\pgfcalendarbeginjulian|
+ Julian day number of \meta{start date}.
+ \item |\pgfcalendarendiso|
+ The \meta{end date} of range being typeset in ISO format.
+ \item |\pgfcalendarendjulian|
+ Julian day number of \meta{end date}.
+ \item |\pgfcalendarcurrentjulian| This \TeX\ count holds the
+ Julian day number of day currently begin rendered.
+ \item |\pgfcalendarcurrentweekday| The weekday
+ (a number with zero representing Monday) of the current date.
+ \item |\pgfcalendarcurrentyear| The year of the current date.
+ \item |\pgfcalendarcurrentmonth| The month of the current date
+ (always two digits with a leading zero, if necessary).
+ \item |\pgfcalendarcurrentday| The day of month of the current date
+ (alwyas two digits).
+ \end{itemize}
+
+ \medskip
+ {\bfseries The |\ifdate| command.}
+ Inside the |\pgfcalendar| the macro |\ifdate| is available
+ locally:
+ \begin{command}{\ifdate\marg{tests}\marg{code}\marg{else code}}
+ \label{ifdate}%
+ This command has the same effect as calling |\pgfcalendarifdate|
+ for the current date.
+ \end{command}
+
+ \medskip
+ \textbf{Examples.}
+ In a first example, let us create a very simple calendar: It just
+ lists the dates in a certain range.
+\begin{codeexample}[vbox,ignorespaces]
+\pgfcalendar{cal}{2007-01-20}{2007-02-10}{\pgfcalendarcurrentday\ }
+\end{codeexample}
+ Let us now make this a little more interesting: Let us add a line
+ break after each Sunday.
+\begin{codeexample}[vbox,ignorespaces]
+\pgfcalendar{cal}{2007-01-20}{2007-02-10}
+{
+ \pgfcalendarcurrentday\
+ \ifdate{Sunday}{\par}{}
+}
+\end{codeexample}
+ We now want to have all Mondays to be aligned on a column. For this,
+ different approaches work. Here is one based positioning each day
+ horizontally using a skip.
+\begin{codeexample}[vbox,ignorespaces]
+\pgfcalendar{cal}{2007-01-20}{2007-02-10}
+{%
+ \leavevmode%
+ \hbox to0pt{\hskip\pgfcalendarcurrentweekday cm\pgfcalendarcurrentday\hss}%
+ \ifdate{Sunday}{\par}{}%
+}
+\end{codeexample}
+ Let us now typeset two complete months.
+\begin{codeexample}[vbox,ignorespaces]
+\pgfcalendar{cal}{2007-01-01}{2007-02-28}{%
+ \ifdate{day of month=1}{
+ \par\bigskip\hbox to7.5cm{\itshape\hss\pgfcalendarshorthand mt\hss}\par
+ }{}%
+ \leavevmode%
+ {%
+ \ifdate{weekend}{\color{black!50}}{\color{black}}%
+ \hbox to0pt{%
+ \hskip\pgfcalendarcurrentweekday cm%
+ \hbox to1cm{\hss\pgfcalendarshorthand d-}\hss%
+ }%
+ }%
+ \ifdate{Sunday}{\par}{}%
+}
+\end{codeexample}
+ For our final example, we use a |{tikzpicture}|.
+\begin{codeexample}[vbox,ignorespaces]
+\begin{tikzpicture}
+ \pgfcalendar{cal}{2007-01-20}{2007-02-10}{%
+ \ifdate{workday}{\tikzstyle{filling}=[fill=blue!20]}{\tikzstyle{filling}=[fill=red!20]}
+ \node (\pgfcalendarsuggestedname) at (\pgfcalendarcurrentweekday,0)
+ [anchor=base,circle,filling] {\pgfcalendarcurrentday};
+ \ifdate{Sunday}{\pgftransformyshift{-3em}}{}%
+ }
+ \draw (cal-2007-01-21) -- (cal-2007-02-03);
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+
+\begin{command}{\pgfcalendarshorthand\marg{kind}\marg{representation}}
+ \label{pgfcalendarshorthand}
+ This command can be used inside a |\pgfcalendar|, where it will
+ expand to a representation of the current day, month, year or day of
+ week, depending on whether \meta{kind} is |d|, |m|, |y| or |w|. The
+ \meta{representation} can be one of the following: |-|, |=|, |0|,
+ |.|, and |t|. They have the following meanings:
+ \begin{itemize}
+ \item The minus sign selects the shortest numerical representation
+ possible (no leading zeros).
+ \item The equal sign also selects the shortest numerical
+ representation, but a space is added to single digit days and
+ months (thereby ensuring that they have the same length as other
+ days).
+ \item The zero digit selects a two-digit numerical representation
+ for days and months. For years it is allowed, but has no effect.
+ \item The letter |t| selects a textual representation.
+ \item The dot selects an abbreviated textual representation.
+ \end{itemize}
+ Normally, you should say |\let\%=\pgfcalendarshorthand| locally, so
+ that you can write |\%wt| instead of the much more cumbersome
+ |\pgfcalendarshorthand{w}{t}|.
+
+\begin{codeexample}[leave comments]
+\let\%=\pgfcalendarshorthand
+\pgfcalendar{cal}{2007-01-20}{2007-01-20}
+{ ISO form: \%y0-\%m0-\%d0, long form: \%wt, \%mt \%d-, \%y0}
+\end{codeexample}
+\end{command}
+
+
+\begin{command}{\pgfcalendarsuggestedname}
+ This macro expands to a suggested name for nodes representing days
+ in a calendar. If the \meta{prefix} is empty, it expands to the
+ empty string, otherwise it expands to the \meta{prefix} of the
+ calendar, followed by a hyphen, followed by the ISO format version
+ of the date. Thus, when the date |2007-01-01| is typeset in a
+ calendar for the prefix |mycal|, the macro expands to
+ |mycal-2007-01-01|.
+\end{command}
+
+
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex
index a2be81b9d7d..fbd4820310d 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex
@@ -11,13 +11,14 @@
\section{Repeating Things: The Foreach Statement}
\label{section-foreach}
-In this section the package |pgffor.sty| is described. It can be used
-independently of \pgfname, but it works particularly well together with
-\pgfname\ and \tikzname.
+This section describes the package |pgffor|, which is loaded
+automatically by \tikzname, but not by \pgfname:
-When you say |\usepackage{pgffor}|, two commands are defined:
-|\foreach| and |\breakforeach|. Their behaviour is described in the
-following:
+\begin{package}{pgffor}
+ This package can be used independently of \pgfname, but works
+ particularly well together with \pgfname\ and \tikzname. It defines
+ two new commands: |\foreach| and |\breakforeach|.
+\end{package}
\begin{command}{\foreach| |\meta{variables}| in |\marg{list}
\meta{commands}}
@@ -47,7 +48,7 @@ following:
\medskip
\textbf{Syntax for the commands.}
- Let use move on to a more complicated setting. The first
+ Let us move on to a more complicated setting. The first
complication occurs when the \meta{commands} are not some text in
curly braces. If the |\foreach| statement does not encounter an
opening brace, it will instead scan everything up to the next
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex
index 33bca9f97ac..c4c8cb13ed2 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex
@@ -90,15 +90,6 @@ abbreviations:
Inside |{tikzpicture}| this is an abbreviation for |\path[use as bounding box]|.
\end{command}
-\begin{command}{\node}
- Inside |{tikzpicture}| this is an abbreviation for |\path node|. Note
- that, for once, |node| is not an option but a path operation.
-\end{command}
-
-\begin{command}{\coordinate}
- Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|.
-\end{command}
-
\subsection{Specifying a Color}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
index c10e98f39d5..d877d60e52a 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
@@ -250,6 +250,63 @@ Let us start with the basic coordinate systems.
\end{coordinatesystem}
+\subsubsection{Barycentric Systems}
+\label{section-barycentric-coordinates}
+
+In the barycentric coordinate system a point is expressed as the
+linear combination of multiple vectors. The idea is that you specify
+vectors $v_1$, $v_2$, \dots, $v_n$ and numbers $\alpha_1$, $\alpha_2$,
+\dots, $\alpha_n$. Then the barycentric coordinate specified by these
+vectors and numbers is
+\begin{align*}
+ \frac{\alpha_1 v_1 + \alpha_2 v_2 + \cdots + \alpha_n v_n}{\alpha_1
+ + \alpha_2 + \cdots + \alpha_n}
+\end{align*}
+
+The |barycentric cs| allows you to specifiy such coordiantes easily.
+
+\begin{coordinatesystem}{barycentric}
+ For this coordinate system, the \meta{coordinate specification}
+ should be a comma-separated list of expressions of the form
+ \meta{node name}|=|\meta{number}. Note that (currently) the list
+ should not contain any spaces before or after the \meta{node name}
+ (unlike normal key-value pairs).
+
+ The specified coordinate is now computed as follows: Each pair
+ provides one vector and a number. The vector is the |center| anchor
+ of the \meta{node name}. The number is the \meta{number}. Note that
+ (currently) you cannot specify a different anchor, so that in order
+ to use, say, the |north| anchor of a node you first have to create a
+ new coordinate at this north anchor. (Using for instance
+ \texttt{\string\coordinate (mynorth) at (mynode.north);}.)
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \coordinate (content) at (90:3cm);
+ \coordinate (structure) at (210:3cm);
+ \coordinate (form) at (-30:3cm);
+
+ \node [above] at (content) {content oriented};
+ \node [below left] at (structure) {structure oriented};
+ \node [below right] at (form) {form oriented};
+
+ \draw [thick,gray] (content.south) -- (structure.north east) -- (form.north west) -- cycle;
+
+ \small
+ \node at (barycentric cs:content=0.5,structure=0.1 ,form=1) {PostScript};
+ \node at (barycentric cs:content=1 ,structure=0 ,form=0.4) {DVI};
+ \node at (barycentric cs:content=0.5,structure=0.5 ,form=1) {PDF};
+ \node at (barycentric cs:content=0 ,structure=0.25,form=1) {CSS};
+ \node at (barycentric cs:content=0.5,structure=1 ,form=0) {XML};
+ \node at (barycentric cs:content=0.5,structure=1 ,form=0.4) {HTML};
+ \node at (barycentric cs:content=1 ,structure=0.2 ,form=0.8) {\TeX};
+ \node at (barycentric cs:content=1 ,structure=0.6 ,form=0.8) {\LaTeX};
+ \node at (barycentric cs:content=0.8,structure=0.8 ,form=1) {Word};
+ \node at (barycentric cs:content=1 ,structure=0.05,form=0.05) {ASCII};
+\end{tikzpicture}
+\end{codeexample}
+\end{coordinatesystem}
+
\subsubsection{Node Coordinate System}
\label{section-node-coordinates}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex
new file mode 100644
index 00000000000..b2b41bae9f2
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex
@@ -0,0 +1,725 @@
+% Copyright 2006 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{Matrices and Alignment}
+
+\label{section-matrices}
+
+\subsection{Overview}
+
+When creating pictures, one often faces the problem of correctly
+aligning parts of the picture. For example, you might wish that the
+base lines of certain nodes should be on the same line and some
+further nodes should be below these nodes with, say, their centers on
+a vertical lines. There are different ways of solving such
+problems. For example, by making clever use of anchors, nearly all
+such alignment problems can be solved. However, this often leads to
+complicated code. An often simpler way is to use \emph{matrices},
+the use of which is explaied in the current section.
+
+A \tikzname\ matrix is similar to \LaTeX's |{tabular}| or
+|{array}| environment, only instead of text each cell contains a
+little picture or a node. The sizes of the cells are automatically
+adjusted such that they are large enough to contain all the cell
+contents.
+
+Matrices are a powerful tool and they need to handled with some care.
+For impatient readers who skip the rest of this section: you
+\emph{must} end \emph{every} row with |\\|. In particular, the last
+row \emph{must} be ended with |\\|.
+
+Many of the ideas implemented in \tikzname's matrix support are due to
+Mark Wibrow -- many thanks to Mark at this point!
+
+
+
+\subsection{Matrices are Nodes}
+
+Matrices are special in many ways, but for most purposes matrices are
+treated like nodes. This means, that you use the |node| path command
+to create a matrix and you only use a special option, namely the
+|matrix| option, to signal that the node will contain a
+matrix. Instead of the usual \TeX-box that makes up the |text| part of
+the node's shape, the matrix is used. Thus, in particular, a matrix
+can have a shape, this shape can be drawn or filled, it can be used in
+a tree, and so on. Also, you can refer to the different anchors of a
+matrix.
+
+\begin{itemize}
+ \itemoption{matrix}\opt{|=|\meta{true or false}} This option can be
+ passed to a |node| path command. It signals that the node will contain
+ a matrix. The default parameter is |true| and should usually be
+ omitted.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (4,2);
+ \node [matrix,fill=red!20,draw=blue,very thick] (my matrix) at (2,1)
+ {
+ \draw (0,0) circle (4mm); & \node[rotate=10] {Hello}; \\
+ \draw (0.2,0) circle (2mm); & \fill[red] (0,0) circle (3mm); \\
+ };
+
+ \draw [very thick,->] (0,0) |- (my matrix.west);
+\end{tikzpicture}
+\end{codeexample}
+ The exact syntax of the matrix is explained in the course of this
+ section.
+ \itemstyle{every matrix}
+ This style is used in every matrix. It is empty by default.
+\end{itemize}
+
+Even more so than nodes, matrices will often be the only object on a
+path. Because of this, there is a special abbreviation for creating matrices:
+
+\begin{command}{\matrix}
+ Inside |{tikzpicture}| this is an abbreviation for |\path node[matrix]|.
+\end{command}
+
+Even though matrices are nodes, some options do not have the same
+effect as for normal nodes:
+\begin{enumerate}
+\item Rotations and scaling have no effect on a matrix as a whole
+ (however, you can still transform the contents of the cells
+ normally). Before the matrix is typeset, the rotational and scaling
+ part of the transformation matrix is reset.
+\item For multi-part shapes you can only set the |text| part of the
+ node.
+\item All options starting with |text| such as |text width| have no
+ effect.
+\end{enumerate}
+
+
+
+\subsection{Cell Pictures}
+
+A matrix consists of rows of \emph{cells}. Each row (including the
+last one!) is ended by the command |\\|. The character |&| is used
+to separate cells. Inside each cell, you must place commands for
+drawing a picture, called the \emph{cell picture} in the
+following. (However, cell pictures are not enclosed in a complete
+|{pgfpicture}| environment, they are a bit more light-weight. The main
+difference is that cell pictures cannot have layers.) It is not
+necessary to specify beforehand how many rows or columns there are
+going to be and if a row contains less cell pictures than another
+line, empty cells are automatically added as needed.
+
+
+\subsubsection{Alignment of Cell Pictures}
+
+For each cell picture a bounding box is computed. These bounding boxes
+and the origins of the cell pictures determine how the cells are
+aligned. Let us start with the rows: Consider the cell pictures on the first
+row. Each has a bounding box and somewhere inside this bounding box
+the origin of the cell picture can be found (the origin might even lie
+outside the bounding box, but let us ignore this problem for the
+moment). The cell pictures are then shifted around such that all
+origins lie on the same horizontal line. This may make it necessary to
+shift some cell pictures upwards and other downwards, but it can be
+done and this yields the vertical alignment of the cell pictures this
+row. The top of the row is then given by the top of the ``highest''
+cell picture in the row, the bottom of the row is given by the bottom
+of the lowest cell picture. (To be more precise, the height of the row
+is the maximum $y$-value of any of the bounding boxes and the depth of
+the row is the negated minimum $y$-value of the bounding boxes).
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every node}=[draw=black,anchor=base,font=\huge]
+
+ \matrix [draw=red]
+ {
+ \node {a}; \fill[blue] (0,0) circle (2pt); &
+ \node {X}; \fill[blue] (0,0) circle (2pt); &
+ \node {g}; \fill[blue] (0,0) circle (2pt); \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+Each row is aligned in this fashion: For each row the cell pictures
+are vertically aligned such that the origins lie on the same
+line. Then the second row is placed below the first row such that the
+bottom of the first row touches the top of the second row (unless a
+|row sep| is used to add a bit of space). Then the bottom of the
+second row touches the top of the third row, and so on. Typically,
+each row will have an individual height and depth.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every node}=[draw=black,anchor=base]
+
+ \matrix [draw=red]
+ {
+ \node {a}; & \node {X}; & \node {g}; \\
+ \node {a}; & \node {X}; & \node {g}; \\
+ };
+
+ \matrix [row sep=3mm,draw=red] at (0,-2)
+ {
+ \node {a}; & \node {X}; & \node {g}; \\
+ \node {a}; & \node {X}; & \node {g}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+Let us now have a look at the columns. The rules for how the pictures
+on any given column are aligned are very similar to the row
+alignment: Consider all cell pictures in the first column. Each is
+shifted horizontally such that the origins lie on the same vertical
+line. Then, the left end of the column is at the left end of the
+bounding box that protrudes furthest to the left. The right end of the
+column is at the right end of the bounding box that protrudes furthest
+to the left. This fixes the horizontal alignment of the cell pictures
+in the first column and the same happens the cell pictures in the
+other columns. Then, the right end of the first column touches the
+left end of the second column (unless |column sep| is used). The right
+end of the second column touches the left end of the third column, and
+so on. (Internally, two columns are actually used to achieve the
+desired horizontal alignment, but that is only and implementation
+detail.)
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every node}=[draw]
+ \matrix [draw=red]
+ {
+ \node[left] {Hallo}; \fill[blue] (0,0) circle (2pt); \\
+ \node {X}; \fill[blue] (0,0) circle (2pt); \\
+ \node[right] {g}; \fill[blue] (0,0) circle (2pt); \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every node}=[draw]
+ \matrix [draw=red,column sep=1cm]
+ {
+ \node {8}; & \node{1}; & \node {6}; \\
+ \node {3}; & \node{5}; & \node {7}; \\
+ \node {4}; & \node{9}; & \node {2}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+
+
+\subsubsection{Setting and Adjusting Column and Row Spacing}
+
+There are different ways of setting and adjusting the spacing between
+columns and rows. First, you can use the options |column sep| and
+|row sep| to set a default spacing for all rows and all
+columns. Second, you can add options to the |&| character and the |\\|
+command to adjust the spacing between two specific columns or
+rows. Additionally, you can specify whether the space between two
+columns or rows should be considered between the origins of cells in
+the column or row or between their borders.
+
+\begin{itemize}
+ \itemoption{column sep}|=|\meta{spacing list}
+ This option sets a default space that is added between every two
+ columns. This space can be positive or negative and is zero by
+ default. The \meta{spacing list} normally contains a single
+ dimension like |2pt|.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [draw,column sep=1cm,nodes=draw]
+ {
+ \node(a) {123}; & \node (b) {1}; & \node {1}; \\
+ \node {12}; & \node {12}; & \node {1}; \\
+ \node(c) {1}; & \node (d) {123}; & \node {1}; \\
+ };
+ \draw [red,thick] (a.east) -- (a.east |- c)
+ (d.west) -- (d.west |- b);
+ \draw [<->,red,thick] (a.east) -- (d.west |- b)
+ node [above,midway] {1cm};
+\end{tikzpicture}
+\end{codeexample}
+ More generally, the \meta{spacing list} may contain a whole list of
+ numbers, separated by commas, and occurrences of the two key words
+ |between origins| and |between borders|. The effect of specifying
+ such a list is the following: First, all numbers occurring in the
+ list are simply added to compute the final spacing. Second,
+ concerning the two keywords, the last occurrence of one of the keywords is
+ important. If the last occurrence is |between borders| or if neither
+ occurs, then the space is inserted between the two columns
+ normally. However, if the last occurs is |between origins|, then the
+ following happens: The distance between the columns is adjusted such
+ that the difference between the origins of all the cells in the
+ first column (remember that they all lie on straight line) and the
+ origins of all the cells in the second column is exactly the given
+ distance.
+
+ \emph{The |between origins| option can only be used for columns
+ mentioned in the first row, that is, you cannot specify this
+ option for columns introduced only in later rows.}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [draw,column sep={1cm,between origins},nodes=draw]
+ {
+ \node(a) {123}; & \node (b) {1}; & \node {1}; \\
+ \node {12}; & \node {12}; & \node {1}; \\
+ \node {1}; & \node {123}; & \node {1}; \\
+ };
+ \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {1cm};
+\end{tikzpicture}
+\end{codeexample}
+ \itemoption{row sep}|=|\meta{spacing list}
+ This option works like |column sep|, only for rows. Here, too, you
+ can specify whether the space is added between the lower end of the
+ first row and the upper end of the second row, or whether the space
+ is computed between the origins of the two rows.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [draw,row sep=1cm,nodes=draw]
+ {
+ \node (a) {123}; & \node {1}; & \node {1}; \\
+ \node (b) {12}; & \node {12}; & \node {1}; \\
+ \node {1}; & \node {123}; & \node {1}; \\
+ };
+ \draw [<->,red,thick] (a.south) -- (b.north) node [right,midway] {1cm};
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [draw,row sep={1cm,between origins},nodes=draw]
+ {
+ \node (a) {123}; & \node {1}; & \node {1}; \\
+ \node (b) {12}; & \node {12}; & \node {1}; \\
+ \node {1}; & \node {123}; & \node {1}; \\
+ };
+ \draw [<->,red,thick] (a.center) -- (b.center) node [right,midway] {1cm};
+\end{tikzpicture}
+\end{codeexample}
+\end{itemize}
+
+The row-end command |\\| allows you to provide an optional
+argument, which must be a dimension. This dimension will be added to
+the list in |row sep|. This means that, firstly, any numbers you list
+in this argument will be added as an extra row separation between the
+line being ended and the next line and, secondly, you can use the
+keywords |between origins| and |between borders| to locally overrule
+the standard setting for this line pair.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [row sep=1mm]
+ {
+ \draw (0,0) circle (2mm); & \draw (0,0) circle (2mm); \\
+ \draw (0,0) circle (2mm); & \draw (0,0) circle (2mm); \\[-1mm]
+ \draw (0,0) coordinate (a) circle (2mm); &
+ \draw (0,0) circle (2mm); \\[1cm,between origins]
+ \draw (0,0) coordinate (b) circle (2mm); &
+ \draw (0,0) circle (2mm); \\
+ };
+ \draw [<->,red,thick] (a.center) -- (b.center) node [right,midway] {1cm};
+\end{tikzpicture}
+\end{codeexample}
+
+The cell separation character |&| also takes an optional
+argument, which must also be a spacing list. This spacing list is
+added to the |column sep| having a similar effect as the option for
+the |\\| command for rows.
+
+This optional spacing list can only be given the first time
+a new column is started (usually in the first row), subsequent usages
+of this option in later rows have no effect.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [draw,nodes=draw,column sep=1mm]
+ {
+ \node {8}; &[2mm] \node{1}; &[-1mm] \node {6}; \\
+ \node {3}; & \node{5}; & \node {7}; \\
+ \node {4}; & \node{9}; & \node {2}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [draw,nodes=draw,column sep=1mm]
+ {
+ \node {8}; &[2mm] \node(a){1}; &[1cm,between origins] \node(b){6}; \\
+ \node {3}; & \node {5}; & \node {7}; \\
+ \node {4}; & \node {9}; & \node {2}; \\
+ };
+ \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {11mm};
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [draw,nodes=draw,column sep={1cm,between origins}]
+ {
+ \node (a) {8}; & \node (b) {1}; &[between borders] \node (c) {6}; \\
+ \node {3}; & \node {5}; & \node {7}; \\
+ \node {4}; & \node {9}; & \node {2}; \\
+ };
+ \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm};
+ \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway] {10mm};
+\end{tikzpicture}
+\end{codeexample}
+
+
+
+
+\subsubsection{Cell Styles and Options}
+
+For following style and option are useful for changing the appearance
+of the all cell pictures:
+\begin{itemize}
+ \itemstyle{every cell} This style is installed at the beginning of
+ each cell picture. Note that setting this style to |draw| will
+ \emph{not} cause all nodes to be drawn since the |draw| option has
+ to be passed to each node individually.
+
+ Inside this style (and inside all cells), the current row and column
+ number are accessible via the counters |\pgfmatrixcurrentrow| and
+ |\pgfmatrixcurrentcolumn|.
+ \itemoption{cells}|=|\meta{options} This option adds the
+ \meta{options} to the style |every cell|. It is just a shorthand for
+ |set style={{every cell}+=[|\meta{options}|]}|.
+ \itemoption{nodes}|=|\meta{options} This option adds the
+ \meta{options} to the style |every node|. It is just a shorthand for
+ |set style={{every node}+=[|\meta{options}|]}|.
+
+ The main use of this option is the install some options for the
+ nodes \emph{inside} the matrix that should not apply to the matrix
+ \emph{itself}.
+\end{itemize}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [nodes={fill=blue!20,minimum size=5mm}]
+ {
+ \node {8}; & \node{1}; & \node {6}; \\
+ \node {3}; & \node{5}; & \node {7}; \\
+ \node {4}; & \node{9}; & \node {2}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+The next set of styles can be used to change the appearance of certain
+rows, columns, or cells. If more than one of these styles is defined,
+they are executed in the below order (the |every cell| style is
+executed before all of the below).
+\begin{itemize}
+ \itemstyle{column \meta{number}}
+ This style is used for every cell in column \meta{number}.
+ \itemstyle{every odd column}
+ This style is used for every cell in an odd column.
+ \itemstyle{every even column}
+ This style is used for every cell in an even column.
+ \itemstyle{row \meta{number}}
+ This style is used for every cell in row \meta{number}.
+ \itemstyle{every odd row}
+ This style is used for every cell in an odd row.
+ \itemstyle{every even row}
+ This style is used for every cell in an even row.
+ \itemstyle{row \meta{row number} column \meta{column number}}
+ This style is used for the cell in row \meta{row number} and column
+ \meta{column number}.
+\end{itemize}
+
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{row 1}=[red]
+ \tikzstyle{column 2}=[green!50!black]
+ \tikzstyle{row 3 column 3}=[blue]
+
+ \matrix
+ {
+ \node {8}; & \node{1}; & \node {6}; \\
+ \node {3}; & \node{5}; & \node {7}; \\
+ \node {4}; & \node{9}; & \node {2}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+You can use the |column |\meta{number} option to change the alignment
+for different columns.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{column 1}=[anchor=base west]
+ \tikzstyle{column 2}=[anchor=base east]
+ \tikzstyle{column 3}=[anchor=base]
+ \matrix
+ {
+ \node {123}; & \node{456}; & \node {789}; \\
+ \node {12}; & \node{45}; & \node {78}; \\
+ \node {1}; & \node{4}; & \node {7}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+
+In many matrices all cell pictures have nearly the same code. For
+example, cells typically start with |\node{| and end |};|. The
+following options allow you to execute such code in all cells:
+
+\begin{itemize}
+ \itemoption{execute at begin cell}|=|\meta{code}
+ The code will be executed at the beginning of each nonempty cell.
+ \itemoption{execute at end cell}|=|\meta{code}
+ The code will be executed at the end of each nonempty cell.
+ \itemoption{execute at empty cell}|=|\meta{code}
+ The code will be executed inside each empty cell.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{matrix of nodes}=[
+ execute at begin cell=\node\bgroup,
+ execute at end cell=\egroup;%
+ ]
+ \matrix [matrix of nodes]
+ {
+ 8 & 1 & 6 \\
+ 3 & 5 & 7 \\
+ 4 & 9 & 2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{matrix of nodes}=[
+ execute at begin cell=\node\bgroup,
+ execute at end cell=\egroup;,%
+ execute at empty cell=\node{--};%
+ ]
+ \matrix [matrix of nodes]
+ {
+ 8 & 1 & \\
+ 3 & & 7 \\
+ & & 2 \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\end{itemize}
+
+The |matrix| library defines a number of styles that make use of the
+above options.
+
+
+
+
+
+\subsection{Anchoring a Matrix}
+
+Since matrices are nodes, they can be anchored in the usual fashion
+using the |anchor| option. However, there are two ways to influence
+this placement further. First, the following option is often useful:
+
+\begin{itemize}
+ \itemoption{matrix anchor}|=|\meta{anchor}
+ This option has the same effect as |anchor|, but the option applies
+ only to the matrix itself, not to the cells inside. If you just say
+ |anchor=north| as an option to the matrix node, all nodes inside
+ matrix will also have this anchor, unless it is explicitly set
+ differently for each node. By comparison, |matrix anchor| sets the
+ anchor for the matrix, but for the nodes inside the value of
+ |anchor| remain unchanged.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix anchor=west] at (0,0)
+ {
+ \node {123}; \\ % still center anchor
+ \node {12}; \\
+ \node {1}; \\
+ };
+ \matrix [anchor=west] at (0,-2)
+ {
+ \node {123}; \\ % inherited west anchor
+ \node {12}; \\
+ \node {1}; \\
+ };
+\end{tikzpicture}
+\end{codeexample}
+\end{itemize}
+
+The second way to anchor a matrix is to use \emph{an anchor of a node
+ inside the matrix}. For this, the |anchor| option has a special
+effect when given as an argument to a matrix:
+
+\begin{itemize}
+ \itemoption{anchor}|=|\meta{anchor or node.anchor}
+ Normally, the argument of this option refers to anchor of the matrix
+ node, which is the node than includes all of the stuff of the
+ matrix. However, you can also provide an argument of the form
+ \meta{node}|.|\meta{anchor} where \meta{node} must be node defined
+ inside the matrix and \meta{anchor} is an anchor of this node. In
+ this case, the whole matrix is shifted around in such a way that
+ this particular anchor of this particular node lies at the |at|
+ position of the matrix. The same is true for |matrix anchor|.
+\end{itemize}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+ \matrix[matrix anchor=inner node.south,anchor=base,row sep=3mm] at (1,1)
+ {
+ \node {a}; & \node {b}; & \node {c}; & \node {d}; \\
+ \node {a}; & \node(inner node) {b}; & \node {c}; & \node {d}; \\
+ \node {a}; & \node {b}; & \node {c}; & \node {d}; \\
+ };
+ \draw (inner node.south) circle (1pt);
+\end{tikzpicture}
+\end{codeexample}
+
+
+
+\subsection{Considerations Concerning Active Characters}
+
+Even though \tikzname\ seems to use |&| to separate cells, \pgfname\ actually
+uses a different command to separate cells, namely the command
+|\pgfmatrixnextcell| and using a normal |&| character will normally
+fail. What happens is that, \tikzname\ makes |&| an active character
+and then defines this character to be equal to
+|\pgfmatrixnextcell|. In most situations this will work
+nicely, but sometimes |&| cannot be made active; for
+instance because the matrix is used in an argument of some macro or
+the matrix contains nodes that contain normal |{tabular}|
+environments. In this case you can use the following option to avoid
+having to type |\pgfmatrixnextcell| each time:
+
+\begin{itemize}
+ \itemoption{ampersand replacement}|=|\meta{macro name or empty}
+ If a macro name is provided, this macro will be defined to be equal
+ to |\pgfmatrixnextcell| inside matrices and |&| will not be made
+ active. For instance, you could say |ampersand replacement=\&| and
+ then use \& to separate columns as in the following example:
+\begin{codeexample}[]
+\tikz
+ \matrix [ampersand replacement=\&]
+ {
+ \draw (0,0) circle (4mm); \& \node[rotate=10] {Hello}; \\
+ \draw (0.2,0) circle (2mm); \& \fill[red] (0,0) circle (3mm); \\
+ };
+\end{codeexample}
+\end{itemize}
+
+
+\subsection{Examples}
+
+The following examples are adapted from code by Mark Wibrow. The first
+two redraw pictures from Timothy van Zandt's PSTricks documentation:
+
+{\catcode`\|=12
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix [matrix of math nodes,row sep=1cm]
+ {
+ |(U)| U &[2mm] &[8mm] \\
+ & |(XZY)| X \times_Z Y & |(X)| X \\
+ & |(Y)| Y & |(Z)| Z \\
+ };
+ \tikzstyle{every node}=[midway,auto,font=\scriptsize]
+ \draw [double, dashed] (U) -- node {$x$} (X);
+ \draw (X) -- node {$p$} (X -| XZY.east)
+ (X) -- node {$f$} (Z)
+ -- node {$g$} (Y)
+ -- node {$q$} (XZY)
+ -- node {$y$} (U);
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}[>=stealth,->,shorten >=2pt,looseness=.5,auto]
+ \matrix [matrix of math nodes,
+ column sep={2cm,between origins},
+ row sep={3cm,between origins},
+ nodes={circle, draw, minimum size=7.5mm}]
+ {
+ & |(A)| A & \\
+ |(B)| B & |(E)| E & |(C)| C \\
+ & |(D)| D \\
+ };
+ \tikzstyle{every node}=[font=\small\itshape]
+ \draw (A) to [bend left] (B) node [midway] {g};
+ \draw (B) to [bend left] (A) node [midway] {f};
+ \draw (D) -- (B) node [midway] {c};
+ \draw (E) -- (B) node [midway] {b};
+ \draw (E) -- (C) node [near end] {a};
+ \draw [-,line width=8pt,draw=graphicbackground]
+ (D) to [bend right, looseness=1] (A);
+ \draw (D) to [bend right, looseness=1] (A) node [near start] {b} node [near end] {e};
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \matrix (network)
+ [matrix of nodes,%
+ nodes in empty cells,
+ nodes={outer sep=0pt,circle,minimum size=4pt,draw},
+ column sep={1cm,between origins},
+ row sep={1cm,between origins}]
+ {
+ & & & \\
+ & & & \\
+ |[draw=none]| & |[xshift=1mm]| & |[xshift=-1mm]| \\
+ };
+ \foreach \a in {1,...,4}{
+ \draw (network-3-2) -- (network-2-\a);
+ \draw (network-3-3) -- (network-2-\a);
+ \draw [-stealth] ([yshift=5mm]network-1-\a.north) -- (network-1-\a);
+ \foreach \b in {1,...,4}
+ \draw (network-1-\a) -- (network-2-\b);
+ }
+ \draw [stealth-] ([yshift=-5mm]network-3-2.south) -- (network-3-2);
+ \draw [stealth-] ([yshift=-5mm]network-3-3.south) -- (network-3-3);
+\end{tikzpicture}
+\end{codeexample}
+
+The following example is adapted from code written by Kjell Magne
+Fauske, which is based on the following paper: K.~Bossley, M.~Brown,
+and C.~Harris, Neurofuzzy identification of an autonomous underwater
+vehicle, \emph{International Journal of Systems Science}, 1999, 30, 901--913.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[auto]
+ \tikzstyle{decision} = [diamond, draw=blue, thick, fill=blue!20,
+ text width=4.5em, text badly centered, inner sep=1pt]
+ \tikzstyle{block} = [rectangle, draw=blue, thick, fill=blue!20,
+ text width=5em, text centered, rounded corners, minimum height=4em]
+ \tikzstyle{line} = [draw, thick, -latex',shorten >=2pt];
+ \tikzstyle{cloud} = [draw=red, thick, ellipse,fill=red!20, minimum height=2em];
+ \matrix [column sep=5mm,row sep=7mm]
+ {
+ % row 1
+ \node [cloud] (expert) {expert}; &
+ \node [block] (init) {initialize model}; &
+ \node [cloud] (system) {system}; \\
+ % row 2
+ & \node [block] (identify) {identify candidate model}; & \\
+ % row 3
+ \node [block] (update) {update model}; &
+ \node [block] (evaluate) {evaluate candidate models}; & \\
+ % row 4
+ & \node [decision] (decide) {is best candidate}; & \\
+ % row 5
+ & \node [block] (stop) {stop}; & \\
+ };
+ \tikzstyle{every path}=[line]
+ \path (init) -- (identify);
+ \path (identify) -- (evaluate);
+ \path (evaluate) -- (decide);
+ \path (update) |- (identify);
+ \path (decide) -| node [near start] {yes} (update);
+ \path (decide) -- node [midway] {no} (stop);
+ \path [dashed] (expert) -- (init);
+ \path [dashed] (system) -- (init);
+ \path [dashed] (system) |- (evaluate);
+\end{tikzpicture}
+\end{codeexample}
+}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End:
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
index 37c0be02ec6..ea8d3f1bcb9 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
@@ -868,444 +868,11 @@ or cosine curve whose end points are not multiples of $\pi/2$.
The |plot| operation can be used to append a line or curve to the path
that goes through a large number of coordinates. These coordinates are
-either given in a simple list of coordinates or they are read from
-some file.
-
-The syntax of the |plot| comes in different versions.
-
-\begin{pathoperation}{--plot}{\meta{further arguments}}
- This operation plots the curve through the coordinates specified in
- the \meta{further arguments}. The current (sub)path is simply
- continued, that is, a line-to operation to the first point of the
- curve is implicitly added. The details of the \meta{further
- arguments} will be explained in a moment.
-\end{pathoperation}
-
-\begin{pathoperation}{plot}{\meta{further arguments}}
- This operation plots the curve through the coordinates specified in
- the \meta{further arguments} by first ``moving'' to the first
- coordinate of the curve.
-\end{pathoperation}
-
-The \meta{further arguments} are used in three different ways to
-specifying the coordinates of the points to be plotted:
-
-\begin{enumerate}
-\item
- \opt{|--|}|plot|\oarg{local options}\declare{|coordinates{|\meta{coordinate
- 1}\meta{coordinate 2}\dots\meta{coordinate $n$}|}|}
-\item
- \opt{|--|}|plot|\oarg{local options}\declare{|file{|\meta{filename}|}|}
-\item
- \opt{|--|}|plot|\oarg{local options}\declare{|function{|\meta{gnuplot formula}|}|}
-\end{enumerate}
-
-These different ways are explained in the following.
-
-
-\subsubsection{Plotting Points Given Inline}
-
-In the first two cases, the points are given directly in the \TeX-file
-as in the following example:
-
-\begin{codeexample}[]
-\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)};
-\end{codeexample}
-
-Here is an example showing the difference between |plot| and |--plot|:
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- (1,1) plot coordinates {(2,0) (4,0)};
- \draw[color=red,xshift=5cm]
- (0,0) -- (1,1) -- plot coordinates {(2,0) (4,0)};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Plotting Points Read From an External File}
-
-The second way of specifying points is to put them in an external
-file named \meta{filename}. Currently, the only file format that
-\tikzname\ allows is the following: Each line of the \meta{filename}
-should contain one line starting with two numbers, separated by a
-space. Anything following the two numbers on the line is
-ignored. Also, lines starting with a |%| or a |#| are ignored as well
-as empty lines. (This is exactly the format that \textsc{gnuplot}
-produces when you say |set terminal table|.) If necessary, more
-formats will be supported in the future, but it is usually easy to
-produce a file containing data in this form.
-
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table};
-\end{codeexample}
-
-The file |plots/pgfmanual-sine.table| reads:
-\begin{codeexample}[code only]
-#Curve 0, 20 points
-#x y type
-0.00000 0.00000 i
-0.52632 0.50235 i
-1.05263 0.86873 i
-1.57895 0.99997 i
-...
-9.47368 -0.04889 i
-10.00000 -0.54402 i
-\end{codeexample}
-It was produced from the following source, using |gnuplot|:
-\begin{codeexample}[code only]
-set terminal table
-set output "../plots/pgfmanual-sine.table"
-set format "%.5f"
-set samples 20
-plot [x=0:10] sin(x)
-\end{codeexample}
-
-The \meta{local options} of the |plot| operation are local to each
-plot and do not affect other plots ``on the same path.'' For example,
-|plot[yshift=1cm]| will locally shift the plot 1cm upward. Remember,
-however, that most options can only be applied to paths as a
-whole. For example, |plot[red]| does not have the effect of making the
-plot red. After all, you are trying to ``locally'' make part of the
-path red, which is not possible.
-
-\subsubsection{Plotting a Function}
-\label{section-tikz-gnuplot}
-
-Often, you will want to plot points that are given via a function like
-$f(x) = x \sin x$. Unfortunately, \TeX\ does not really have enough
-computational power to generate the points on such a function
-efficiently (it is a text processing program, after all). However,
-if you allow it, \TeX\ can try to call external programs that can
-easily produce the necessary points. Currently, \tikzname\ knows how to
-call \textsc{gnuplot}.
-
-When \tikzname\ encounters your operation
-|plot[id=|\meta{id}|] function{x*sin(x)}| for
-the first time, it will create a file called
-\meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is |\jobname.| by
-default, that is, the name of you main |.tex| file. If no \meta{id} is
-given, it will be empty, which is alright, but it is better when each
-plot has a unique \meta{id} for reasons explained in a moment. Next,
-\tikzname\ writes some initialization code into this file followed by
-|plot x*sin(x)|. The initialization code sets up things
-such that the |plot| operation will write the coordinates into another
-file called \meta{prefix}\meta{id}|.table|. Finally, this table file
-is read as if you had said |plot file{|\meta{prefix}\meta{id}|.table}|.
-
-For the plotting mechanism to work, two conditions must be met:
-\begin{enumerate}
-\item
- You must have allowed \TeX\ to call external programs. This is often
- switched off by default since this is a security risk (you might,
- without knowing, run a \TeX\ file that calls all sorts of ``bad''
- commands). To enable this ``calling external programs'' a command
- line option must be given to the \TeX\ program. Usually, it is
- called something like |shell-escape| or |enable-write18|. For
- example, for my |pdflatex| the option |--shell-escape| can be
- given.
-\item
- You must have installed the |gnuplot| program and \TeX\ must find it
- when compiling your file.
-\end{enumerate}
-
-Unfortunately, these conditions will not always be met. Especially if
-you pass some source to a coauthor and the coauthor does not have
-\textsc{gnuplot} installed, he or she will have trouble compiling your
-files.
-
-For this reason, \tikzname\ behaves differently when you compile your
-graphic for the second time: If upon reaching
-|plot[id=|\meta{id}|] function{...}| the file \meta{prefix}\meta{id}|.table|
-already exists \emph{and} if the \meta{prefix}\meta{id}|.gnuplot| file
-contains what \tikzname\ thinks that it ``should'' contain, the |.table|
-file is immediately read without trying to call a |gnuplot|
-program. This approach has the following advantages:
-\begin{enumerate}
-\item
- If you pass a bundle of your |.tex| file and all |.gnuplot| and
- |.table| files to someone else, that person can \TeX\ the |.tex|
- file without having to have |gnuplot| installed.
-\item
- If the |\write18| feature is switched off for security reasons (a
- good idea), then, upon the first compilation of the |.tex| file, the
- |.gnuplot| will still be generated, but not the |.table|
- file. You can then simply call |gnuplot| ``by hand'' for each
- |.gnuplot| file, which will produce all necessary |.table| files.
-\item
- If you change the function that you wish to plot or its
- domain, \tikzname\ will automatically try to regenerate the |.table|
- file.
-\item
- If, out of laziness, you do not provide an |id|, the same |.gnuplot|
- will be used for different plots, but this is not a problem since
- the |.table| will automatically be regenerated for each plot
- on-the-fly. \emph{Note: If you intend to share your files with
- someone else, always use an id, so that the file can by typeset
- without having \textsc{gnuplot} installed.} Also, having unique ids
- for each plot will improve compilation speed since no external
- programs need to be called, unless it is really necessary.
-\end{enumerate}
-
-When you use |plot function{|\meta{gnuplot formula}|}|, the \meta{gnuplot
- formula} must be given in the |gnuplot| syntax, whose details are
-beyond the scope of this manual. Here is the ultra-condensed
-essence: Use |x| as the variable and use the C-syntax for normal
-plots, use |t| as the variable for parametric plots. Here are some examples:
-
-\begin{codeexample}[]
-\begin{tikzpicture}[domain=0:4]
- \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
-
- \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
- \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
-
- \draw[color=red] plot[id=x] function{x} node[right] {$f(x) =x$};
- \draw[color=blue] plot[id=sin] function{sin(x)} node[right] {$f(x) = \sin x$};
- \draw[color=orange] plot[id=exp] function{0.05*exp(x)} node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
-\end{tikzpicture}
-\end{codeexample}
-
-
-The following options influence the plot:
-
-\begin{itemize}
- \itemoption{samples}|=|\meta{number}
- sets the number of samples used in the plot. The default is 25.
- \itemoption{domain}|=|\meta{start}|:|\meta{end}
- sets the domain between which the samples are taken. The default is
- |-5:5|.
- \itemoption{parametric}\opt{|=|\meta{true or false}}
- sets whether the plot is a parametric plot. If true, then |t| must
- be used instead of |x| as the parameter and two comma-separated
- functions must be given in the \meta{gnuplot formula}. An example is
- the following:
-\begin{codeexample}[]
-\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth]
- plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)};
-\end{codeexample}
-
- \itemoption{id}|=|\meta{id}
- sets the identifier of the current plot. This should be a unique
- identifier for each plot (though things will also work if it is not,
- but not as well, see the explanations above). The \meta{id} will be
- part of a filename, so it should not contain anything fancy like |*|
- or |$|.%$
- \itemoption{prefix}|=|\meta{prefix}
- is put before each plot file name. The default is |\jobname.|, but
- if you have many plots, it might be better to use, say |plots/| and
- have all plots placed in a directory. You have to create the
- directory yourself.
- \itemoption{raw gnuplot}
- causes the \meta{gnuplot formula} to be passed on to
- \textsc{gnuplot} without setting up the samples or the |plot|
- operation. Thus, you could write
-\begin{codeexample}[code only]
-plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)}
-\end{codeexample}
- This can be
- useful for complicated things that need to be passed to
- \textsc{gnuplot}. However, for really complicated situations you
- should create a special external generating \textsc{gnuplot} file
- and use the |file|-syntax to include the table ``by hand.''
-\end{itemize}
-
-The following styles influence the plot:
-\begin{itemize}
- \itemstyle{every plot}
- This style is installed in each plot, that is, as if you always said
-\begin{codeexample}[code only]
- plot[style=every plot,...]
-\end{codeexample}
- This is most useful for globally setting a prefix for all plots by saying:
-\begin{codeexample}[code only]
-\tikzstyle{every plot}=[prefix=plots/]
-\end{codeexample}
-\end{itemize}
-
-
-
-\subsubsection{Placing Marks on the Plot}
-
-As we saw already, it is possible to add \emph{marks} to a plot using
-the |mark| option. When this option is used, a copy of the plot
-mark is placed on each point of the plot. Note that the marks are
-placed \emph{after} the whole path has been drawn/filled/shaded. In
-this respect, they are handled like text nodes.
-
-In detail, the following options govern how marks are drawn:
-\begin{itemize}
- \itemoption{mark}|=|\meta{mark mnemonic}
- Sets the mark to a mnemonic that has previously been defined using
- the |\pgfdeclareplotmark|. By default, |*|, |+|, and |x| are available,
- which draw a filled circle, a plus, and a cross as marks. Many more
- marks become available when the library |pgflibraryplotmarks| is
- loaded. Section~\ref{section-plot-marks} lists the available plot
- marks.
-
- One plot mark is special: the |ball| plot mark is available only
- it \tikzname. The |ball color| determines the balls's color. Do not use
- this option with a large number of marks since it will take very long
- to render in PostScript.
-
- \begin{tabular}{lc}
- Option & Effect \\\hline \vrule height14pt width0pt
- \plotmarkentrytikz{ball}
- \end{tabular}
-
- \itemoption{mark repeat}|=|\meta{r}
- This option tells \tikzname\ that only every $r$th mark should be
- drawn.
-
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table};
-\end{codeexample}
-
- \itemoption{mark phase}|=|\meta{p}
- This option tells \tikzname\ that the first mark to be draw should
- be the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so
- on.
-
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table};
-\end{codeexample}
-
- \itemoption{mark indices}|=|\meta{list}
- This option allows you to specify explicitly the indices at which a
- mark should be placed. Counting starts with 1. You can use the
- |\foreach| syntax, that is, |...| can be used.
-
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth]
- file {plots/pgfmanual-sine.table};
-\end{codeexample}
-
- \itemoption{mark size}|=|\meta{dimension}
- Sets the size of the plot marks. For circular plot marks,
- \meta{dimension} is the radius, for other plot marks
- \meta{dimension} should be about half the width and height.
-
- This option is not really necessary, since you achieve the same
- effect by specifying |scale=|\meta{factor} as a local option, where
- \meta{factor} is the quotient of the desired size and the default
- size. However, using |mark size| is a bit faster and more natural.
-
- \itemoption{mark options}|=|\meta{options}
- These options are applied to marks when they are drawn. For example,
- you can scale (or otherwise transform) the plot mark or set its
- color.
-\begin{codeexample}[]
-\tikz \fill[fill=blue!20]
- plot[mark=triangle*,mark options={color=blue,rotate=180}]
- file{plots/pgfmanual-sine.table} |- (0,0);
-\end{codeexample}
-\end{itemize}
-
-
-
-\subsubsection{Smooth Plots, Sharp Plots, and Comb Plots}
-
-There are different things the |plot| operation can do with the points
-it reads from a file or from the inlined list of points. By default,
-it will connect these points by straight lines. However, you can also
-use options to change the behavior of |plot|.
-
-\begin{itemize}
- \itemoption{sharp plot}
- This is the default and causes the points to be connected by
- straight lines. This option is included only so that you can
- ``switch back'' if you ``globally'' install, say, |smooth|.
-
- \itemoption{smooth}
- This option causes the points on the path to be connected using a
- smooth curve:
-
-\begin{codeexample}[]
-\tikz\draw plot[smooth] file{plots/pgfmanual-sine.table};
-\end{codeexample}
-
- Note that the smoothing algorithm is not very intelligent. You will
- get the best results if the bending angles are small, that is, less
- than about $30^\circ$ and, even more importantly, if the distances
- between points are about the same all over the plotting path.
-
- \itemoption{tension}|=|\meta{value}
- This option influences how ``tight'' the smoothing is. A lower value
- will result in sharper corners, a higher value in more ``round''
- curves. A value of $1$ results in a circle if four points at
- quarter-positions on a circle are given. The default is $0.55$. The
- ``correct'' value depends on the details of plot.
-
-\begin{codeexample}[]
-\begin{tikzpicture}[smooth cycle]
- \draw plot[tension=0.2]
- coordinates{(0,0) (1,1) (2,0) (1,-1)};
- \draw[yshift=-2.25cm] plot[tension=0.5]
- coordinates{(0,0) (1,1) (2,0) (1,-1)};
- \draw[yshift=-4.5cm] plot[tension=1]
- coordinates{(0,0) (1,1) (2,0) (1,-1)};
-\end{tikzpicture}
-\end{codeexample}
-
- \itemoption{smooth cycle}
- This option causes the points on the path to be connected using a
- closed smooth curve.
-
-\begin{codeexample}[]
-\tikz[scale=0.5]
- \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)}
- plot coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle;
-\end{codeexample}
-
- \itemoption{ycomb}
- This option causes the |plot| operation to interpret the plotting
- points differently. Instead of connecting them, for each point of
- the plot a straight line is added to the path from the $x$-axis to the point,
- resulting in a sort of ``comb'' or ``bar diagram.''
-
-\begin{codeexample}[]
-\tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[ycomb]
- \draw[color=red,line width=6pt]
- plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
- \draw[color=red!50,line width=4pt,xshift=3pt]
- plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
-\end{tikzpicture}
-\end{codeexample}
-
- \itemoption{xcomb}
- This option works like |ycomb| except that the bars are horizontal.
-
-\begin{codeexample}[]
-\tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)};
-\end{codeexample}
-
- \itemoption{polar comb}
- This option causes a line from the origin to the point to be added
- to the path for each plot point.
-
-\begin{codeexample}[]
-\tikz \draw plot[polar comb,
- mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt]
- coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)};
-\end{codeexample}
-
-
- \itemoption{only marks}
- This option causes only marks to be shown; no path segments are
- added to the actual path. This can be useful for quickly adding some
- marks to a path.
-
-\begin{codeexample}[]
-\tikz \draw (0,0) sin (1,1) cos (2,0)
- plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)};
-\end{codeexample}
-\end{itemize}
-
+either given in a simple list of coordinates, read from some file, or
+they are computed on the fly.
+Since the syntax and the behaviour of this command are a bit complex,
+they are described in the separated Section~\ref{section-tikz-plots}.
\subsection{The To Path Operation}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex
new file mode 100644
index 00000000000..043ba4c5312
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex
@@ -0,0 +1,577 @@
+% Copyright 2007 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{Plots of Functions}
+
+\label{section-tikz-plots}
+
+\subsection{When Should One Use \tikzname\ for Generating Plots? }
+
+\label{section-why-pgname-for-plots}
+
+There exist many powerful programs that produce plots, examples are
+\textsc{gnuplot} or \textsc{mathematica}. These programs can produce
+two different kinds of output: First, they can output a complete plot
+picture in a certain format (like \pdf) that includes all low-level
+commands necessary for drawing the complete plot (including axes and
+labels). Second, they can usually also produce ``just plain data'' in
+the form of a long list of coordinates. Most of the powerful programs
+consider it a to be ``a bit boring'' to just output tabled data and
+very much prefer to produce fancy pictures. Nevertheless, when coaxed,
+they can also provide the plain data.
+
+\emph{Note that is often not necessary to use \tikzname\ for plots.}
+Programs like \textsc{gnuplot} can produce very sophisticated plots
+and it is usually much easier to simply include these plots as a
+finished \textsc{pdf} or PostScript graphics.
+
+However, there are a number of reasons why you may wish to invest time
+and energy into mastering the \pgfname\ commands for creating plots:
+
+\begin{itemize}
+\item
+ Virtually all plots produced by ``external programs'' use different
+ fonts from the one used in your document.
+\item
+ Even worse, formulas will look totally different, if they can be
+ rendered at all.
+\item
+ Line width will usually be too large or too small.
+\item
+ Scaling effects upon inclusion can create a mismatch between sizes
+ in the plot and sizes in the text.
+\item
+ The automatic grid generated by most programs is mostly
+ distracting.
+\item
+ The automatic ticks generated by most programs are cryptic
+ numerics. (Try adding a tick reading ``$\pi$'' at the right point.)
+\item
+ Most programs make it very easy to create ``chart junk'' in a most
+ convenient fashion. All show, no content.
+\item
+ Arrows and plot marks will almost never match the arrows used in the
+ rest of the document.
+\end{itemize}
+
+The above list is not exhaustive, unfortunately.
+
+
+\subsection{The Plot Path Operation}
+
+The |plot| path operation can be used to append a line or curve to the path
+that goes through a large number of coordinates. These coordinates are
+either given in a simple list of coordinates, read from some file, or
+they are computed on the fly.
+
+The syntax of the |plot| comes in different versions.
+
+\begin{pathoperation}{--plot}{\meta{further arguments}}
+ This operation plots the curve through the coordinates specified in
+ the \meta{further arguments}. The current (sub)path is simply
+ continued, that is, a line-to operation to the first point of the
+ curve is implicitly added. The details of the \meta{further
+ arguments} will be explained in a moment.
+\end{pathoperation}
+
+\begin{pathoperation}{plot}{\meta{further arguments}}
+ This operation plots the curve through the coordinates specified in
+ the \meta{further arguments} by first ``moving'' to the first
+ coordinate of the curve.
+\end{pathoperation}
+
+The \meta{further arguments} are used in three different ways to
+specifying the coordinates of the points to be plotted:
+
+\begin{enumerate}
+\item
+ \opt{|--|}|plot|\oarg{local options}\declare{|coordinates{|\meta{coordinate
+ 1}\meta{coordinate 2}\dots\meta{coordinate $n$}|}|}
+\item
+ \opt{|--|}|plot|\oarg{local options}\declare{|file{|\meta{filename}|}|}
+\item
+ \opt{|--|}|plot|\oarg{local options}\declare{\meta{coordinate expression}}
+\item
+ \opt{|--|}|plot|\oarg{local options}\declare{|function{|\meta{gnuplot formula}|}|}
+\end{enumerate}
+
+These different ways are explained in the following.
+
+
+\subsection{Plotting Points Given Inline}
+
+In the first two cases, the points are given directly in the \TeX-file
+as in the following example:
+
+\begin{codeexample}[]
+\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)};
+\end{codeexample}
+
+Here is an example showing the difference between |plot| and |--plot|:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) -- (1,1) plot coordinates {(2,0) (4,0)};
+ \draw[color=red,xshift=5cm]
+ (0,0) -- (1,1) -- plot coordinates {(2,0) (4,0)};
+\end{tikzpicture}
+\end{codeexample}
+
+
+\subsection{Plotting Points Read From an External File}
+
+The second way of specifying points is to put them in an external
+file named \meta{filename}. Currently, the only file format that
+\tikzname\ allows is the following: Each line of the \meta{filename}
+should contain one line starting with two numbers, separated by a
+space. Anything following the two numbers on the line is
+ignored. Also, lines starting with a |%| or a |#| are ignored as well
+as empty lines. (This is exactly the format that \textsc{gnuplot}
+produces when you say |set terminal table|.) If necessary, more
+formats will be supported in the future, but it is usually easy to
+produce a file containing data in this form.
+
+\begin{codeexample}[]
+\tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table};
+\end{codeexample}
+
+The file |plots/pgfmanual-sine.table| reads:
+\begin{codeexample}[code only]
+#Curve 0, 20 points
+#x y type
+0.00000 0.00000 i
+0.52632 0.50235 i
+1.05263 0.86873 i
+1.57895 0.99997 i
+...
+9.47368 -0.04889 i
+10.00000 -0.54402 i
+\end{codeexample}
+It was produced from the following source, using |gnuplot|:
+\begin{codeexample}[code only]
+set terminal table
+set output "../plots/pgfmanual-sine.table"
+set format "%.5f"
+set samples 20
+plot [x=0:10] sin(x)
+\end{codeexample}
+
+The \meta{local options} of the |plot| operation are local to each
+plot and do not affect other plots ``on the same path.'' For example,
+|plot[yshift=1cm]| will locally shift the plot 1cm upward. Remember,
+however, that most options can only be applied to paths as a
+whole. For example, |plot[red]| does not have the effect of making the
+plot red. After all, you are trying to ``locally'' make part of the
+path red, which is not possible.
+
+\subsection{Plotting a Function}
+\label{section-tikz-plot}
+
+When you plot a function, the coordinates of the plot data can be
+computed by evaluating a mathematical expression. Since \pgfname\
+comes with a mathematical engine, you can specify this expression and
+then have \tikzname\ produce the desired coordinates for you,
+automatically.
+
+Since this case is quite common when plotting a function, the syntax
+is easy: Following the |plot| command and its local options, you
+directly provide a \meta{coordinate expression}. It looks like a
+normal coordinate, but inside you may use a special macro, which is
+|\x| by default, but this can be changed using the |variable|
+option. The \meta{coordinate expression} is then evaluated for
+different values for |\x| and the resulting coordinates are plotted.
+
+Note that you will often have to put the $x$- or $y$-coordinate inside
+braces, namely whenever you use an expression involving a paranthesis.
+
+The following options influence how the \meta{coordinate expression}
+is evaluated:
+\begin{itemize}
+ \itemoption{variable}|=|\meta{macro}
+ sets the macro whose value is set to the different values when
+ \meta{coordinate expression} is evaluated.
+ \itemoption{samples}|=|\meta{number}
+ sets the number of samples used in the plot. The default is 25.
+ \itemoption{domain}|=|\meta{start}|:|\meta{end}
+ sets the domain between which the samples are taken. The default is
+ |-5:5|.
+ \itemoption{samples at}|=|\meta{sample list}
+ This option specifies a list of positions for which the
+ variable should be evaluated. For instance, you can say
+ |samples at={1,2,8,9,10}| to have the variable evaluated exactly for
+ values $1$, $2$, $8$, $9$, and $10$. You can use the |\foreach|
+ syntax, so you can use |...| inside the \meta{sample list}.
+
+ When this option is used, the |samples| and |domain| option are
+ overruled. The other ways round, setting either |samples| or
+ |domain| will overrule this option.
+\end{itemize}
+
+\begin{codeexample}[]
+\begin{tikzpicture}[domain=0:4]
+ \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
+
+ \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
+ \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
+
+ \draw[color=red] plot (\x,\x) node[right] {$f(x) =x$};
+ \draw[color=blue] plot (\x,{sin(\x r)}) node[right] {$f(x) = \sin x$};
+ \draw[color=orange] plot (\x,{0.05*exp(\x)}) node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,variable=\t]
+ plot ({\t*sin(\t r)},{\t*cos(\t r)});
+\end{codeexample}
+
+\begin{codeexample}[]
+\tikz \draw[domain=0:360,smooth,variable=\t]
+ plot ({sin(\t)},\t/360,{cos(\t)});
+\end{codeexample}
+
+
+\subsection{Plotting a Function Using Gnuplot}
+\label{section-tikz-gnuplot}
+
+Often, you will want to plot points that are given via a function like
+$f(x) = x \sin x$. Unfortunately, \TeX\ does not really have enough
+computational power to generate the points on such a function
+efficiently (it is a text processing program, after all). However,
+if you allow it, \TeX\ can try to call external programs that can
+easily produce the necessary points. Currently, \tikzname\ knows how to
+call \textsc{gnuplot}.
+
+When \tikzname\ encounters your operation
+|plot[id=|\meta{id}|] function{x*sin(x)}| for
+the first time, it will create a file called
+\meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is |\jobname.| by
+default, that is, the name of you main |.tex| file. If no \meta{id} is
+given, it will be empty, which is alright, but it is better when each
+plot has a unique \meta{id} for reasons explained in a moment. Next,
+\tikzname\ writes some initialization code into this file followed by
+|plot x*sin(x)|. The initialization code sets up things
+such that the |plot| operation will write the coordinates into another
+file called \meta{prefix}\meta{id}|.table|. Finally, this table file
+is read as if you had said |plot file{|\meta{prefix}\meta{id}|.table}|.
+
+For the plotting mechanism to work, two conditions must be met:
+\begin{enumerate}
+\item
+ You must have allowed \TeX\ to call external programs. This is often
+ switched off by default since this is a security risk (you might,
+ without knowing, run a \TeX\ file that calls all sorts of ``bad''
+ commands). To enable this ``calling external programs'' a command
+ line option must be given to the \TeX\ program. Usually, it is
+ called something like |shell-escape| or |enable-write18|. For
+ example, for my |pdflatex| the option |--shell-escape| can be
+ given.
+\item
+ You must have installed the |gnuplot| program and \TeX\ must find it
+ when compiling your file.
+\end{enumerate}
+
+Unfortunately, these conditions will not always be met. Especially if
+you pass some source to a coauthor and the coauthor does not have
+\textsc{gnuplot} installed, he or she will have trouble compiling your
+files.
+
+For this reason, \tikzname\ behaves differently when you compile your
+graphic for the second time: If upon reaching
+|plot[id=|\meta{id}|] function{...}| the file \meta{prefix}\meta{id}|.table|
+already exists \emph{and} if the \meta{prefix}\meta{id}|.gnuplot| file
+contains what \tikzname\ thinks that it ``should'' contain, the |.table|
+file is immediately read without trying to call a |gnuplot|
+program. This approach has the following advantages:
+\begin{enumerate}
+\item
+ If you pass a bundle of your |.tex| file and all |.gnuplot| and
+ |.table| files to someone else, that person can \TeX\ the |.tex|
+ file without having to have |gnuplot| installed.
+\item
+ If the |\write18| feature is switched off for security reasons (a
+ good idea), then, upon the first compilation of the |.tex| file, the
+ |.gnuplot| will still be generated, but not the |.table|
+ file. You can then simply call |gnuplot| ``by hand'' for each
+ |.gnuplot| file, which will produce all necessary |.table| files.
+\item
+ If you change the function that you wish to plot or its
+ domain, \tikzname\ will automatically try to regenerate the |.table|
+ file.
+\item
+ If, out of laziness, you do not provide an |id|, the same |.gnuplot|
+ will be used for different plots, but this is not a problem since
+ the |.table| will automatically be regenerated for each plot
+ on-the-fly. \emph{Note: If you intend to share your files with
+ someone else, always use an id, so that the file can by typeset
+ without having \textsc{gnuplot} installed.} Also, having unique ids
+ for each plot will improve compilation speed since no external
+ programs need to be called, unless it is really necessary.
+\end{enumerate}
+
+When you use |plot function{|\meta{gnuplot formula}|}|, the \meta{gnuplot
+ formula} must be given in the |gnuplot| syntax, whose details are
+beyond the scope of this manual. Here is the ultra-condensed
+essence: Use |x| as the variable and use the C-syntax for normal
+plots, use |t| as the variable for parametric plots. Here are some examples:
+
+\begin{codeexample}[]
+\begin{tikzpicture}[domain=0:4]
+ \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
+
+ \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
+ \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
+
+ \draw[color=red] plot[id=x] function{x} node[right] {$f(x) =x$};
+ \draw[color=blue] plot[id=sin] function{sin(x)} node[right] {$f(x) = \sin x$};
+ \draw[color=orange] plot[id=exp] function{0.05*exp(x)} node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
+\end{tikzpicture}
+\end{codeexample}
+
+
+The following options influence the plot:
+
+\begin{itemize}
+ \itemoption{samples}|=|\meta{number}
+ sets the number of samples used in the plot. The default is 25.
+ \itemoption{domain}|=|\meta{start}|:|\meta{end}
+ sets the domain between which the samples are taken. The default is
+ |-5:5|.
+ \itemoption{parametric}\opt{|=|\meta{true or false}}
+ sets whether the plot is a parametric plot. If true, then |t| must
+ be used instead of |x| as the parameter and two comma-separated
+ functions must be given in the \meta{gnuplot formula}. An example is
+ the following:
+\begin{codeexample}[]
+\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth]
+ plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)};
+\end{codeexample}
+
+ \itemoption{id}|=|\meta{id}
+ sets the identifier of the current plot. This should be a unique
+ identifier for each plot (though things will also work if it is not,
+ but not as well, see the explanations above). The \meta{id} will be
+ part of a filename, so it should not contain anything fancy like |*|
+ or |$|.%$
+ \itemoption{prefix}|=|\meta{prefix}
+ is put before each plot file name. The default is |\jobname.|, but
+ if you have many plots, it might be better to use, say |plots/| and
+ have all plots placed in a directory. You have to create the
+ directory yourself.
+ \itemoption{raw gnuplot}
+ causes the \meta{gnuplot formula} to be passed on to
+ \textsc{gnuplot} without setting up the samples or the |plot|
+ operation. Thus, you could write
+\begin{codeexample}[code only]
+plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)}
+\end{codeexample}
+ This can be
+ useful for complicated things that need to be passed to
+ \textsc{gnuplot}. However, for really complicated situations you
+ should create a special external generating \textsc{gnuplot} file
+ and use the |file|-syntax to include the table ``by hand.''
+\end{itemize}
+
+The following styles influence the plot:
+\begin{itemize}
+ \itemstyle{every plot}
+ This style is installed in each plot, that is, as if you always said
+\begin{codeexample}[code only]
+ plot[style=every plot,...]
+\end{codeexample}
+ This is most useful for globally setting a prefix for all plots by saying:
+\begin{codeexample}[code only]
+\tikzstyle{every plot}=[prefix=plots/]
+\end{codeexample}
+\end{itemize}
+
+
+
+\subsection{Placing Marks on the Plot}
+
+As we saw already, it is possible to add \emph{marks} to a plot using
+the |mark| option. When this option is used, a copy of the plot
+mark is placed on each point of the plot. Note that the marks are
+placed \emph{after} the whole path has been drawn/filled/shaded. In
+this respect, they are handled like text nodes.
+
+In detail, the following options govern how marks are drawn:
+\begin{itemize}
+ \itemoption{mark}|=|\meta{mark mnemonic}
+ Sets the mark to a mnemonic that has previously been defined using
+ the |\pgfdeclareplotmark|. By default, |*|, |+|, and |x| are available,
+ which draw a filled circle, a plus, and a cross as marks. Many more
+ marks become available when the library |pgflibraryplotmarks| is
+ loaded. Section~\ref{section-plot-marks} lists the available plot
+ marks.
+
+ One plot mark is special: the |ball| plot mark is available only
+ it \tikzname. The |ball color| determines the balls's color. Do not use
+ this option with a large number of marks since it will take very long
+ to render in PostScript.
+
+ \begin{tabular}{lc}
+ Option & Effect \\\hline \vrule height14pt width0pt
+ \plotmarkentrytikz{ball}
+ \end{tabular}
+
+ \itemoption{mark repeat}|=|\meta{r}
+ This option tells \tikzname\ that only every $r$th mark should be
+ drawn.
+
+\begin{codeexample}[]
+\tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table};
+\end{codeexample}
+
+ \itemoption{mark phase}|=|\meta{p}
+ This option tells \tikzname\ that the first mark to be draw should
+ be the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so
+ on.
+
+\begin{codeexample}[]
+\tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table};
+\end{codeexample}
+
+ \itemoption{mark indices}|=|\meta{list}
+ This option allows you to specify explicitly the indices at which a
+ mark should be placed. Counting starts with 1. You can use the
+ |\foreach| syntax, that is, |...| can be used.
+
+\begin{codeexample}[]
+\tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth]
+ file {plots/pgfmanual-sine.table};
+\end{codeexample}
+
+ \itemoption{mark size}|=|\meta{dimension}
+ Sets the size of the plot marks. For circular plot marks,
+ \meta{dimension} is the radius, for other plot marks
+ \meta{dimension} should be about half the width and height.
+
+ This option is not really necessary, since you achieve the same
+ effect by specifying |scale=|\meta{factor} as a local option, where
+ \meta{factor} is the quotient of the desired size and the default
+ size. However, using |mark size| is a bit faster and more natural.
+
+ \itemoption{mark options}|=|\meta{options}
+ These options are applied to marks when they are drawn. For example,
+ you can scale (or otherwise transform) the plot mark or set its
+ color.
+\begin{codeexample}[]
+\tikz \fill[fill=blue!20]
+ plot[mark=triangle*,mark options={color=blue,rotate=180}]
+ file{plots/pgfmanual-sine.table} |- (0,0);
+\end{codeexample}
+\end{itemize}
+
+
+
+\subsection{Smooth Plots, Sharp Plots, and Comb Plots}
+
+There are different things the |plot| operation can do with the points
+it reads from a file or from the inlined list of points. By default,
+it will connect these points by straight lines. However, you can also
+use options to change the behavior of |plot|.
+
+\begin{itemize}
+ \itemoption{sharp plot}
+ This is the default and causes the points to be connected by
+ straight lines. This option is included only so that you can
+ ``switch back'' if you ``globally'' install, say, |smooth|.
+
+ \itemoption{smooth}
+ This option causes the points on the path to be connected using a
+ smooth curve:
+
+\begin{codeexample}[]
+\tikz\draw plot[smooth] file{plots/pgfmanual-sine.table};
+\end{codeexample}
+
+ Note that the smoothing algorithm is not very intelligent. You will
+ get the best results if the bending angles are small, that is, less
+ than about $30^\circ$ and, even more importantly, if the distances
+ between points are about the same all over the plotting path.
+
+ \itemoption{tension}|=|\meta{value}
+ This option influences how ``tight'' the smoothing is. A lower value
+ will result in sharper corners, a higher value in more ``round''
+ curves. A value of $1$ results in a circle if four points at
+ quarter-positions on a circle are given. The default is $0.55$. The
+ ``correct'' value depends on the details of plot.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[smooth cycle]
+ \draw plot[tension=0.2]
+ coordinates{(0,0) (1,1) (2,0) (1,-1)};
+ \draw[yshift=-2.25cm] plot[tension=0.5]
+ coordinates{(0,0) (1,1) (2,0) (1,-1)};
+ \draw[yshift=-4.5cm] plot[tension=1]
+ coordinates{(0,0) (1,1) (2,0) (1,-1)};
+\end{tikzpicture}
+\end{codeexample}
+
+ \itemoption{smooth cycle}
+ This option causes the points on the path to be connected using a
+ closed smooth curve.
+
+\begin{codeexample}[]
+\tikz[scale=0.5]
+ \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)}
+ plot coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle;
+\end{codeexample}
+
+ \itemoption{ycomb}
+ This option causes the |plot| operation to interpret the plotting
+ points differently. Instead of connecting them, for each point of
+ the plot a straight line is added to the path from the $x$-axis to the point,
+ resulting in a sort of ``comb'' or ``bar diagram.''
+
+\begin{codeexample}[]
+\tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table};
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}[ycomb]
+ \draw[color=red,line width=6pt]
+ plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
+ \draw[color=red!50,line width=4pt,xshift=3pt]
+ plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
+\end{tikzpicture}
+\end{codeexample}
+
+ \itemoption{xcomb}
+ This option works like |ycomb| except that the bars are horizontal.
+
+\begin{codeexample}[]
+\tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)};
+\end{codeexample}
+
+ \itemoption{polar comb}
+ This option causes a line from the origin to the point to be added
+ to the path for each plot point.
+
+\begin{codeexample}[]
+\tikz \draw plot[polar comb,
+ mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt]
+ coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)};
+\end{codeexample}
+
+
+ \itemoption{only marks}
+ This option causes only marks to be shown; no path segments are
+ added to the actual path. This can be useful for quickly adding some
+ marks to a path.
+
+\begin{codeexample}[]
+\tikz \draw (0,0) sin (1,1) cos (2,0)
+ plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)};
+\end{codeexample}
+\end{itemize}
+
+
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex
index 6fa844a8875..91b85c34a8f 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex
@@ -187,7 +187,7 @@ The syntax for specifying nodes is the following:
\end{itemize}
\end{pathoperation}
-The is a special syntax for specifying ``light-weighed'' nodes:
+There is a special syntax for specifying ``light-weighed'' nodes:
\begin{pathoperation}{coordinate}{\opt{|[|\meta{options}|]|}|(|\meta{name}|)|\opt{|at(|\meta{coordinate}|)|}}
This has the same effect as
@@ -197,6 +197,17 @@ The is a special syntax for specifying ``light-weighed'' nodes:
where the |at| part might be missing.
\end{pathoperation}
+Since nodes are often the only path operation on paths, there are two
+special commands for creating paths containing only a node:
+
+\begin{command}{\node}
+ Inside |{tikzpicture}| this is an abbreviation for |\path node|.
+\end{command}
+
+\begin{command}{\coordinate}
+ Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|.
+\end{command}
+
\subsection{Multi-Part Nodes}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex
index 82a99bbd4b1..0ff34448609 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex
@@ -225,6 +225,26 @@ singular (if you do not know what singular matrices are, you are blessed).
\end{tikzpicture}
\end{codeexample}
+ \itemoption{shift only}
+ This option does not take any parameter. Its effect is to cancel all
+ current transformations except for the shifting. This means that the
+ origin will remain where it is, but any rotation around the origin
+ or scaling relative to the origin or skewing will no longer have an
+ effect.
+
+ This option is useful in situtations where a complicated
+ transformation is used to ``get to a position,'' but you then wish
+ to draw something ``normal'' at this position.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[style=help lines] (0,0) grid (3,2);
+ \draw (0,0) -- (1,1) -- (1,0);
+ \draw[rotate=30,xshift=2cm,blue] (0,0) -- (1,1) -- (1,0);
+ \draw[rotate=30,xshift=2cm,shift only,red] (0,0) -- (1,1) -- (1,0);
+\end{tikzpicture}
+\end{codeexample}
+
\itemoption{xshift}|=|\meta{dimension}
adds \meta{dimension} to the $x$ value of all coordinates.
\begin{codeexample}[]
@@ -334,7 +354,8 @@ singular (if you do not know what singular matrices are, you are blessed).
completely resets the coordinate transformation matrix to the
identity matrix. This will destroy not only the transformations
applied in the current scope, but also all transformations inherited
- from surrounding scopes. Do not use this option.
+ from surrounding scopes. Do not use this option, unless you really,
+ really know what you are doing.
\end{itemize}
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex
index 3aa66b26e79..53528ccfc04 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex
@@ -560,6 +560,45 @@ Here is a detailed description of the options:
\itemoption{grow'}|=|\meta{direction}
This option has the same effect as |grow|, only the children are
arranged in the opposite order.
+
+ \itemoption{growth parent anchor}|=|\meta{anchor}
+ This option allows you to specify which anchor of the parent node is
+ to be used for computing the children's position. For example, when
+ there is only one child and the |level distance| is |2cm|, then the
+ child node will be placed two centimeters below the \meta{anchor} of
+ the parent node. ``Beinng placed'' means that the child node's
+ anchor (which is the anchor specified using the |anchor=| option in
+ the |node| command of the child) is two centimeters below the parent
+ node's \meta{anchor}. The default value of \meta{anchor} is
+ |center|.
+
+ In the following example, the two red lines both have length |1cm|.
+\begin{codeexample}[]
+\begin{tikzpicture}[level distance=1cm]
+ \node [rectangle,draw] (a) at (0,0) {root}
+ [growth parent anchor=south] child;
+
+ \node [rectangle,draw] (b) at (2,0) {root}
+ [growth parent anchor=north east] child;
+
+ \draw [red,thick,dashed] (a.south) -- (a-1);
+ \draw [red,thick,dashed] (b.north east) -- (b-1);
+\end{tikzpicture}
+\end{codeexample}
+
+ In the next example, the top and bottom nodes are aligned at the top
+ and the bottom.
+\begin{codeexample}[]
+\begin{tikzpicture}[level distance=2cm,growth parent anchor=north]
+ \tikzstyle{every node}=[anchor=north,rectangle,draw]
+ \tikzstyle{every child node}=[anchor=south]
+
+ \node at (0,0) {root} child {node {small}};
+
+ \node at (2,0) {big root} child {node {\large big}};
+\end{tikzpicture}
+\end{codeexample}
+
\itemoption{growth function}|=|\meta{macro name}
This rather low-level option allows you to set a new growth
function. The \meta{macro name} must be the name of a macro without
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-main.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-main.tex
deleted file mode 100644
index 0b4b89b6dea..00000000000
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-main.tex
+++ /dev/null
@@ -1,338 +0,0 @@
-% Copyright 2006 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.
-
-% pgf version is defined in \pgfversion in file
-% generic/pgf/utilities/pgfrcs.code.tex
-
-\def\xcolorversion{2.00}
-\def\xkeyvalversion{1.8}
-
-\usepackage[version=0.96]{pgf}
-\usepackage{tikz}
-\usepackage{pgflibraryarrows}
-\usepackage{pgflibraryshapes}
-\usepackage{pgflibraryplotmarks}
-\usepackage{pgflibrarytikzbackgrounds}
-\usepackage{pgflibrarytikztrees}
-\usepackage[left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
-\usepackage{amsmath,amssymb}
-\usepackage{xxcolor}
-\usepackage{pifont}
-\usepackage{makeidx}
-\usepackage[latin1]{inputenc}
-\usepackage{amsmath}
-
-\input{../../macros/pgfmanual-macros}
-
-\makeindex
-
-\makeatletter
-\renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.8em}}
-\renewcommand*\l@subsubsection{\@dottedtocline{3}{4.3em}{3.2em}}
-\makeatother
-
-%\includeonly{pgfmanual-libraries}
-
-% Global styles:
-\tikzstyle{every plot}=[prefix=plots/pgf-]
-\tikzstyle{shape example}=[color=black!30,draw,fill=yellow!30,line width=.5cm,inner xsep=2.5cm,inner ysep=0.5cm]
-
-\index{Options for graphics|see{Graphic options}}
-\index{Options for packages|see{Package options}}
-\index{File|see{Packages and files}}
-\index{Layout|see{Page layout}}
-
-\begin{document}
-
-{
- \parindent0pt
-\vbox{}
-\vskip 3.5cm
-\Huge
-\tikzname\ and \pgfname
-
-\Large
-Manual for Version \pgfversion
-
-\vskip 3cm
-
-\begin{codeexample}[graphic=white]
-\tikz[rotate=30]
- \foreach \x / \xcolor in {0/blue,1/cyan,2/green,3/yellow,4/red}
- \foreach \y / \ycolor in {0/blue,1/cyan,2/green,3/yellow,4/red}
- \shade[ball color=\xcolor!50!\ycolor] (\x,\y) circle (7.5mm);
-\end{codeexample}
-\vskip 0cm plus 1.5fill
-\vbox{}
-\clearpage
-}
-
-{
- \vbox{}
- \vskip0pt plus 1fill
- Für meinen Vater, damit er noch viele schöne \TeX-Graphiken erschaffen kann.
- \vskip0pt plus 3fill
- \vbox{}
- \clearpage
-}
-
-
-\title{The \tikzname\ and \pgfname\ Packages\\
- Manual for Version \pgfversion\\[1mm]
-\large\href{http://sourceforge.net/projects/pgf}{\texttt{http://sourceforge.net/projects/pgf}}}
-\author{Till Tantau\\
- \href{mailto:tantau@users.sourceforge.net}{\texttt{tantau@users.sourceforge.net}}}
-
-\maketitle
-
-\tableofcontents
-
-\clearpage
-
-\part{Getting Started}
-
-This part is intended to help you get started with the \pgfname\
-package. First, the installation process is explained; however, the
-system will typically be already installed on your system, so this can
-often be skipped. Next, a short tutorial is given that explains the
-most often used commands and concepts of \tikzname, without going into
-any of the glorious details. At the end of this section you will find
-some, hopefully useful, hints on how to create ``good'' graphics in
-general. The information in this section is not specific to
-\pgfname.
-
-\vskip3cm
-
-\begin{codeexample}[graphic=white,width=0pt]
-\tikz \draw[thick,rounded corners=8pt]
- (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0);
-\end{codeexample}
-
-\include{pgfmanual-introduction}
-\include{pgfmanual-installation}
-\include{pgfmanual-tutorial}
-\include{pgfmanual-guidelines}
-\include{pgfmanual-drivers}
-
-
-\part{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm}
-\label{part-tikz}
-
-\vskip3cm
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}
- \draw[fill=yellow] (0,0) -- (60:.75cm) arc (60:180:.75cm);
- \draw(120:0.4cm) node {$\alpha$};
-
- \draw[fill=green!30] (0,0) -- (right:.75cm) arc (0:60:.75cm);
- \draw(30:0.5cm) node {$\beta$};
-
- \begin{scope}[shift={(60:2cm)}]
- \draw[fill=green!30] (0,0) -- (180:.75cm) arc (180:240:.75cm);
- \draw (30:-0.5cm) node {$\gamma$};
-
- \draw[fill=yellow] (0,0) -- (240:.75cm) arc (240:360:.75cm);
- \draw (-60:0.4cm) node {$\delta$};
- \end{scope}
-
- \begin{scope}[thick]
- \draw (60:-1cm) node[fill=white] {$E$} -- (60:3cm) node[fill=white] {$F$};
- \draw[red] (-2,0) node[left] {$A$} -- (3,0) node[right]{$B$};
- \draw[blue,shift={(60:2cm)}] (-3,0) node[left] {$C$} -- (2,0) node[right]{$D$};
-
- \draw[shift={(60:1cm)},xshift=4cm]
- node [right,text width=6cm,rounded corners,fill=red!20,inner sep=1ex]
- {
- When we assume that $\color{red}AB$ and $\color{blue}CD$ are
- parallel, i.\,e., ${\color{red}AB} \mathbin{\|} \color{blue}CD$,
- then $\alpha = \delta$ and $\beta = \gamma$.
- };
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-
-
-\include{pgfmanual-tikz-design}
-\include{pgfmanual-tikz-scopes}
-\include{pgfmanual-tikz-coordinates}
-\include{pgfmanual-tikz-paths}
-\include{pgfmanual-tikz-actions}
-\include{pgfmanual-tikz-shapes}
-\include{pgfmanual-tikz-trees}
-\include{pgfmanual-tikz-transformations}
-
-
-
-\part{Libraries and Utilities}
-\label{part-libraries}
-
-In this part the library and utility packages are documented. The
-library packages provide additional predefined graphic objects like
-new arrow heads, or new plot marks. These are not loaded by default
-since many users will not need them.
-
-The utility packages are not directly involved in creating graphics,
-but you may find them useful nonetheless. All of them either directly
-depend on \pgfname\ or they are designed to work well together with
-\pgfname\ even though they can be used in a stand-alone way.
-\vskip2cm
-\medskip
-\noindent
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}[scale=2]
- \shade[top color=blue,bottom color=gray!50] (0,0) parabola (1.5,2.25) |- (0,0);
- \draw (1.05cm,2pt) node[above] {$\displaystyle\int_0^{3/2} \!\!x^2\mathrm{d}x$};
-
- \draw[style=help lines] (0,0) grid (3.9,3.9)
- [step=0.25cm] (1,2) grid +(1,1);
-
- \draw[->] (-0.2,0) -- (4,0) node[right] {$x$};
- \draw[->] (0,-0.2) -- (0,4) node[above] {$f(x)$};
-
- \foreach \x/\xtext in {1/1, 1.5/1\frac{1}{2}, 2/2, 3/3}
- \draw[shift={(\x,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\xtext$};
-
- \foreach \y/\ytext in {1/1, 2/2, 2.25/2\frac{1}{4}, 3/3}
- \draw[shift={(0,\y)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\ytext$};
-
- \draw (-.5,.25) parabola bend (0,0) (2,4) node[below right] {$x^2$};
-\end{tikzpicture}
-\end{codeexample}
-
-\include{pgfmanual-libraries}
-\include{pgfmanual-pgffor}
-\include{pgfmanual-pages}
-\include{pgfmanual-xxcolor}
-
-
-
-\part{The Basic Layer}
-
-\vskip1cm
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}
- \draw[gray,very thin] (-1.9,-1.9) grid (2.9,3.9)
- [step=0.25cm] (-1,-1) grid (1,1);
- \draw[blue] (1,-2.1) -- (1,4.1); % asymptote
-
- \draw[->] (-2,0) -- (3,0) node[right] {$x(t)$};
- \draw[->] (0,-2) -- (0,4) node[above] {$y(t)$};
-
- \foreach \pos in {-1,2}
- \draw[shift={(\pos,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\pos$};
-
- \foreach \pos in {-1,1,2,3}
- \draw[shift={(0,\pos)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\pos$};
-
- \fill (0,0) circle (0.064cm);
- \draw[thick,parametric,domain=0.4:1.5,samples=200]
- % The plot is reparameterised such that there are more samples
- % near the center.
- plot[id=asymptotic-example] function{(t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t))}
- node[right] {$\bigl(x(t),y(t)\bigr) = (t\sin \frac{1}{t}, t\cos \frac{1}{t})$};
-
- \fill[red] (0.63662,0) circle (2pt)
- node [below right,fill=white,yshift=-4pt] {$(\frac{2}{\pi},0)$};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\include{pgfmanual-base-design}
-\include{pgfmanual-base-scopes}
-\include{pgfmanual-base-points}
-\include{pgfmanual-base-paths}
-\include{pgfmanual-base-actions}
-\include{pgfmanual-base-arrows}
-\include{pgfmanual-base-nodes}
-\include{pgfmanual-base-transformations}
-\include{pgfmanual-base-images}
-\include{pgfmanual-base-shadings}
-\include{pgfmanual-base-plots}
-\include{pgfmanual-base-layers}
-\include{pgfmanual-base-quick}
-
-
-
-
-\part{The System Layer}
-\label{part-system}
-
-This part describes the low-level interface of \pgfname, called the
-\emph{system layer}. This interface provides a complete abstraction of
-the internals of the underlying drivers.
-
-Unless you intend to port \pgfname\ to another driver or unless you intend
-to write your own optimized frontend, you need not read this part.
-
-In the following it is assumed that you are familiar with the basic
-workings of the |graphics| package and that you know what
-\TeX-drivers are and how they work.
-
-\vskip1cm
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}[shorten >=1pt,->]
- \tikzstyle{vertex}=[circle,fill=black!25,minimum size=17pt,inner sep=0pt]
-
- \foreach \name/\x in {s/1, 2/2, 3/3, 4/4, 15/11, 16/12, 17/13, 18/14, 19/15, t/16}
- \node[vertex] (G-\name) at (\x,0) {$\name$};
-
- \foreach \name/\angle/\text in {P-1/234/5, P-2/162/6, P-3/90/7, P-4/18/8, P-5/-54/9}
- \node[vertex,xshift=6cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$};
-
- \foreach \name/\angle/\text in {Q-1/234/10, Q-2/162/11, Q-3/90/12, Q-4/18/13, Q-5/-54/14}
- \node[vertex,xshift=9cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$};
-
- \foreach \from/\to in {s/2,2/3,3/4,3/4,15/16,16/17,17/18,18/19,19/t}
- \draw (G-\from) -- (G-\to);
-
- \foreach \from/\to in {1/2,2/3,3/4,4/5,5/1,1/3,2/4,3/5,4/1,5/2}
- { \draw (P-\from) -- (P-\to); \draw (Q-\from) -- (Q-\to); }
-
- \draw (G-3) .. controls +(-30:2cm) and +(-150:1cm) .. (Q-1);
- \draw (Q-5) -- (G-15);
-\end{tikzpicture}
-\end{codeexample}
-
-\include{pgfmanual-pgfsys-overview}
-\include{pgfmanual-pgfsys-commands}
-\include{pgfmanual-pgfsys-paths}
-\include{pgfmanual-pgfsys-protocol}
-
-
-
-\part{References and Index}
-
-\vskip1cm
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}
- \draw[line width=0.3cm,color=red!30,cap=round,join=round] (0,0)--(2,0)--(2,5);
- \draw[help lines] (-2.5,-2.5) grid (5.5,7.5);
- \draw[very thick] (1,-1)--(-1,-1)--(-1,1)--(0,1)--(0,0)--
- (1,0)--(1,-1)--(3,-1)--(3,2)--(2,2)--(2,3)--(3,3)--
- (3,5)--(1,5)--(1,4)--(0,4)--(0,6)--(1,6)--(1,5)
- (3,3)--(4,3)--(4,5)--(3,5)--(3,6)
- (3,-1)--(4,-1);
- \draw[below left] (0,0) node(s){$s$};
- \draw[below left] (2,5) node(t){$t$};
- \fill (0,0) circle (0.06cm) (2,5) circle (0.06cm);
- \draw[->,rounded corners=0.2cm,shorten >=2pt]
- (1.5,0.5)-- ++(0,-1)-- ++(1,0)-- ++(0,2)-- ++(-1,0)-- ++(0,2)-- ++(1,0)--
- ++(0,1)-- ++(-1,0)-- ++(0,-1)-- ++(-2,0)-- ++(0,3)-- ++(2,0)-- ++(0,-1)--
- ++(1,0)-- ++(0,1)-- ++(1,0)-- ++(0,-1)-- ++(1,0)-- ++(0,-3)-- ++(-2,0)--
- ++(1,0)-- ++(0,-3)-- ++(1,0)-- ++(0,-1)-- ++(-6,0)-- ++(0,3)-- ++(2,0)--
- ++(0,-1)-- ++(1,0);
-\end{tikzpicture}
-\end{codeexample}
-
-\printindex
-
-\end{document}
-
-