% Copyright 2011, 2012 by Florêncio Neves
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.

% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.

% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
% The preamble of this file contains parts of the files
% pgfmanual-en-main.tex and pgfmanual-en-macros.tex of the pgf package,
% copyright 2006 by Till Tantau and distributed under LPPL and/or GNU
% GPL.
%
% To get cross-references to the pgf manual, it is necessary to
% compile it and copy all resulting .aux files to the directory of
% tikz-cd-doc.tex.
%
% To compile with luatex, the fonts texgyrepagella-math.otf,
% xits-math.otf and lmodern-math.otf are needed.

\documentclass{ltxdoc}

        \def\xcolorversion{2.00}

        \usepackage[version=latest]{pgf}

        \usepackage{xkeyval,calc,listings,tikz,fp}

        \usepackage{hyperref}
        \hypersetup{%
          colorlinks=true,	% use true to enable colors below:
          linkcolor=blue,%red,
          filecolor=blue,%magenta,
          pagecolor=blue,%red,
          urlcolor=blue,%cyan,
          citecolor=blue,
          pdfborder=0 0 0,
        }

        % We need lots of libraries...
        \usetikzlibrary{
          arrows,
          calc,
          fit,
          patterns,
          plotmarks,
          shapes.geometric,
          shapes.misc,
          shapes.symbols,
          shapes.arrows,
          shapes.callouts,
          shapes.multipart,
          shapes.gates.logic.US,
          shapes.gates.logic.IEC,
          circuits.logic.US,
          circuits.logic.IEC,
          circuits.logic.CDH,
          circuits.ee.IEC,
          datavisualization,
          datavisualization.formats.functions,
          er,
          automata,
          backgrounds,
          chains,
          topaths,
          trees,
          petri,
          mindmap,
          matrix,
          calendar,
          folding,
          fadings,
          shadings,
          spy,
          through,
          turtle,
          positioning,
          scopes,
          decorations.fractals,
          decorations.shapes,
          decorations.text,
          decorations.pathmorphing,
          decorations.pathreplacing,
          decorations.footprints,
          decorations.markings,
          shadows,
          lindenmayersystems,
          intersections,
          fixedpointarithmetic,
          fpu,
          svg.path,
          external,
        }

        \iffalse
        % \iftrue
        \tikzexternalize[
        mode=list only,export=true,% simply skips EVERY picture -> good for debugging the text.
        ]
        {pgfmanual}

        \tikzifexternalizing{%
          \pgfkeys{/pdflinks/codeexample links=false}%
        }{}%
        \fi


        \usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
        \usepackage{amsmath,amssymb}
        \usepackage{xxcolor}
        \usepackage{pifont}
        \usepackage{makeidx}
        \usepackage{amsmath}

        \graphicspath{{../../images/}}              % TODOsp: under windows this would go up 2 directories, but the file is only one directory up
        % \makeindex

        \providecommand\href[2]{\texttt{#1}}
        \providecommand\hypertarget[2]{\texttt{#1}}
        \providecommand\hyperlink[2]{\texttt{#1}}


        \colorlet{examplefill}{yellow!80!black}
        \definecolor{graphicbackground}{rgb}{0.96,0.96,0.8}
        \definecolor{codebackground}{rgb}{0.8,0.8,1}

        \newenvironment{pgfmanualentry}{\list{}{\leftmargin=2em\itemindent-\leftmargin\def\makelabel##1{\hss##1}}}{\endlist}
        \newcommand\pgfmanualentryheadline[1]{\itemsep=0pt\parskip=0pt\item\strut{#1}\par\topsep=0pt}
        \newcommand\pgfmanualbody{\parskip3pt}



        \newenvironment{pgflayout}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{\texttt{\string\pgfpagesuselayout\char`\{\declare{#1}\char`\}}\oarg{options}}
            \index{#1@\protect\texttt{#1} layout}%
            \index{Page layouts!#1@\protect\texttt{#1}}%
            \pgfmanualpdflabel{#1}{}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }


        \newenvironment{command}[1]{
          \begin{pgfmanualentry}
            \extractcommand#1\@@
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{commandlist}[1]{%
          \begin{pgfmanualentry}
            \foreach \xx in {#1} {%
              \expandafter\extractcommand\xx\@@
            }%
            \pgfmanualbody
          }{%
          \end{pgfmanualentry}
        }%

        % \begin{internallist}[register]{\pgf@xa}
        % \end{internallist}
        % 
        % \begin{internallist}[register]{\pgf@xa,\pgf@xb}
        % \end{internallist}
        \newenvironment{internallist}[2][register]{%
          \begin{pgfmanualentry}
            \foreach \xx in {#2} {%
              \expandafter\extractinternalcommand\expandafter{\xx}{#1}%
            }%
            \pgfmanualbody
          }{%
          \end{pgfmanualentry}
        }%
        \def\extractinternalcommand#1#2{%
          \pgfmanualentryheadline{Internal #2 \declare{\texttt{\string#1}}}%
          \removeats{#1}%
          \index{Internals!\strippedat @\protect\myprintocmmand{\strippedat}}%
          \index{\strippedat @\protect\myprintocmmand{\strippedat}}%
          \pgfmanualpdflabel{\textbackslash\strippedat}{}%
        }

        %% MW: START MATH MACROS
        \def\mvar#1{{\ifmmode\textrm{\textit{#1}}\else\rmfamily\textit{#1}\fi}}

        \makeatletter

        \def\extractmathfunctionname#1{\extractmathfunctionname@#1(,)\tmpa\tmpb}
        \def\extractmathfunctionname@#1(#2)#3\tmpb{\def\mathname{#1}}

        \makeatother

        \newenvironment{math-function}[1]{
          \def\mathdefaultname{#1}
          \extractmathfunctionname{#1}
          \edef\mathurl{{math:\mathname}}\expandafter\hypertarget\expandafter{\mathurl}{}%
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{\texttt{#1}}%
            \index{\mathname @\protect\texttt{\mathname} math function}%
            \index{Math functions!\mathname @\protect\texttt{\mathname}}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \def\pgfmanualemptytext{}
        \def\pgfmanualvbarvbar{\char`\|\char`\|}

        \newenvironment{math-operator}[4][]{%
          \begin{pgfmanualentry}
            \csname math#3operator\endcsname{#2}{#4}
            \def\mathtest{#4}%
            \ifx\mathtest\pgfmanualemptytext%
            \def\mathtype{(#3 operator)}
            \else%
            \def\mathtype{(#3 operator; uses the \texttt{#4} function)}
            \fi%
            \pgfmanualentryheadline{\mathexample\hfill\mathtype}%
            \def\mathtest{#1}%
            \ifx\mathtest\pgfmanualemptytext%
            \index{#2@\protect\texttt{#2} #3 math operator}%  
            \index{Math operators!#2@\protect\texttt{#2}}%
            \fi%
            \pgfmanualbody
          }
          {\end{pgfmanualentry}}

        \newenvironment{math-operators}[5][]{%
          \begin{pgfmanualentry}
            \csname math#4operator\endcsname{#2}{#3}
            \def\mathtest{#5}%
            \ifx\mathtest\pgfmanualemptytext%
            \def\mathtype{(#4 operators)}
            \else%
            \def\mathtype{(#4 operators; use the \texttt{#5} function)}
            \fi%
            \pgfmanualentryheadline{\mathexample\hfill\mathtype}%
            \def\mathtest{#1}%
            \ifx\mathtest\pgfmanualemptytext%
            \index{#2#3@\protect\texttt{#2\protect\ #3} #4 math operators}% 
            \index{Math operators!#2#3@\protect\texttt{#2\protect\ #3}}%
vv            \fi%
            \pgfmanualbody
          }
          {\end{pgfmanualentry}}

        \def\mathinfixoperator#1#2{%
          \def\mathoperator{\texttt{#1}}%
          \def\mathexample{\mvar{x}\space\texttt{#1}\space\mvar{y}}%
        }

        \def\mathprefixoperator#1#2{%
          \def\mathoperator{\texttt{#1}}%
          \def\mathexample{\texttt{#1}\mvar{x}}%
        }

        \def\mathpostfixoperator#1#2{%
          \def\mathoperator{\texttt{#1}}
          \def\mathexample{\mvar{x}\texttt{#1}}%
        }

        \def\mathgroupoperator#1#2{%
          \def\mathoperator{\texttt{#1\ #2}}%
          \def\mathexample{\texttt{#1}\mvar{x}\texttt{#2}}%
        }

        \expandafter\let\csname matharray accessoperator\endcsname=\mathgroupoperator
        \expandafter\let\csname matharrayoperator\endcsname=\mathgroupoperator

        \def\mathconditionaloperator#1#2{%
          \def\mathoperator{#1\space#2}
          \def\mathexample{\mvar{x}\ \texttt{#1}\ \mvar{y}\ {\texttt{#2}}\ \mvar{z}}
        }

        \newcommand\mathcommand[1][\mathdefaultname]{%
          \expandafter\makemathcommand#1(\empty)\stop%
          \expandafter\extractcommand\mathcommandname\@@%
          \medskip
        }
        \makeatletter

        \def\makemathcommand#1(#2)#3\stop{%
          \expandafter\def\expandafter\mathcommandname\expandafter{\csname pgfmath#1\endcsname}%
          \ifx#2\empty%
          \else%
          \@makemathcommand#2,\stop,
          \fi}
        \def\@makemathcommand#1,{%
          \ifx#1\stop%
          \else%
          \expandafter\def\expandafter\mathcommandname\expandafter{\mathcommandname{\ttfamily\char`\{#1\char`\}}}%
          \expandafter\@makemathcommand%
          \fi}
        \makeatother

        \def\calcname{\textsc{calc}}
        %% MW: END MATH MACROS


        \def\extractcommand#1#2\@@{%
          \pgfmanualentryheadline{\declare{\texttt{\string#1}}#2}%
          \removeats{#1}%
          \index{\strippedat @\protect\myprintocmmand{\strippedat}}
          \pgfmanualpdflabel{\textbackslash\strippedat}{}%
        }


        % \begin{environment}{{name}\marg{arguments}}
        \renewenvironment{environment}[1]{
          \begin{pgfmanualentry}
            \extractenvironement#1\@@
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \def\extractenvironement#1#2\@@{%
          \pgfmanualentryheadline{{\ttfamily\char`\\begin\char`\{\declare{#1}\char`\}}#2}%
          \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}%
          \pgfmanualentryheadline{{\ttfamily\char`\\end\char`\{\declare{#1}\char`\}}}%
          \index{#1@\protect\texttt{#1} environment}%
          \index{Environments!#1@\protect\texttt{#1}}
          \pgfmanualpdflabel{#1}{}%
        }


        \newenvironment{plainenvironment}[1]{
          \begin{pgfmanualentry}
            \extractplainenvironement#1\@@
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \def\extractplainenvironement#1#2\@@{%
          \pgfmanualentryheadline{{\ttfamily\declare{\char`\\#1}}#2}%
          \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}%
          \pgfmanualentryheadline{{\ttfamily\declare{\char`\\end#1}}}%
          \index{#1@\protect\texttt{#1} environment}%
          \index{Environments!#1@\protect\texttt{#1}}%
        }


        \newenvironment{contextenvironment}[1]{
          \begin{pgfmanualentry}
            \extractcontextenvironement#1\@@
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \def\extractcontextenvironement#1#2\@@{%
          \pgfmanualentryheadline{{\ttfamily\declare{\char`\\start#1}}#2}%
          \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}%
          \pgfmanualentryheadline{{\ttfamily\declare{\char`\\stop#1}}}%
          \index{#1@\protect\texttt{#1} environment}%
          \index{Environments!#1@\protect\texttt{#1}}}


        \newenvironment{shape}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{Shape {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} shape}%
            \index{Shapes!#1@\protect\texttt{#1}}
            \pgfmanualpdflabel{#1}{}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{shading}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{Shading {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} shading}%
            \index{Shadings!#1@\protect\texttt{#1}}
            \pgfmanualpdflabel{#1}{}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }


        \newenvironment{dataformat}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{Format {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} format}%
            \index{Formats!#1@\protect\texttt{#1}}
            \pgfmanualpdflabel{#1}{}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{handler}[1]{
          \begin{pgfmanualentry}
            \extracthandler#1\@nil%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \def\gobble#1{}
        \def\extracthandler#1#2\@nil{%
          \pgfmanualentryheadline{Key handler \meta{key}{\ttfamily/\declare{#1}}#2}%
          \index{\gobble#1@\protect\texttt{#1} handler}%
          \index{Key handlers!#1@\protect\texttt{#1}}
          \pgfmanualpdflabel{/handlers/#1}%
        }


        \makeatletter


        \newenvironment{stylekey}[1]{
          \begin{pgfmanualentry}
            \def\extrakeytext{style, }
            \extractkey#1\@nil%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \def\choicesep{$\vert$}%
        \def\choicearg#1{\texttt{#1}}

        \newif\iffirstchoice

        % \mchoice{choice1,choice2,choice3}
        \newcommand\mchoice[1]{%
          \begingroup
          \firstchoicetrue
          \foreach \mchoice@ in {#1} {%
            \iffirstchoice
            \global\firstchoicefalse
            \else
            \choicesep
            \fi
            \choicearg{\mchoice@}%
          }%
          \endgroup
        }%

        % \begin{key}{/path/x=value}
        %   \begin{key}{/path/x=value (initially XXX)}
        %     \begin{key}{/path/x=value (default XXX)}
        \newenvironment{key}[1]{
          \begin{pgfmanualentry}
            \def\extrakeytext{}
            % \def\altpath{\emph{\color{gray}or}}%
            \extractkey#1\@nil%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        % \insertpathifneeded{a key}{/pgf} -> assign mykey={/pgf/a key}
        % \insertpathifneeded{/tikz/a key}{/pgf} -> assign mykey={/tikz/a key}
        % 
        % #1: the key
        % #2: a default path (or empty)
        \def\insertpathifneeded#1#2{%
          \def\insertpathifneeded@@{#2}%
          \ifx\insertpathifneeded@@\empty
          \def\mykey{#1}%
          \else
          \insertpathifneeded@#2\@nil
          \ifpgfutil@in@
          \def\mykey{#2/#1}%
          \else
          \def\mykey{#1}%
          \fi
          \fi
        }%
        \def\insertpathifneeded@#1#2\@nil{%
          \def\insertpathifneeded@@{#1}%
          \def\insertpathifneeded@@@{/}%
          \ifx\insertpathifneeded@@\insertpathifneeded@@@
          \pgfutil@in@true
          \else
          \pgfutil@in@false
          \fi
        }%

        % \begin{keylist}[default path]
        %   {/path/option 1=value,/path/option 2=value2}
        % \end{keylist}
        \newenvironment{keylist}[2][]{%
          \begin{pgfmanualentry}
            \def\extrakeytext{}%
            \foreach \xx in {#2} {%
              \expandafter\insertpathifneeded\expandafter{\xx}{#1}%
              \expandafter\extractkey\mykey\@nil%
            }%
            \pgfmanualbody
          }{%
          \end{pgfmanualentry}
        }%

        \def\extractkey#1\@nil{%
          \pgfutil@in@={#1}%
          \ifpgfutil@in@%
          \extractkeyequal#1\@nil
          \else%
          \pgfutil@in@{(initial}{#1}%
          \ifpgfutil@in@%
          \extractequalinitial#1\@nil%
          \else
          \pgfmanualentryheadline{{\ttfamily\declare{#1}}\hfill(\extrakeytext no value)}%
          \def\mykey{#1}%
          \def\mypath{}%
          \def\myname{}%
          \firsttimetrue%
          \decompose#1/\nil%
          \fi
          \fi%
        }

        \def\extractkeyequal#1=#2\@nil{%
          \pgfutil@in@{(default}{#2}%
          \ifpgfutil@in@%
          \extractdefault{#1}#2\@nil%
          \else%
          \pgfutil@in@{(initial}{#2}%
          \ifpgfutil@in@%
          \extractinitial{#1}#2\@nil%
          \else
          \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill(\extrakeytext no default)}%
          \fi%
          \fi%
          \def\mykey{#1}%
          \def\mypath{}%
          \def\myname{}%
          \firsttimetrue%
          \decompose#1/\nil%
        }

        \def\extractdefault#1#2(default #3)\@nil{%
          \pgfmanualentryheadline{{\ttfamily\declare{#1}\opt{=}}\opt{#2}\hfill (\extrakeytext default {\ttfamily#3})}%
        }

        \def\extractinitial#1#2(initially #3)\@nil{%
          \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill (\extrakeytext no default, initially {\ttfamily#3})}%
        }

        \def\extractequalinitial#1 (initially #2)\@nil{%
          \pgfmanualentryheadline{{\ttfamily\declare{#1}}\hfill (\extrakeytext initially {\ttfamily#2})}%
          \def\mykey{#1}%
          \def\mypath{}%
          \def\myname{}%
          \firsttimetrue%
          \decompose#1/\nil%
        }

        % Introduces a key alias '/#1/<name of current key>'
        % to be used inside of \begin{key} ... \end{key}
        \def\keyalias#1{\vspace{-3pt}\item{\small alias {\ttfamily/#1/\myname}}\vspace{-2pt}\par
          \pgfmanualpdflabel{/#1/\myname}{}%
        }

        \newif\iffirsttime

        \makeatother

        \def\decompose/#1/#2\nil{%
          \def\test{#2}%
          \ifx\test\empty%
          % aha.
          \index{#1@\protect\texttt{#1} key}%
          \index{\mypath#1@\protect\texttt{#1}}%
          \def\myname{#1}%
          \else%
          \iffirsttime
          \begingroup	
          % also make a pdf link anchor with full key path.
          \def\hyperlabelwithoutslash##1/\nil{%
            \pgfmanualpdflabel{##1}{}%
          }%
          \hyperlabelwithoutslash/#1/#2\nil
          \endgroup
          \def\mypath{#1@\protect\texttt{/#1/}!}%
          \firsttimefalse
          \else
          \expandafter\def\expandafter\mypath\expandafter{\mypath#1@\protect\texttt{#1/}!}%
          \fi
          \def\firsttime{}
          \decompose/#2\nil%
          \fi%
        }

        \def\indexkey#1{%
          \def\mypath{}%
          \decompose#1/\nil%
        }

        \newenvironment{predefinedmethod}[1]{
          \begin{pgfmanualentry}
            \extractpredefinedmethod#1\@nil
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }
        \def\extractpredefinedmethod#1(#2)\@nil{%
          \pgfmanualentryheadline{Method \declare{\ttfamily #1}\texttt(#2\texttt) \hfill(predefined for all classes)}
          \index{#1@\protect\texttt{#1} method}%
          \index{Methods!#1@\protect\texttt{#1}}
          \pgfmanualpdflabel{#1}{}%
        }


        \newenvironment{ooclass}[1]{
          \begin{pgfmanualentry}
            \def\currentclass{#1}
            \pgfmanualentryheadline{Class \declare{\texttt{#1}}}
            \index{#1@\protect\texttt{#1} class}%
            \index{Class #1@Class \protect\texttt{#1}}%
            \index{Classes!#1@\protect\texttt{#1}}
            \pgfmanualpdflabel{#1}{}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{method}[1]{
          \begin{pgfmanualentry}
            \extractmethod#1\@nil
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }
        \def\extractmethod#1(#2)\@nil{%
          \def\test{#1}
          \ifx\test\currentclass
          \pgfmanualentryheadline{Constructor \declare{\ttfamily #1}\texttt(#2\texttt)}
          \else
          \pgfmanualentryheadline{Method \declare{\ttfamily #1}\texttt(#2\texttt)}
          \fi
          \index{#1@\protect\texttt{#1} method}%
          \index{Methods!#1@\protect\texttt{#1}}
          \index{Class \currentclass!#1@\protect\texttt{#1}}%
          \pgfmanualpdflabel{#1}{}%
        }

        \newenvironment{attribute}[1]{
          \begin{pgfmanualentry}
            \extractattribute#1\@nil
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }
        \def\extractattribute#1=#2;\@nil{%
          \def\test{#2}%
          \ifx\test\@empty
          \pgfmanualentryheadline{Private attribute \declare{\ttfamily #1} \hfill (initially empty)}
          \else
          \pgfmanualentryheadline{Private attribute \declare{\ttfamily #1} \hfill (initially {\ttfamily #2})}
          \fi
          \index{#1@\protect\texttt{#1} attribute}%
          \index{Attributes!#1@\protect\texttt{#1}}
          \index{Class \currentclass!#1@\protect\texttt{#1}}%
          \pgfmanualpdflabel{#1}{}%
        }



        \newenvironment{predefinednode}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{Predefined node {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} node}%
            \index{Predefined node!#1@\protect\texttt{#1}}
            \pgfmanualpdflabel{#1}{}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{coordinatesystem}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{Coordinate system {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} coordinate system}%
            \index{Coordinate systems!#1@\protect\texttt{#1}}
            \pgfmanualpdflabel{#1}{}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{snake}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{Snake {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} snake}%
            \index{Snakes!#1@\protect\texttt{#1}}
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{decoration}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{Decoration {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} decoration}%
            \index{Decorations!#1@\protect\texttt{#1}}
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }


        \def\pgfmanualbar{\char`\|}
        \makeatletter
        \newenvironment{pathoperation}[3][]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\path}\
                \ \dots}
              \declare{\texttt{#2}}#3\ \textcolor{gray}{\dots\texttt{;}}}%
            \def\pgfmanualtest{#1}%
            \ifx\pgfmanualtest\@empty%
            \index{#2@\protect\texttt{#2} path operation}%
            \index{Path operations!#2@\protect\texttt{#2}}%
            \pgfmanualpdflabel{#2}{}%
            \fi%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }
        \newenvironment{datavisualizationoperation}[3][]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\datavisualization}\
                \ \dots}
              \declare{\texttt{#2}}#3\ \textcolor{gray}{\dots\texttt{;}}}%
            \def\pgfmanualtest{#1}%
            \ifx\pgfmanualtest\@empty%
            \index{#2@\protect\texttt{#2} (data visualization)}%
            \index{Data visualization!#2@\protect\texttt{#2}}%
            \pgfmanualpdflabel{#2}{}%
            \fi%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }
        \makeatother

        \def\extractcommand#1#2\@@{%
          \pgfmanualentryheadline{\declare{\texttt{\string#1}}#2}%
          \removeats{#1}%
          \index{\strippedat @\protect\myprintocmmand{\strippedat}}
          \pgfmanualpdflabel{\textbackslash\strippedat}{}%
        }

        \def\doublebs{\texttt{\char`\\\char`\\}}


        \newenvironment{package}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{{\ttfamily\char`\\usepackage\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space  \LaTeX}}
            \index{#1@\protect\texttt{#1} package}%
            \index{Packages and files!#1@\protect\texttt{#1}}%
            \pgfmanualentryheadline{{\ttfamily\char`\\input \declare{#1}.tex\space\space\space \char`\%\space\space  plain \TeX}}
            \pgfmanualentryheadline{{\ttfamily\char`\\usemodule[\declare{#1}]\space\space \char`\%\space\space  Con\TeX t}}
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }


        \newenvironment{pgfmodule}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{{\ttfamily\char`\\usepgfmodule\char`\{\declare{#1}\char`\}\space\space\space
                \char`\%\space\space  \LaTeX\space and plain \TeX\space and pure pgf}}
            \index{#1@\protect\texttt{#1} module}%
            \index{Modules!#1@\protect\texttt{#1}}%
            \pgfmanualentryheadline{{\ttfamily\char`\\usepgfmodule[\declare{#1}]\space\space \char`\%\space\space  Con\TeX t\space and pure pgf}}
            \pgfmanualbody
            \pgfmanualpdflabel{#1}{}%
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{pgflibrary}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{{\ttfamily\char`\\usepgflibrary\char`\{\declare{#1}\char`\}\space\space\space
                \char`\%\space\space  \LaTeX\space and plain \TeX\space and pure pgf}}
            \index{#1@\protect\texttt{#1} library}%
            \index{Libraries!#1@\protect\texttt{#1}}%
            \pgfmanualentryheadline{{\ttfamily\char`\\usepgflibrary[\declare{#1}]\space\space \char`\%\space\space  Con\TeX t\space and pure pgf}}
            \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary\char`\{\declare{#1}\char`\}\space\space
                \char`\%\space\space  \LaTeX\space and plain \TeX\space when using \tikzname}}
            \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary[\declare{#1}]\space
                \char`\%\space\space  Con\TeX t\space when using \tikzname}}
            \pgfmanualbody
            \pgfmanualpdflabel{#1}{}%
          }
          {
          \end{pgfmanualentry}
        }

        \newenvironment{tikzlibrary}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space  \LaTeX\space and plain \TeX}}
            \index{#1@\protect\texttt{#1} library}%
            \index{Libraries!#1@\protect\texttt{#1}}%
            \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary[\declare{#1}]\space \char`\%\space\space Con\TeX t}}
            \pgfmanualbody
            \pgfmanualpdflabel{#1}{}%
          }
          {
          \end{pgfmanualentry}
        }



        \newenvironment{filedescription}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{File {\ttfamily\declare{#1}}}%
            \index{#1@\protect\texttt{#1} file}%
            \index{Packages and files!#1@\protect\texttt{#1}}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }


        \newenvironment{packageoption}[1]{
          \begin{pgfmanualentry}
            \pgfmanualentryheadline{{\ttfamily\char`\\usepackage[\declare{#1}]\char`\{pgf\char`\}}}
            \index{#1@\protect\texttt{#1} package option}%
            \index{Package options for \textsc{pgf}!#1@\protect\texttt{#1}}%
            \pgfmanualbody
          }
          {
          \end{pgfmanualentry}
        }



        \newcommand\opt[1]{{\color{black!50!green}#1}}
        \newcommand\ooarg[1]{{\ttfamily[}\meta{#1}{\ttfamily]}}

        \def\opt{\afterassignment\pgfmanualopt\let\next=}
        \def\pgfmanualopt{\ifx\next\bgroup\bgroup\color{black!50!green}\else{\color{black!50!green}\next}\fi}



        \def\beamer{\textsc{beamer}}
        \def\pdf{\textsc{pdf}}
        \def\eps{\texttt{eps}}
        \def\pgfname{\textsc{pgf}}
        \def\tikzname{Ti\emph{k}Z}
        \def\pstricks{\textsc{pstricks}}
        \def\prosper{\textsc{prosper}}
        \def\seminar{\textsc{seminar}}
        \def\texpower{\textsc{texpower}}
        \def\foils{\textsc{foils}}

        {
          \makeatletter
          \global\let\myempty=\@empty
          \global\let\mygobble=\@gobble
          \catcode`\@=12
          \gdef\getridofats#1@#2\relax{%
            \def\getridtest{#2}%
            \ifx\getridtest\myempty%
            \expandafter\def\expandafter\strippedat\expandafter{\strippedat#1}
            \else%
            \expandafter\def\expandafter\strippedat\expandafter{\strippedat#1\protect\printanat}
            \getridofats#2\relax%
            \fi%
          }

          \gdef\removeats#1{%
            \let\strippedat\myempty%
            \edef\strippedtext{\stripcommand#1}%
            \expandafter\getridofats\strippedtext @\relax%
          }

          \gdef\stripcommand#1{\expandafter\mygobble\string#1}
        }

        \def\printanat{\char`\@}

        \def\declare{\afterassignment\pgfmanualdeclare\let\next=}
        \def\pgfmanualdeclare{\ifx\next\bgroup\bgroup\color{red!75!black}\else{\color{red!75!black}\next}\fi}


        \let\textoken=\command
        \let\endtextoken=\endcommand

        \def\myprintocmmand#1{\texttt{\char`\\#1}}

        \def\example{\par\smallskip\noindent\textit{Example: }}
        \def\themeauthor{\par\smallskip\noindent\textit{Theme author: }}


        \def\indexoption#1{%
          \index{#1@\protect\texttt{#1} option}%
          \index{Graphic options and styles!#1@\protect\texttt{#1}}%
        }

        \def\itemcalendaroption#1{\item \declare{\texttt{#1}}%
          \index{#1@\protect\texttt{#1} date test}%
          \index{Date tests!#1@\protect\texttt{#1}}%
        }



        \def\class#1{\list{}{\leftmargin=2em\itemindent-\leftmargin\def\makelabel##1{\hss##1}}%
          \extractclass#1@\par\topsep=0pt}
        \def\endclass{\endlist}
        \def\extractclass#1#2@{%
        \item{{{\ttfamily\char`\\documentclass}#2{\ttfamily\char`\{\declare{#1}\char`\}}}}%
          \index{#1@\protect\texttt{#1} class}%
          \index{Classes!#1@\protect\texttt{#1}}}

        \def\partname{Part}

        \makeatletter
        \def\index@prologue{\section*{Index}\addcontentsline{toc}{section}{Index}
          This index only contains automatically generated entries. A good
          index should also contain carefully selected keywords. This index is
          not a good index.
          \bigskip
        }
        \c@IndexColumns=2
        \def\theindex{\@restonecoltrue
          \columnseprule \z@  \columnsep 29\p@
          \twocolumn[\index@prologue]%
          \parindent -30pt
          \columnsep 15pt
          \parskip 0pt plus 1pt
          \leftskip 30pt
          \rightskip 0pt plus 2cm
          \small
          \def\@idxitem{\par}%
          \let\item\@idxitem \ignorespaces}
        \def\endtheindex{\onecolumn}
        \def\noindexing{\let\index=\@gobble}



        \newcommand\symarrow[1]{
          \index{#1@\protect\texttt{#1} arrow tip}%
          \index{Arrow tips!#1@\protect\texttt{#1}}
          \texttt{#1}& yields thick  
          \begin{tikzpicture}[arrows={#1-#1},thick,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture} and thin
          \begin{tikzpicture}[arrows={#1-#1},thin,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture}
        }
        \newcommand\symarrowdouble[1]{
          \index{#1@\protect\texttt{#1} arrow tip}%
          \index{Arrow tips!#1@\protect\texttt{#1}}
          \texttt{#1}& yields thick  
          \begin{tikzpicture}[arrows={#1-#1},thick,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture}
          and thin
          \begin{tikzpicture}[arrows={#1-#1},thin,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture}, double 
          \begin{tikzpicture}[arrows={#1-#1},thick,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture} and 
          \begin{tikzpicture}[arrows={#1-#1},thin,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture}
        }

        \newcommand\sarrow[2]{
          \index{#1@\protect\texttt{#1} arrow tip}%
          \index{Arrow tips!#1@\protect\texttt{#1}}
          \index{#2@\protect\texttt{#2} arrow tip}%
          \index{Arrow tips!#2@\protect\texttt{#2}}
          \texttt{#1-#2}& yields thick  
          \begin{tikzpicture}[arrows={#1-#2},thick,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture} and thin
          \begin{tikzpicture}[arrows={#1-#2},thin,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture}
        }

        \newcommand\sarrowdouble[2]{
          \index{#1@\protect\texttt{#1} arrow tip}%
          \index{Arrow tips!#1@\protect\texttt{#1}}
          \index{#2@\protect\texttt{#2} arrow tip}%
          \index{Arrow tips!#2@\protect\texttt{#2}}
          \texttt{#1-#2}& yields thick  
          \begin{tikzpicture}[arrows={#1-#2},thick,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture} and thin
          \begin{tikzpicture}[arrows={#1-#2},thin,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture}, double 
          \begin{tikzpicture}[arrows={#1-#2},thick,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture} and 
          \begin{tikzpicture}[arrows={#1-#2},thin,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex);
            \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex);
          \end{tikzpicture}
        }

        \newcommand\carrow[1]{
          \index{#1@\protect\texttt{#1} arrow tip}%
          \index{Arrow tips!#1@\protect\texttt{#1}}
          \texttt{#1}& yields for line width 1ex
          \begin{tikzpicture}[arrows={#1-#1},line width=1ex,baseline]
            \useasboundingbox (0pt,-0.5ex) rectangle (1.5cm,2ex);
            \draw (0pt,.5ex) -- (1.5cm,.5ex);
          \end{tikzpicture}
        }
        \def\myvbar{\char`\|}
        \newcommand\plotmarkentry[1]{%
          \index{#1@\protect\texttt{#1} plot mark}%
          \index{Plot marks!#1@\protect\texttt{#1}}
          \texttt{\char`\\pgfuseplotmark\char`\{\declare{#1}\char`\}} &
          \tikz\draw[color=black!25] plot[mark=#1,mark options={fill=examplefill,draw=black}] coordinates{(0,0) (.5,0.2) (1,0) (1.5,0.2)};\\
        }
        \newcommand\plotmarkentrytikz[1]{%
          \index{#1@\protect\texttt{#1} plot mark}%
          \index{Plot marks!#1@\protect\texttt{#1}}
          \texttt{mark=\declare{#1}} & \tikz\draw[color=black!25]
          plot[mark=#1,mark options={fill=examplefill,draw=black}] 
          coordinates {(0,0) (.5,0.2) (1,0) (1.5,0.2)};\\
        }



        \ifx\scantokens\@undefined
        \PackageError{pgfmanual-macros}{You need to use extended latex
          (elatex) or (pdfelatex) to process this document}{}
        \fi

        \begingroup
        \catcode`|=0%|
        \catcode`[= 1
        \catcode`]=2
        \catcode`\{=12
        \catcode `\}=12
        \catcode`\\=12 |gdef|find@example#1\end{codeexample}[|endofcodeexample[#1]]
        |endgroup

        % define \returntospace.
        % 
        % It should define NEWLINE as {}, spaces and tabs as \space.
        \begingroup
        \catcode`\^=7
        \catcode`\^^M=13
        \catcode`\^^I=13
        \catcode`\ =13%
        \gdef\returntospace{\catcode`\ =13\def {\space}\catcode`\^^I=13\def^^I{\space}}
        \gdef\showreturn{\show^^M}
        \endgroup

        \begingroup
        \catcode`\%=13
        \catcode`\^^M=13
        \gdef\commenthandler{\catcode`\%=13\def%{\@gobble@till@return}}
          \gdef\@gobble@till@return#1^^M{}
          \gdef\@gobble@till@return@ignore#1^^M{\ignorespaces}
          \gdef\typesetcomment{\catcode`\%=13\def%{\@typeset@till@return}}
            \gdef\@typeset@till@return#1^^M{{\def%{\char`\%}\textsl{\char`\%#1}}\par}
                \endgroup

        % Define tab-implementation functions
        % \codeexample@tabinit@replacementchars@
        % and
        % \codeexample@tabinit@catcode@
        % 
        % They should ONLY be used in case that tab replacement is active.
        % 
        % This here is merely a preparation step.
        % 
        % Idea:
        % \codeexample@tabinit@catcode@ will make TAB active
        % and
        % \codeexample@tabinit@replacementchars@ will insert as many spaces as
        % /codeexample/tabsize contains.
        {
          \catcode`\^^I=13
          % ATTENTION: do NOT use tabs in these definitions!!
          \gdef\codeexample@tabinit@replacementchars@{%
            \begingroup
            \count0=\pgfkeysvalueof{/codeexample/tabsize}\relax
            \toks0={}%
            \loop
            \ifnum\count0>0
            \advance\count0 by-1
            \toks0=\expandafter{\the\toks0\ }%
            \repeat
            \xdef\codeexample@tabinit@replacementchars@@{\the\toks0}%
            \endgroup
            \let^^I=\codeexample@tabinit@replacementchars@@
          }%
          \gdef\codeexample@tabinit@catcode@{\catcode`\^^I=13}%
        }%

        % Called after any options have been set. It assigns
        % \codeexample@tabinit@catcode
        % and
        % \codeexample@tabinit@replacementchars
        % which are used inside of 
        % \begin{codeexample}
        %   ...
        % \end{codeexample}
        % 
        % \codeexample@tabinit@catcode  is either \relax or it makes tab
        % active.
        % 
        % \codeexample@tabinit@replacementchars is either \relax or it inserts
        % a proper replacement sequence for tabs (as many spaces as
        % configured)
        \def\codeexample@tabinit{%
          \ifnum\pgfkeysvalueof{/codeexample/tabsize}=0\relax
          \let\codeexample@tabinit@replacementchars=\relax
          \let\codeexample@tabinit@catcode=\relax
          \else
          \let\codeexample@tabinit@catcode=\codeexample@tabinit@catcode@
          \let\codeexample@tabinit@replacementchars=\codeexample@tabinit@replacementchars@
          \fi
        }

        \pgfqkeys{/codeexample}{%
          width/.code=	{\setlength\codeexamplewidth{#1}},
          graphic/.code=	{\colorlet{graphicbackground}{#1}},
          code/.code=	{\colorlet{codebackground}{#1}},
          execute code/.is if=code@execute,
          code only/.code=	{\code@executefalse},
          pre/.store in=\code@pre,
          post/.store in=\code@post,
          % #1 is the *complete* environment contents as it shall be
          % typeset. In particular, the catcodes are NOT the normal ones.
          typeset listing/.code=	{#1},
          render instead/.store in=\code@render,
          vbox/.code=	{\def\code@pre{\vbox\bgroup\setlength{\hsize}{\linewidth-6pt}}\def\code@post{\egroup}},
          ignorespaces/.code=	{\let\@gobble@till@return=\@gobble@till@return@ignore},
          leave comments/.code=	{\def\code@catcode@hook{\catcode`\%=12}\let\commenthandler=\relax\let\typesetcomment=\relax},
          tabsize/.initial=0,% FIXME : this here is merely used for indentation. It is just a TAB REPLACEMENT.
          every codeexample/.style={width=4cm+7pt},
        }

        \let\code@pre\pgfutil@empty
        \let\code@post\pgfutil@empty
        \let\code@render\pgfutil@empty
        \def\code@catcode@hook{}

        \newdimen\codeexamplewidth
        \newif\ifcode@execute
        \newbox\codeexamplebox
        \def\codeexample[#1]{%
          \begingroup%
          \code@executetrue
          \pgfqkeys{/codeexample}{every codeexample,#1}%
          \codeexample@tabinit% assigns \codeexample@tabinit@[catcode,replacementchars]
          \parindent0pt
          \begingroup%
          \par%
          \medskip%
          \let\do\@makeother%
          \dospecials%
          \obeylines%
          \@vobeyspaces%
          \catcode`\%=13%
          \catcode`\^^M=13%
          \code@catcode@hook%
          \codeexample@tabinit@catcode
          \relax%
          \find@example}
        \def\endofcodeexample#1{%
          \endgroup%
          \ifcode@execute%
          \setbox\codeexamplebox=\hbox{%
            \ifx\code@render\pgfutil@empty%
            {%
              {%
                \returntospace%
                \commenthandler%
                \xdef\code@temp{#1}% removes returns and comments
              }%
              \catcode`\^^M=9%
              \colorbox{graphicbackground}{\color{black}\ignorespaces%
                \code@pre\expandafter\scantokens\expandafter{\code@temp\ignorespaces}\code@post\ignorespaces}%
            }%
            \else%
            \colorbox{graphicbackground}{\color{black}\ignorespaces%
              \code@render}%
            \fi%
          }%
          \ifdim\wd\codeexamplebox>\codeexamplewidth%
          \def\code@start{\par}%
          \def\code@flushstart{}\def\code@flushend{}%
          \def\code@mid{\parskip2pt\par\noindent}%
          \def\code@width{\linewidth-6pt}%
          \def\code@end{}%
          \else%
          \def\code@start{%
            \linewidth=\textwidth%
            \parshape \@ne 0pt \linewidth
            \leavevmode%
            \hbox\bgroup}%
          \def\code@flushstart{\hfill}%
          \def\code@flushend{\hbox{}}%
          \def\code@mid{\hskip6pt}%
          \def\code@width{\linewidth-12pt-\codeexamplewidth}%
          \def\code@end{\egroup}%
          \fi%
          \code@start%
          \noindent%
          \begin{minipage}[t]{\codeexamplewidth}\raggedright
            \hrule width0pt%
            \footnotesize\vskip-1em%
            \code@flushstart\box\codeexamplebox\code@flushend%
            \vskip-1ex
            \leavevmode%
          \end{minipage}%
          \else%
          \def\code@mid{\par}
          \def\code@width{\linewidth-6pt}
          \def\code@end{}
          \fi%
          \code@mid%  
          \colorbox{codebackground}{%
            \begin{minipage}[t]{\code@width}%
              {%
                \let\do\@makeother
                \dospecials
                \frenchspacing\@vobeyspaces
                \normalfont\ttfamily\footnotesize
                \typesetcomment%
                \codeexample@tabinit@replacementchars
                \@tempswafalse
                \def\par{%
                  \if@tempswa
                  \leavevmode \null \@@par\penalty\interlinepenalty
                  \else
                  \@tempswatrue
                  \ifhmode\@@par\penalty\interlinepenalty\fi
                  \fi}%
                \obeylines
                \everypar \expandafter{\the\everypar \unpenalty}%
                \pgfkeysvalueof{/codeexample/typeset listing/.@cmd}{#1}\pgfeov
              }
            \end{minipage}}%
          \code@end%
          \par%
          \medskip
        \end{codeexample}
      }

      \def\endcodeexample{\endgroup}


      \makeatother

      \usepackage{pgfmanual}

      \makeatletter
      % \pgfautoxrefs will be defined by 'make dist'
      \pgfutil@ifundefined{pgfautoxrefs}{%
	\def\pgfmanualpdflabel#1#2{#2}% NO-OP
	\def\pgfmanualpdfref#1#2{#2}%
	\pgfkeys{
          /pdflinks/codeexample links=false,% DISABLED.
	}%
      }{}
      \makeatother


      \makeatletter
      \renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.8em}}
      \renewcommand*\l@subsubsection{\@dottedtocline{3}{4.3em}{3.2em}}
      \makeatother

      % \includeonly{pgfmanual-en-library-profiler}

      % Global styles:
      \tikzset{
        every plot/.style={prefix=plots/pgf-},
        shape example/.style={
          color=black!30,
          draw,
          fill=yellow!30,
          line width=.5cm,
          inner xsep=2.5cm,
          inner ysep=0.5cm}
      }

\usepackage{iftex,tikz-cd,xr}
\ifLuaTeX
  \usepackage{fontspec}
\else
  \usepackage[utf8]{inputenc}
\fi

\hypersetup{unicode,
            pdftitle={The tikz-cd package},
            pdfauthor={Florêncio Neves},
            pdfkeywords={commutative diagrams, latex, tikz, pgf},
            colorlinks,
           }

\externaldocument[pgfman-]{pgfmanual}
           
\title{The \texttt{tikz-cd} package}
\author{Florêncio Neves\footnote{\emph{E-mail:} \href{mailto:florencioneves@gmail.com}{\texttt{florencioneves@gmail.com}}}}
\date{Version 0.3c, of December 30, 2012}

\tikzset{commutative diagrams/background color=graphicbackground}

\newcommand{\displayarrow}[2][]{\texttt{#2} & yields \tikz[baseline=-2.5pt] \draw[#2-#2, line width=0.0929ex, #1] (0,0) -- (1,0);}
\newcommand{\displayarrowstyle}[2][]{\texttt{#2} #1 & yields
  \tikz[baseline=-tikzcdaxis, line width=tikzcdrule] \draw[commutative diagrams/.cd, #2] (0,0) -- (0.6,0);}

\usepackage{microtype,ellipsis}

\begin{document}
\maketitle

The general-purpose drawing package Ti\emph{k}Z can be used to typeset
commutative diagrams and other kinds of mathematical pictures,
generating high-quality results (see for example \cite{lenders} or
\cite{milne}).  The present package facilitates the creation of such diagrams
by providing a convenient set of macros and reasonable default
settings.  Familiarity with Ti\emph{k}Z is helpful but not necessary,
since the examples contained here cover the most common situations.

This package also includes an arrow tip library closely matching the
Computer Modern arrow tips.

\tableofcontents

\section{Basic usage}
\label{sec:basic-usage}

Commutative diagrams are created with the |tikzcd| environment.  Its
content describes a matrix, similarly to the |\matrix| command in
\tikzname{} or the |align| environment in \LaTeX.  Everything is
typeset in math mode, but you will probably want use \texttt{tikzcd}
inside |\[| \dots\ |\]| or an \texttt{equation} environment, so that
the diagram is placed on a new line and centered.

% Diagrams will not be displayed correctly in the \textsc{dvi} file.  It
% is necessary to convert it to \textsc{pdf} or \textsc{ps} format---or,
% even better, use \texttt{pdflatex} to obtain a \textsc{pdf} file
% directly.

\subsection{Inserting arrows}
\label{sec:inserting-arrows}

Inside the |tikzcd| environment, the command |\arrow| is provided to
produce arrows.  In its simplest form, it takes one argument, a string
containing the characters |r|, |l|, |u| or |d|, standing for right, left,
up and down, that determine the arrow target.  A label can be
placed on an arrow by providing a second argument.
\begin{codeexample}[]
  \begin{tikzcd}
    A \arrow{rd} \arrow{r}{\phi} & B \\
                                 & C
  \end{tikzcd}
\end{codeexample}

You can control the appearance of the arrow by placing an argument
in square braces before the direction parameter.  It may contain
any option that can be passed to \tikzname{}'s
|\path| command.  Similarly, a label can be modified by an argument in
square braces right before it.  It may contain anything that can be
passed to \tikzname's |node| operator.
\begin{codeexample}[]
\begin{tikzcd}
  A \arrow{r}{\psi} \arrow[color=red]{d}
    & B \arrow{d}[color=red]{\psi} \\
  C \arrow[color=red]{r}[color=blue]{\eta}
    & D
\end{tikzcd}
\end{codeexample}

Arrows can actually have an arbitrary number of labels, each one
specified by juxtaposing |{|\meta{text}|}| or
|[|\meta{options}|]{|\meta{text}|}| to the |\arrow| command.

\begin{codeexample}[]
\begin{tikzcd}
  A \arrow{r}[near start]{\phi}[swap]{\psi}[near end]{\eta} & B    
\end{tikzcd}
\end{codeexample}

% If using \tikzname's \texttt{quotes} library, the above could be rewritten as follows:

% \usetikzlibrary{quotes}
% \begin{codeexample}[]
% \begin{tikzcd}
%   A \arrow["\phi" near start, "\psi"', "\eta" near end]{r} & B    
% \end{tikzcd}
% \end{codeexample}

To save typing, the command |\ar| is provided as a shorthand to
|\arrow|.  There are also commands |\rar|, |\lar|, |\uar|, |\dar|,
|\urar|, |\ular|, |\drar| and |\dlar| that act like |\arrow{r}|,
|\arrow{l}|, \dots, |\arrow{dl}|.  They can take an optional
argument in square braces to modify the arrow, followed by label
specifiers of the form |{|\meta{text}|}| or
|[|\meta{options}|]{|\meta{text}|}|.
\begin{codeexample}[]
\begin{tikzcd}
  A \rar{\psi} \dar[color=red]
    & B \dar[][color=red]{\psi} \\
  C \rar[color=red][color=blue]{\eta} \urar[dashed]
    & D
\end{tikzcd}
\end{codeexample}

We provide one more example, reproduced from X\raisebox{-0.3ex}{Y}-pic
user's guide.

\begin{codeexample}[]
\begin{tikzcd}
  T
  \arrow[bend left]{drr}{x}
  \arrow[bend right]{ddr}{y}
  \arrow[dotted]{dr}[description]{(x,y)} & & \\
    & X \times_Z Y \arrow{r}{p} \arrow{d}{q}
      & X \arrow{d}{f} \\
    & Y \arrow{r}{g}
      & Z
\end{tikzcd}
\end{codeexample}

\subsection{Changing arrow tips}
\label{sec:changing-arrow-tips}

For some \LaTeX\ arrow-producing commands, there is a
corresponding option (without a ``|\|'') that can be passed to
|\arrow| to produce that kind of arrow.  Notice the use of
|hookrightarrow| and |dashrightarrow| in the example below.

\begin{codeexample}[]
  \begin{tikzcd}
    X \arrow[hookrightarrow]{r} \arrow[dashrightarrow]{rd}
      & \bar{X} \arrow{d}\\
      & Y
  \end{tikzcd}
\end{codeexample}

The following list shows all available arrows.

{\tikzset{commutative diagrams/.cd, background color=white}
  \begin{quote}
    \begin{tabular}{ll}
      \displayarrowstyle{rightarrow}\\
      \displayarrowstyle{leftarrow}\\
      \displayarrowstyle{leftrightarrow}\\
      \displayarrowstyle{dash}\\
      \displayarrowstyle{Rightarrow}\\
      \displayarrowstyle{Leftarrow}\\
      \displayarrowstyle{Leftrightarrow}\\
      \displayarrowstyle{equal}\\
      \displayarrowstyle[(or \texttt{maps to})]{mapsto}\\
      \displayarrowstyle{mapsfrom}\\
      \displayarrowstyle[(or \texttt{hook})]{hookrightarrow}\\
      \displayarrowstyle{hookleftarrow}\\
      \displayarrowstyle{rightharpoonup}\\
      \displayarrowstyle{rightharpoondown}\\
      \displayarrowstyle{leftharpoonup}\\
      \displayarrowstyle{leftharpoondown}\\
      \displayarrowstyle[(or \texttt{dashed})]{dashrightarrow}\\
      \displayarrowstyle{dashleftarrow}\\
      \displayarrowstyle[(or \texttt{tail})]{rightarrowtail}\\
      \displayarrowstyle{leftarrowtail}\\
      \displayarrowstyle[(or \texttt{two heads})]{twoheadrightarrow}\\
      \displayarrowstyle{twoheadleftarrow}\\
      \displayarrowstyle[(or \texttt{squiggly})]{rightsquigarrow}\\
      \displayarrowstyle{leftsquigarrow}\\
      \displayarrowstyle{leftrightsquigarrow}
    \end{tabular}
  \end{quote}
}

Some of the arrows above have an alternate name shown in parenthesis.
These forms behave a little differently from the original ones, in
that they can be superimposed with other arrows.

\begin{codeexample}[]
\begin{tikzcd}
  A \arrow[tail, two heads, dashed]{r} & B
\end{tikzcd}
\end{codeexample}

It is also possible to select arrow tips using \tikzname{}'s |arrow|
option directly (e.g., by saying |right hook->|).  However, the method
described here above is more appropriate, as it abstracts the choice
of an actual arrow tip design (see also the key \texttt{commutative
  diagrams/arrow style} below), and is arguably better from the
mnemonic standpoint.

\section{Controlling the appearance of diagrams}
\label{sec:chang-appe-diagr}

This section lists all customization keys defined by this package.
Options can be made take effect in different scopes:
\begin{enumerate}
\item Globally, using the command |\tikzset|.  This can be done in the
  document preamble, or in the body, to affect all diagrams
  appearing thereafter.
\item For a particular diagram, by placing options in the optional
  argument to the |tikzcd| environment.  Such options are applied to
  the |tikzpicture| environment generated by |tikzcd| (cf.\
  \S\ref{sec:intern-arrow-comm}).
\item For a particular arrow or label, by placing options in one of
  the optional arguments of |\arrow|.
\end{enumerate}
Of course, not all options make sense in all contexts.

All keys provided by this package are located in the path
|/tikz/commutative diagrams|.  Methods 2 and 3 above will search in
this path by default; if a key is not found there, an attempt is made
to find it in |/tikz|.  When using method 1, it is convenient to
change the default search path by using
\begin{quote}
  |\tikzset{commutative diagrams/.cd, |\meta{options}|}|.
\end{quote}

Besides the keys described in this manual, numerous \tikzname\
parameters can affect the appearance of a diagram.  However, only a
few of them (namely those appearing in \texttt{every diagram},
\texttt{every arrow} and \texttt{every label} below) are reinitialized
when |tikzcd| is called.  This means that modifying a certain
\tikzname\ parameter globally may or may not affect the output of
|tikzcd|.

\subsection{General options}
\label{sec:general-options}

\begin{stylekey}{/tikz/commutative diagrams/every diagram}
  This style is applied to every |tikzcd| environment.  Initially, it
  contains the following:
\begin{quote}\ttfamily{}
/tikz/commutative diagrams/.cd,\\
|/tikz/cells={nodes={shape={asymmetrical rectangle}}}|,\\
/tikz/baseline=0pt,\\
row sep=normal,\\
column sep=normal
\end{quote}
\end{stylekey}

The |baseline=0pt| setting is used to make equation numbers be placed
correctly.  The \texttt{asymmetrical rectangle} shape, used in the
matrix nodes, is described in \S\ref{sec:asymm-rect-shape}.

\begin{key}{/tikz/commutative diagrams/diagrams=\meta{options}}
  This key appends \meta{options} to the style
  |/tikz/commutative diagrams/every diagram|.
\end{key}

\begin{key}{/tikz/commutative diagrams/row sep=\meta{size} (initially normal)}
  This key acts as a ``frontend'' to \tikzname's |/tikz/row sep| key.  If
  the key
  \begin{quote}
    |/tikz/commutative diagrams/row sep/|\meta{size}
  \end{quote}
stores a
  \meta{value}, then it is read and |/tikz/row sep|=\meta{value} is
  set.  If the key above is not initialized, then \meta{size} is
  presumably a dimension, and |/tikz/row sep|=\meta{size} is set.

  The initially available \meta{size}'s, and their values, are
  the following:
  \begin{center}
    \begin{tabular}{cccccc}
      |tiny| & |small| & |scriptsize| & |normal| & |large| & |huge| \\
      1.25\,ex & 2.5\,ex   & 3.75\,ex       & 5\,ex      & 7.5\,ex   & 10\,ex
    \end{tabular}
  \end{center}
\end{key}

Notice that setting, say, |row sep=1cm| globally with |\tikzset| will
have no effect, since the |row sep| option is re-set at the beginning
of each diagram.  To make all diagrams have |row sep| equal to 1\,cm,
you can modify the meaning of |normal| by saying
\begin{quote}
|\tikzset{commutative diagrams/row sep/normal=1cm}|.
\end{quote}
You can also create new sizes, but \pgfname\ requires new keys to be
initialized explicitly.  For example, to create a size |my size|,
meaning 1\,ex, you should use
\begin{quote}
|\tikzset{commutative diagrams/row sep/my size/.initial=1ex}|.
\end{quote}

\begin{key}{/tikz/commutative diagrams/column sep=\meta{size} (initially normal)}
  This works analogously to the |row sep| key above.  The sizes available
  initially are the following:
  \begin{center}
    \begin{tabular}{cccccc}
      |tiny| & |small| & |scriptsize| & |normal| & |large| & |huge| \\
      1.5\,ex & 3\,ex   & 4.5\,ex       & 6\,ex      & 9\,ex   & 12\,ex
    \end{tabular}
  \end{center}
\end{key}

In the examples below, the triangular diagrams would look too wide or
too tall if the column or row separation were not set appropriately.

\begin{codeexample}[]
\begin{tikzcd}[column sep=small]
               & A \arrow{dl}\arrow{dr} & \\
  B \arrow{rr} &                        & C 
\end{tikzcd}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzcd}[row sep=tiny]
                         & B \arrow{dd} \\
  A \arrow{ur}\arrow{dr} &              \\
                         & C
\end{tikzcd}
\end{codeexample}

Section \ref*{pgfman-section-matrices}.3.2 of the \pgfname{} manual
\cite{pgfman} contains further details on the spacing of matrix cells.

\begin{key}{/tikz/commutative diagrams/math mode=\meta{boolean}
    (initially true)}
  This keys determines whether the contents of a diagram are typeset in
  math mode or not.  If set globally or diagram-wise, it affects both
  the diagram entries and arrow labels.  If used with |\arrow|, it affects
  only its labels.
\end{key}

\begin{key}{/tikz/commutative diagrams/background color=\meta{color} (initially white)}
  This key stores the name of a color, and is read by 
  styles that fill the background, such as |description| and |crossing over|.
  It does not cause the background of diagrams to be filled.
\end{key}

\subsection{Options for arrows}
\label{sec:options-arrows}

Besides the options and styles provided by this package, several keys
defined by \tikzname{} are useful for arrows, such as |dashed|,
|dotted|, and its relatives, |line width=|\meta{dimension},
|color=|\meta{color}, |bend right|, |bend left|, |in=|\meta{angle},
|out=|\meta{angle}, |loop|, etc.  See the \pgfname{}
manual~\cite[\S\ref*{pgfman-section-cap-joins} and
\S\ref*{pgfman-library-to-paths}]{pgfman}.

\begin{stylekey}{/tikz/commutative diagrams/every arrow}
  This style is applied to every |\arrow|.  Initially, it contains the
  following:
\begin{quote}\ttfamily{}
/tikz/commutative diagrams/.cd,\\
/tikz/draw,\\
default arrow
\end{quote}
\end{stylekey}

The |default arrow| style is similar to |rightarrow|, but may perform
some additional tasks, such as setting the line width.

\begin{key}{/tikz/commutative diagrams/arrows=\meta{options}}
  This key appends \meta{options} to the style
  |/tikz/commutative diagrams/every arrow|.
\end{key}

\begin{key}{/tikz/commutative diagrams/arrow style=\meta{style} (initially computer
    modern)}
  Setting this key causes the several arrow-tip-specifying styles
  listed in \S\ref{sec:changing-arrow-tips} to be redefined.  In
  particular, it makes the style \texttt{/tikz/commutative
    diagrams/default arrow}, which is automatically applied to every
  arrow, to be redefined.  Currently, \meta{style} can be one of
  the following:
  \begin{description}
  \item[|computer modern|] This is the initial setting and is suitable
    for documents using Computer Modern or Latin Modern fonts.
  \item[|tikz|] This style uses the arrow tips defined in \tikzname's
    |arrows| library (which has to be loaded before setting this
    option).  It honors the option |/tikz/>|, and it keeps the
    parameter \texttt{/tikz/line width} untouched.
  \end{description}
\end{key}

If you are using a font different from Computer Modern, you may find
better results by selecting the |tikz| arrow style, setting |/tikz/>|
to the value that best matches your font (among those shown in
\cite[\S\ref*{pgfman-section-library-arrows}]{pgfman}), and adjusting |/tikz/line width| if necessary.
The following example, if not particularly elegant, should be
instructive.

\begin{codeexample}[]
\usetikzlibrary{arrows}

\tikzset{
  commutative diagrams/.cd,
  arrow style=tikz,
  diagrams={>=open triangle 45, line width=tikzcdrule}}
  
\begin{tikzcd}
  A \arrow{r} \arrow{d} & B \arrow{d}\\
  C \arrow{r}           & D
\end{tikzcd}
\end{codeexample}

The following set of options allow fine-tuning the placement of
arrows.

\begin{key}{/tikz/commutative diagrams/shift={\ttfamily\char`\{}\meta{coordinate}{\ttfamily\char`\}}}
  Shifts arrows by \meta{coordinate}.
\end{key}

\begin{key}{/tikz/commutative diagrams/xshift=\meta{dimension}}
  Shifts arrows right by \meta{dimension}.
\end{key}

\begin{key}{/tikz/commutative diagrams/yshift=\meta{dimension}}
  Shifts arrows up by \meta{dimension}.
\end{key}

\begin{codeexample}[]
  \begin{tikzcd}
    A \arrow[yshift=0.7ex]{r} \arrow[yshift=-0.7ex]{r}
      & B \arrow[xshift=0.7ex]{d} \arrow[xshift=-0.7ex]{d} \\
      & C
  \end{tikzcd}
\end{codeexample}

\begin{key}{/tikz/commutative diagrams/shift left=\meta{dimension}}
  Shifts arrows by \meta{dimension} in the direction making a $90^\circ$
  angle with the arrow.
\end{key}

\begin{key}{/tikz/commutative diagrams/shift right=\meta{dimension}}
  Shifts arrows by \meta{dimension} in the direction making a $-90^\circ$
  angle with the arrow.
\end{key}

\begin{codeexample}[]
  \begin{tikzcd}
    A \arrow[red, shift left=1.5ex]{r} \arrow{r}
      \arrow[blue, shift right=1.5ex]{dr} \arrow{dr}
      & B \arrow[purple, shift left=1.5ex]{d} \arrow{d}\\
      & C
  \end{tikzcd}
\end{codeexample}

\begin{key}{/tikz/commutative diagrams/start anchor=\opt{{\ttfamily\char`\{}\ooarg{coordinate transformations}}\meta{anchor}\opt{\ttfamily\char`\}}}
  This key specifies at which anchor of the current node the arrow
  should start.  Optionally, additional coordinate transformations can
  be supplied.  An empty argument causes no anchor to be specified.
\end{key}

\begin{key}{/tikz/commutative diagrams/end anchor=\opt{{\ttfamily\char`\{}\ooarg{coordinate transformations}}\meta{anchor}\opt{\ttfamily\char`\}}}
  This key works analogously, but refers to the target node of the arrow.
\end{key}

See the picture on \S\ref{sec:asymm-rect-shape} for some of the
possible values for \meta{anchor}.
\begin{codeexample}[]
\begin{tikzcd}[cells={nodes={draw=gray}}]
  A \arrow[black]{r}
    \arrow[blue, end anchor=north east]{r}
    \arrow[red,
           start anchor={[xshift=-1ex]},
           end anchor={[yshift=2ex]north east}]{r}
    & B
\end{tikzcd}
\end{codeexample}

\begin{stylekey}{/tikz/commutative diagrams/crossing over}
  This style makes a thicker line, with color
  |/tikz/commutative diagrams/background color|, to be drawn under the
  current arrow, simulating the effect of its passing over other
  arrows.

\begin{codeexample}[]
\begin{tikzcd}
  A \arrow{dr} & B \arrow[crossing over]{dl} \\
  C            & D
\end{tikzcd}
\end{codeexample}
\end{stylekey}

Note that, since arrows are drawn in the order they are read, some
arrows may need to run ``backwards'' to achieve the desired result.
%The option \texttt{on background layer}
%\cite[\S\ref*{pgfman-section-tikz-backgrounds}]{pgfman} may also
%be useful in this context.
The following picture, adapted from
\cite{lenders}, illustrates the use of \texttt{crossing over}.

\begin{codeexample}[]
\begin{tikzcd}[row sep=scriptsize, column sep=scriptsize]
  & f^* E_V \arrow{dl}\arrow{rr}\arrow{dd} & & E_V \arrow{dl}\arrow{dd} \\
  f^* E \arrow[crossing over]{rr}\arrow{dd} & & E \\
  & U \arrow{dl}\arrow{rr} &  & V \arrow{dl} \\
  M \arrow{rr} & & N\arrow[crossing over, leftarrow]{uu}\\
\end{tikzcd}
\end{codeexample}
  
\begin{key}{/tikz/commutative diagram/crossing over clearance=\meta{dimension}
    (initially 1.5ex)}
  This key specifies the width of the background-colored line drawn
  under a |crossing over| arrow.
\end{key}

\subsection{Options for labels}
\label{sec:options-labels}

Besides the options provided by this package and listed below, there
are many options provided by \tikzname{} that are useful for
labels, such as  |above|, |below|, |left|,
|right|, |swap| (which makes the label be placed in the opposite side
to the default), |sloped|, |pos=|\meta{fraction}, |near start|,
|near end|, |inner sep=|\meta{dimension}, |font=|\meta{font
  command}, |text width=|\meta{dimension}, etc.  See the \pgfname{}
manual~\cite[\S\ref*{pgfman-section-nodes}, esp.\ \S\ref*{pgfman-section-pos-option}]{pgfman}.

\begin{stylekey}{/tikz/commutative diagrams/every label}
  This style is applied to every label produced with |\arrow|.  It is initially set
  to

\begin{quote}\ttfamily{}
/tikz/commutative diagrams/.cd,\\
/tikz/auto,\\
/tikz/font=\meta{\rmfamily something},\\
/tikz/inner sep=0.5ex
\end{quote}
where \meta{something} is something that makes |\scriptstyle| be
applied to labels in math mode.
\end{stylekey}

The key |/tikz/auto| makes the label be placed to the left of the
arrow, considering ``front'' as the direction the arrow points at.
The key |/tikz/inner sep| controls the distance between a label and
the corresponding arrow.

\begin{key}{/tikz/commutative diagrams/labels=\meta{options}}
  This key appends \meta{options} to the style
  \texttt{/tikz/commutative diagrams/every label}.
\end{key}

\begin{stylekey}{/tikz/commutative diagrams/description}
  This style causes the label to be placed over the arrow, with the
  background filled.  The clearance around the label is determined by
  \texttt{/tikz/inner sep}.

\begin{codeexample}[]
\begin{tikzcd}
  A \arrow{r}[description]{\phi} & B
\end{tikzcd}
\end{codeexample}
\end{stylekey}

\section{Advanced usage}
\label{sec:advanced-usage}

This section provides further details on the functioning of this
package, with the aim of showing how a more or less arbitrary
interaction with other \tikzname{} features is possible.

\subsection{Internals of \texttt{tikzcd} and the arrow commands}
\label{sec:intern-arrow-comm}

The |tikzcd| environment works by substituting code of the form
\begin{quote}
  |\begin{tikzcd}[|\meta{options}|]|
    \meta{contents}
  |\end{tikzcd}|
\end{quote}
with roughly the following:
\begin{quote}
  |\begin{tikzpicture}[commutative diagrams/every diagram,|
    \meta{options}|]|\\
  |  \matrix[matrix of |[|math|]| nodes] {|\\
  |    |\meta{contents} |\\|\\
  |  };|\\
  |  |\meta{paths}\\
  |\end{tikzpicture}|
\end{quote}

Not shown above are a number of initialization procedures, such as
defining |\arrow| and its relatives.  Note that the next-row command
|\\| for the last row is inserted by |tikzcd|, and therefore does not
need to be present in \meta{contents}.  The |\matrix| is supplied the
option \texttt{matrix of nodes} or \texttt{matrix of math nodes} as
specified by the option \texttt{commutative diagrams/math mode}.
Notice also that you can use the key |execute at end picuture| in
\meta{options} to have arbitrary \tikzname{} code executed after a
diagram is drawn.

Initially, \meta{paths} is empty.  The command
|\arrow[|\meta{path options}|]{|\meta{direction}|}| does nothing at the
point it is inserted, and causes the following code to be appended to
\meta{paths}:
\begin{quote}
  |\path[commutative diagrams/every arrow, |\meta{path options}|]|\\
  |     (| \meta{current node}|) to |\meta{labels}| (|\meta{target~node}|);|
\end{quote}

Here, \meta{current node} is the node corresponding to the matrix cell
where the command |\arrow| is present, and \meta{target node} is determined by
\meta{direction} as explained in \S\ref{sec:inserting-arrows}.

Initially, \meta{labels} is the empty string.  A label specifier of
the form |{|\meta{label text}|}| or |[|\meta{label
  options}|]{|\meta{label text}|}| immediately following the
\meta{direction} argument or a previous label specifier causes the
string
\begin{quote}
  |node [commutative diagrams/every label, |\meta{label options}|] {|[|$|]\meta{label text}[|$|]|}|
\end{quote}
to be appended to \meta{labels}.  Dollars signs surround \meta{label
  text} depending on the setting \texttt{commutative diagrams/math
  mode}.

The abbreviated forms |\rar|, |\dar|, \dots, have entirely analogous
effect.

\subsection{Tweaking \texttt{to} paths}
\label{sec:tweaking-to-paths}

Recall that the |to| path operation used in the paths created by
|\arrow| can take a number of options, as described in 
\S\ref*{pgfman-library-to-paths} of the \pgfname{} manual~\cite{pgfman}.  In particular, the
key |/tikz/to path| determines the path that is actually drawn, and
can be used to do all sorts of fiddling.

\begin{codeexample}[]
\begin{tikzcd}
  A \arrow[controls={+(1.5,0.5) and +(-1,0.8)}]{dr}
    \arrow[dashed, to path=|- (\tikztotarget)]{dr}
    & \\
    & B \arrow[loop right]{}
\end{tikzcd}
\end{codeexample}

The following example shows how to produce a ``snake'' map.  The arrow
with |draw=none| goes from $B$ to $E$, and its only purpose is to
create a coordinate, named |Z|, lying halfway between these two cells.
The arrow starting at $C$ has target $D$, so the macros |\tikztostart|
and |\tikztotarget| will expand to the nodes corresponding to these
two cells in the argument of |to path|.  Notice also the use of
|\tikztonodes| at the point where we want the label to be inserted.
\begin{codeexample}[]
\begin{tikzcd}
  A \arrow{r}
    & B \arrow{r}
        \arrow[draw=none]{d}[name=Z, shape=coordinate]{}
    & C \arrow[rounded corners,
               to path={ -- ([xshift=2ex]\tikztostart.east)
                         |- (Z) [near end]\tikztonodes
                         -| ([xshift=-2ex]\tikztotarget.west)
                         -- (\tikztotarget)}]
              {dll}{\delta} \\
  D \arrow{r}
    & E \arrow{r}
      & F
\end{tikzcd}
\end{codeexample}

In the next examples, empty labels are used to create nodes for later
reference, and the |to path| key is used in a way that, in the
terminology of the previous section, \meta{current node} and/or
\meta{target node} are completely ignored.
\begin{codeexample}[]
\begin{tikzcd}
  A \arrow{d} \arrow[bend left]{dr}[name=U,below]{}\\
  B \arrow{r} \arrow[Rightarrow,to path=-- (U) \tikztonodes]{}{\psi} & C
\end{tikzcd}
\end{codeexample}
\begin{codeexample}[]
\begin{tikzcd}
  A \arrow[bend left=50]{r}[name=U,below]{}
    \arrow[bend right=50]{r}[name=D]{}
    & B
  \arrow[Rightarrow,to path=(U) -- (D)]{}
\end{tikzcd}
\end{codeexample}

\subsection{Drawing diagrams directly with Ti\emph{k}Z}
\label{sec:draw-diagr-directly}

If the tools provided by this package prove not flexible enough for
some application, you can use the methods described in \cite{lenders}
and \cite{milne} to draw diagrams directly with \tikzname.  In this
case, you can still use the styles provided here in order to achieve
uniformity with diagrams drawn with |tikzcd|.  The pictures below show
how this can be done (the second one is adapted from \cite{milne}).

\begin{codeexample}[]
\begin{tikzpicture}[commutative diagrams/every diagram]
  \matrix[matrix of math nodes, name=m] {
    X & \bar X \\
      & Y      \\};
  \path[commutative diagrams/.cd, every arrow, every label]
    (m-1-1) edge[commutative diagrams/hook] (m-1-2)
            edge[commutative diagrams/dashed] (m-2-2)
    (m-1-2) edge (m-2-2);
\end{tikzpicture}
\end{codeexample}


\begin{codeexample}[]
\begin{tikzpicture}[commutative diagrams/every diagram]
  \node (P0) at (90:2.8cm) {$X\otimes (Y\otimes (Z\otimes T))$};
  \node (P1) at (90+72:2.5cm) {$X\otimes ((Y\otimes Z)\otimes T))$} ;
  \node (P2) at (90+2*72:2.5cm) {\makebox[5ex][r]{$(X\otimes (Y\otimes Z))\otimes T$}};
  \node (P3) at (90+3*72:2.5cm) {\makebox[5ex][l]{$((X\otimes Y)\otimes Z)\otimes T$}};
  \node (P4) at (90+4*72:2.5cm) {$(X\otimes Y)\otimes (Z\otimes T)$};

  \path[commutative diagrams/.cd, every arrow, every label]
    (P0) edge node[swap] {$1\otimes\phi$} (P1)
    (P1) edge node[swap] {$\phi$} (P2)
    (P2) edge node {$\phi\otimes 1$} (P3)
    (P4) edge node {$\phi$} (P3)
    (P0) edge node {$\phi$} (P4);
\end{tikzpicture}
\end{codeexample}

\subsection{Issues with active ampersand}
\label{sec:issues-with-active-ampersand}

By default, \tikzname{} makes the character |&| active inside
matrices, and this causes the error message
\begin{quote}
  |! Package pgfbasematrix Error: Single ampersand used with wrong catcode.|
\end{quote}
when |tikzcd| is used inside the argument to a macro such as a Beamer
frame or a footnote.  One solution to this problem is to call |tikzcd|
with the option |ampersand replacement=\&|, and replace all
occurrences of |&| with |\&| in the diagram.

\section{Additional goodies}
\label{sec:general-infra}

This package provides some general \pgfname\ infrastructure to meet its ends,
as described in this section.

\subsection{The \texttt{asymmetrical rectangle} shape}
\label{sec:asymm-rect-shape}

The \texttt{asymmetrical rectangle} shape is similar to the
\texttt{rectangle} shape, except that the \texttt{center} anchor is
not located at its geometric center, but rather right above the
\texttt{base} anchor, at a distance that can be specified by the
following key.

\begin{key}{/tikz/commutative diagrams/center yshift=\meta{dimension}
    (initially tikzcdaxis)}
\end{key}

The picture below shows some of the available anchors.  All anchors
provided by \texttt{rectangle} are available and behave exactly the
same, except for \texttt{center}, \texttt{west}, \texttt{east}, and
the numerical anchors.  The anchors \texttt{real center}, \texttt{real
  west} and \texttt{real east} agree with \texttt{rectangle}'s
\texttt{center}, \texttt{west} and \texttt{east}.

\begin{center}\Huge
  \begin{tikzpicture}
    \node[name=s,shape=asymmetrical rectangle,shape example]
    {Asymmetrical rectangle\vrule width 1pt height 2cm}; \foreach
    \anchor/\placement in {north west/above left, north/above, north
      east/above right, west/left, center/right, east/right, real
      west/left, real center/right, real east/right, base west/left,
      base/right, base east/right, south west/below left, south/below,
      south east/below right, text/left, 10/right, 130/above,
      230/below, -10/below} \draw[shift=(s.\anchor)] plot[mark=x]
    coordinates{(0,0)} node[\placement] {\scriptsize\texttt{\anchor}};
  \end{tikzpicture}
\end{center}

This shape is used in \texttt{tikzcd}'s matrix cells to ensure arrows
between nodes in the same row are drawn horizontally.  When
\tikzname{} draws a path between two nodes, it chooses endpoints lying
on their borders in such a way that the path points towards the
\texttt{center} of the nodes.  With the \texttt{rectangle} shape, the
anchor \texttt{center} lies halfway between two nonadjacent vertices
and therefore its position depends on the height and depth of the
text, potentially causing slanted lines to be draw.  The picture
above, for instance, has a humongous ascender (namely, the rule after
the word ``rectangle''), so its \texttt{real center} lies well above
its \texttt{center}.

\subsection{Reading font parameters}
\label{sec:read-font-param}

The following are |pgfmath| functions used to access relevant math
font parameters.  They take no arguments, but the result depends of
the currently selected font size.

\begin{math-function}{tikzcdaxis}
Returns the ``axis height'' parameter of the document's math font.
\end{math-function}

\begin{math-function}{tikzcdrule}
Returns the fraction rule thickness of the document's math font.
\end{math-function}

\subsection{Computer Modern arrow tips}
\label{sec:comp-modern-arrow}

The naming scheme of the Computer Modern-like arrow tips provided by
this package parallels that of \pgfname's |arrows| library, documented
in \S\ref*{pgfman-section-library-arrows} of the \pgfname{} manual~\cite{pgfman}.  To match the Computer Modern
typeface at size 10\,pt, line width should be set to 0.4\,pt; for
larger font sizes, scale this parameter accordingly, or use the value 0.0929\,ex.

Notice that by using the mechanism explained in
\S\ref{sec:changing-arrow-tips}, it is not necessary, and in fact not
advisable, to directly refer to the arrow tips listed in this section
when creating diagrams with |tikzcd|.

Incidentally, \tikzname's original |to| arrow tip seems to be based on
the pre-1992 version of Computer Modern which, in spite of its
author's wish \cite{knuth}, can still be found in many systems.
\TeX{}Live, for instance, distributed the old version up until 2007 or
2008.  Therefore, an up-to-date \TeX{} distribution may be necessary
to get matching arrows in formulas and diagrams.

\begin{description}
\item[Basic arrow tips]\ \\
\begin{tabular}{ll}
  \displayarrow{cm to}\\
  \displayarrow{cm to reversed}\\
  \displayarrow[line width=0.66pt]{cm bold to} (with a line 50\% thicker)\\
  \texttt{cm \char`\|} & yields \tikz[baseline=-2.5pt] \draw[cm |-cm |, line width=0.0929ex] (0,0) -- (1,0);\\
  \displayarrow{cm o}\\
  \displayarrow{cm *}\\
  \displayarrow{cm cap}\\
\end{tabular}

\item[Arrow tips for double lines]\ \\
\begin{tabular}{ll}
  \displayarrow[/tikz/double distance=3.643\pgflinewidth]{cm implies}\\
  \displayarrow[/tikz/double distance=3.643\pgflinewidth]{cm implies cap}
\end{tabular}

\item[Hooks]\ \\
\begin{tabular}{ll}
  \displayarrow{cm left hook}\\
  \displayarrow{cm right hook}\\
\end{tabular}

\item[Double arrow tips]\ \\
\begin{tabular}{ll}
  \displayarrow{cm double to}\\
  \displayarrow{cm double to reversed}\\
\end{tabular}

\item[Partial arrow tips]\ \\
\begin{tabular}{ll}
  \displayarrow{cm left to}\\
  \displayarrow{cm left to reversed}\\
  \displayarrow{cm right to}\\
  \displayarrow{cm right to reversed}\\
\end{tabular}
\end{description}

\subsection{Font arrow tips}
\label{sec:font-arrow-tips}

{\it This is
    an experimental feature.  It may be modified, moved elsewhere or
    even removed in the future.}

As an attempt to provide a general solution to the problem of having
matching arrow tips in text and pictures, this feature produces
arrow tips that consist of (pieces of) characters carefully placed at
the endpoints of the path.  To activate it in |tikzcd| diagrams, say
\begin{quote}
  |\tikzset{commutative diagrams/arrow style=math font}|.
\end{quote}
It is also necessary to load |amssymb| or some other package defining
the symbols corresponding to the arrow tips you want to use.
\ifLuaTeX
Here are some samples:

\begin{center}
  \begin{tikzpicture}
    \node[draw=gray,name=P]{
      \begin{minipage}[t]{0.25\linewidth}\centering
        \setmainfont{texgyrepagella-math.otf}
        \tikzset{commutative diagrams/.cd,
                 arrow style=math font,
                 default arrow/.append style={line width=0.6pt},
                 font arrows/.cd,
                 declare head={math to}{→}{2.5pt}{1ex},
                 declare tail={math cap}{→}{2.5pt}{1ex},
                 declare tail={math right hook}{↪}{2.5pt}{1ex},
                 declare head={math double to}{↠}{2.5pt}{1.4ex},
               }
        \begin{tikzcd}[math mode=false]
          \relax\ar[bend right]{rr}\rar[hook]%
          𝐴\pgfmatrixnextcell 𝐵\rar[two heads]%
          \pgfmatrixnextcell 𝐶
        \end{tikzcd}\\
        \TeX\ Gyre Pagella 
      \end{minipage}};
    \node[draw=gray,name=Q,right=5mm of P]{
      \begin{minipage}[t]{0.25\linewidth}\centering
        \setmainfont{STIXGeneral.otf}
        \tikzset{commutative diagrams/.cd,
                 arrow style=math font,
                 default arrow/.append style={line width=0.66pt},
                 font arrows/.cd,
                 declare head={math to}{→}{2.5pt}{1ex},
                 declare tail={math cap}{→}{2.5pt}{1ex},
                 declare tail={math right hook}{↪}{2.5pt}{1ex},
                 declare head={math double to}{↠}{2.5pt}{1.4ex},
               }
        \begin{tikzcd}[math mode=false]
          \relax\ar[bend right]{rr}\rar[hook]%
          𝐴\pgfmatrixnextcell 𝐵\rar[two heads]%
          \pgfmatrixnextcell 𝐶
        \end{tikzcd}\\
        STIX
      \end{minipage}};
    \node[draw=gray,name=R,right=5mm of Q]{
      \begin{minipage}[t]{0.25\linewidth}\centering
        \setmainfont{lmodern-math.otf}
        \tikzset{commutative diagrams/.cd,
                 arrow style=math font,
                 default arrow/.append style={line width=0.4pt},
                 font arrows/.cd,
                 declare head={math to}{→}{2.5pt}{1ex},
                 declare tail={math cap}{→}{2.5pt}{1ex},
                 declare tail={math right hook}{↪}{2.5pt}{1ex},
                 declare head={math double to}{↠}{2.5pt}{1.4ex},
               }
        \begin{tikzcd}[math mode=false]
          \relax\ar[bend right]{rr}\rar[hook]%
          𝐴\pgfmatrixnextcell 𝐵\rar[two heads]%
          \pgfmatrixnextcell 𝐶
        \end{tikzcd}\\
        Latin Modern
      \end{minipage}};
\end{tikzpicture}
\end{center}
\fi

Setting the key above also makes arrow tips named |math to|,
\texttt{math to reversed}, \texttt{math cap}, \texttt{math \char`\|},
|math o|, \texttt{math implies}, |math implies cap|, |math left hook|,
\texttt{math right hook}, \texttt{math double to}, |math left to|, and
\texttt{math right to} available for use in \tikzname{} pictures in
the usual way.  These tips do not scale with the line width, but their
size depends on the current font size, so you will probably want to
set \texttt{line width=tikzcdrule} when using them. It is possible to
define more arrows or tweak the existing ones.  Look into the source
code of this package if you are interested.  (And let me know what you
think!)

The transition between a line and the arrow tip may be visible with some
document viewers and printers, as you may notice from the picture
below.  When using \pdf\TeX{} (or Lua\TeX) with \pdf{} output, a
measure is taken to alleviate this.
\begin{center}\tikzset{commutative diagrams/enable font arrows}
  \pdf\TeX{} \tikz[baseline=-tikzcdaxis]
  \draw[math to-math to, line width=tikzcdrule] (0,0) -- (1,0);
  \hspace{1cm}
  Other \TeX{} engines
  \makeatletter\def\tikzcd@arrowset{\tikzcd@arrowset@generic}\makeatother
  \tikz[baseline=-tikzcdaxis]
  \draw[math to-math to,line width=tikzcdrule] (0,0) -- (1,0);
\end{center}

I don't know of any automatic way of determining the distance between
the lines in a $\Rightarrow$,
so this parameter has to be entered manually via the key
\texttt{/tikz/commutative diagrams/font arrows/double distance} if you
want to use double lines.

\begin{thebibliography}{9}
\bibitem{knuth}
  Donald Knuth,
  \emph{Important message to all users of \TeX}.
  Available at \url{http://www-cs-staff.stanford.edu/~uno/cm.html}
\bibitem{lenders}
  Felix Lenders,
  \emph{Commutative diagrams using \tikzname}.
  Available at \url{http://www.felixl.de/commu.pdf}.
\bibitem{milne}
  James Milne,
  \emph{Guide to commutative diagrams}.
  Available at \url{http://www.jmilne.org/not/CDGuide.html}.
\bibitem{pgfman}
  Till Tantau,
  \emph{The \tikzname{} and \pgfname{} packages:  Manual for version 2.10}.
  Available at \url{http://www.ctan.org/tex-archive/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf}.
\end{thebibliography}

\end{document}

%%% Local Variables:
%%% mode: tex
%%% mode: auto-fill
%%% End: