% Copyright 2008 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{pgflibrary}{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{pgflibrary}

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 noticably
the |babel| package, agressively 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}



\endinput



