% 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}