summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-library-babel.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-babel.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-library-babel.tex94
1 files changed, 94 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-babel.tex b/graphics/pgf/base/doc/pgfmanual-en-library-babel.tex
new file mode 100644
index 0000000000..221a84c640
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-library-babel.tex
@@ -0,0 +1,94 @@
+% Copyright 2019 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{Babel Library}
+\label{section-library-babel}
+
+\begin{tikzlibrary}{babel}
+ A tiny library that make the interaction with the |babel| package easier.
+ Despite the name, it may also be useful in other contexts, namely whenever
+ the catcodes of important symbols are changed globally. Normally, using
+ this library is always a good idea; it is not always loaded by default
+ since in some rare cases it may break old code.
+\end{tikzlibrary}
+
+The problems this library tries to fix have to do with the so-called
+``catcodes'' of symbols used inside \tikzname. In normal \TeX\ operation,
+symbols like |!| or |"| are ``normal'' characters and the \tikzname\ parser
+expects them to be. Some packages, most noticeably the |babel| package,
+aggressively change these character codes so that for instance a semicolon gets
+a little extra space in |french| mode or a quotation mark followed by a
+vertical bar breaks ligatures in |german| mode.
+
+Unfortunately, \tikzname\ expects the character codes of some symbols to be
+``normal''. In some important cases it will tolerate changed character codes,
+but when the changes made by |babel| (or some other package) are too
+``aggressive'', compilation of \tikzname\ code will fail.
+
+The |babel| library of \tikzname\ is intended to help out in this situation.
+All this library does is to set the following two keys to |true|. You can,
+however, also set these keys directly and also switch them off or on
+individually and independently of this library.
+
+\begin{key}{/tikz/handle active characters in code=\opt{\meta{true or false}} (initially false)}
+ When this key is set, at the beginning of every |\tikz| command and every
+ |{tikzpicture}|, the character codes of all symbols used by \tikzname\ are
+ reset to their normal values. Furthermore, at the beginning of each node,
+ the catcodes are restored to the values they had prior to the current
+ picture.
+
+ The net effect of this is that, in most cases, symbols having a special
+ character code can be used nicely both in \tikzname\ code and also in node
+ texts.
+
+ In the following, slightly silly, example we make the dot an active
+ character and define it in some strange way. Now, in the later \tikzname\
+ command, the dot in |3.0cm| may no longer be active and setting the
+ |handle...| option achieves exactly this. However, as can be seen, the dot
+ is once more active inside the node.
+ %
+\begin{codeexample}[]
+\catcode`\.=\active
+\def.{\o}
+
+\tikz [handle active characters in code]
+ \node [draw, minimum width=3.0cm] {hall. pe.ple};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/handle active characters in nodes=\opt{\meta{true or false}} (initially false)}
+ This key is needed for a special situation: As explained for the
+ |handle ... code| key, that key switches off all special meaning of symbols
+ and switches them back on again at the beginning of nodes. However, there
+ is one situation when this is not possible: When some text has already been
+ read by \TeX, the catcodes can no longer change. Now, for normal nodes this
+ is not a problem since their contents has not been read at the moment the
+ catcodes are restored. In contrast for label nodes for edges, nodes
+ produced by the |graph| and |quotes| libraries, and some others nodes,
+ their text \emph{has} already been read when the catcodes get adjusted.
+
+ The present key may help in such situations: It causes the text of all such
+ ``indirectly created'' nodes to be surrounded by a call to the
+ |\scantokens| command. This command attempts to reread an already read
+ text, but allows catcodes to change. As users of this command will know, it
+ is not a perfect substitute for directly reading the text by \TeX, but it
+ normally has the desired effect.
+ %
+\begin{codeexample}[]
+\catcode`\.=\active
+\def.{\o}
+
+\tikz [handle active characters in code,
+ handle active characters in nodes]
+ \node [draw, label=f..] {hall. pe.ple};
+\end{codeexample}
+ %
+\end{key}