pgf 3.0.0

git-svn-id: svn://tug.org/texlive/trunk@33057 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 63 insertions, 14 deletions

diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex
index 063b4570a7e..07d04943cc8 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex
@@ -31,7 +31,7 @@ apply to everything within the environment.
 
   \pgfname\ needs to know what \TeX\ driver you are intending to use. In
   most cases \pgfname\ is clever enough to determine the correct driver
-  for you; this is true in particular if you use \LaTeX. Currently, the only
+  for you; this is true in particular if you use \LaTeX. One
   situation where \pgfname\ cannot know the driver ``by itself'' is when
   you use plain \TeX\ or Con\TeX t together with |dvipdfm|. In this case,
   you have to write |\def\pgfsysdriver{pgfsys-dvipdfm.def}|
@@ -47,17 +47,19 @@ apply to everything within the environment.
   like. If you try to load a library a second time, nothing will
   happen.
 
-  \example |\usetikzlibrary{arrows}|
+  \example |\usetikzlibrary{arrows.meta}|
 
   The above command will load a whole bunch of extra arrow tip
   definitions.
 
   What this command does is to load the file
   |tikzlibrary|\meta{library}|.code.tex| for each \meta{library} in
-  the \meta{list of libraries}. Thus, to write your own library file,
-  all you need to do is to place a file of the appropriate name
-  somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t
-  users can then use your library.
+  the \meta{list of libraries}. If this file does not exist, the file
+  |pgflibrary|\meta{library}|.code.tex| is loaded instead. If this
+  file also does not exist, an error message is printed. Thus, to
+  write your own library file, all you need to do is to place a file
+  of the appropriate name somewhere where \TeX\ can find it. \LaTeX,
+  plain \TeX, and Con\TeX t users can then use your library.
 \end{command}
 
 
@@ -111,7 +113,7 @@ they apply.
   coordinates. This will usually give a good
   approximation of the bounding box, but will not always be
   accurate. First, the line thickness of diagonal lines is not taken
-  into account correctly. Second, controls points of a curve often lie far
+  into account correctly. Second, control points of a curve often lie far
   ``outside'' the curve and make the bounding box too large. In this
   case, you should use the |[use as bounding box]| option.
 
@@ -121,9 +123,11 @@ they apply.
     Normally, the lower end of the picture is put on the baseline of
     the surrounding text. For example, when you give the code
     |\tikz\draw(0,0)circle(.5ex);|, \pgfname\ will find out that the
-    lower end of the picture is at $-.5\mathrm{ex}$ and that the upper
-    end is at $.5\mathrm{ex}$. Then, the lower end will be put on the
-    baseline, resulting in the following: \tikz\draw(0,0)circle(.5ex);.
+    lower end of the picture is at $-.5\mathrm{ex} - 0.2\mathrm{pt}$
+    (the 0.2pt are half the line width, which is 0.4pt) and that the
+    upper end is at $.5\mathrm{ex}+.5\mathrm{pt}$. Then, the lower end
+    will be put on the baseline, resulting in the following:
+    \tikz\draw(0,0)circle(.5ex);. 
 
     Using this option, you can specify that the picture should be
     raised or lowered such that the height \meta{dimension} is on the
@@ -138,11 +142,11 @@ $A \mathbin{\tikz[baseline] \draw[->>] (0pt,.5ex) -- (3ex,.5ex);} B$
 
     Instead of a \meta{dimension} you can also provide a coordinate in
     parentheses. Then the effect is to put the baseline on the
-    $y$-coordinate that the give \meta{coordinate} has \emph{at the
+    $y$-coordinate that the given \meta{coordinate} has \emph{at the
       end of the picture}. This means that, at the end of the picture,
     the \meta{coordinate} is evaluated and then the baseline is set
     to the $y$-coordinate of the resulting point. This makes it easy
-    to reference the $y$-coordinate of, say, the base line of nodes.
+    to reference the $y$-coordinate of, say, the baseline of nodes.
 \begin{codeexample}[]
 Hello
 \tikz[baseline=(X.base)]
@@ -211,7 +215,7 @@ Top align:
   This will have the desired effect.
 \end{environment}
 
-In other \TeX\ format, you should use instead the following commands:
+In other \TeX\ formats, you should use the following commands instead:
 
 \begin{plainenvironment}{{tikzpicture}\opt{\oarg{options}}}
   This is the plain \TeX\ version of the environment.
@@ -247,6 +251,23 @@ commands.
 \end{command}
 
 
+\subsubsection{Handling Catcodes and the Babel Package}
+
+Inside a \tikzname\ picture, most symbols need to have the category 
+code 12 (normal text) in order to ensure that the parser works
+properly. This is typically not the case when packages like |babel|
+are used, which change catcodes aggressively.
+
+To solve this problem, \tikzname\ provides a small library also called
+|babel| (which can, however, also be used together with any other
+package that globally changes category codes). What it does is to
+reset the category codes at the beginning of every |{tikzpicture}| and
+to restore them at the beginning of every node. In almost all cases,
+this is exactly would you would expect and need, so I recommend to
+always load this library by saying |\usetikzlibrary{babel}|. For
+details on what, exactly, happens with the category codes, see
+Section~\ref{section-library-babel}.
+
 
 \subsubsection{Adding a Background}
 
@@ -365,6 +386,34 @@ square bracket must follow, otherwise the brace is treated as a normal
 \TeX\ scope.
 
 
+\subsubsection{Single Command Scopes}
+
+In some situations it is useful to create a scope for a single
+command. For instance, when you wish to use algorithm graph drawing
+in order to layout a tree, the path of the tree needs to be surrounded
+by a scope whose only purpose is to take a key that selects a layout
+for the scope. Similarly, in order to put something on a background
+layer, a scope needs to be created. In such cases, where it will 
+cumbersome to create a |\begin{scope}| and |\end{scope}| pair just for
+a single command, the |\scoped| command may be useful:
+
+\begin{command}{\scoped\opt{\oarg{options}}\meta{path command}}
+  This command works like |\tikz|, only you can use it inside a
+  |{tikzpicture}|. It will take the following \meta{path command} and
+  put it inside a |{scope}| with the \meta{options} set. The
+  \meta{path command} may either be a single command ended by a
+  semicolon or it may contain multiple commands, but then they must be
+  surrounded by curly braces.
+  \begin{codeexample}[]
+\begin{tikzpicture}
+  \node [fill=white] at (1,1) {Hello world};
+  \scoped [on background layer]
+    \draw (0,0) grid (3,2);
+\end{tikzpicture}
+  \end{codeexample}
+\end{command}
+
+
 \subsubsection{Using Scopes Inside Paths}
 
 The |\path| command, which is described in much more detail in later
@@ -463,7 +512,7 @@ my style/.style={draw=red,fill=red!20}
 \end{codeexample}
 
 The meaning of the curious |/.style| is the following: ``The key
-|my style| should not be used here but, rather, be defined. So, setup
+|my style| should not be used here but, rather, be defined. So, set up
 things such that using the key |my style| will, in the following, have
 the same effect as if we had written |draw=red,fill=red!20| instead.''