Debian Codegraph @

texmf-dist/doc/latex/tikz-cd/tikz-cd-doc.tex

raw
1 %% tikz-cd-doc.tex
2 %% Copyright 2011, 2012, 2014, 2018, 2021 Augusto Stoffel
3 %
4 % This work may be distributed and/or modified under the
5 % conditions of the LaTeX Project Public License, either version 1.3
6 % of this license or (at your option) any later version.
7 % The latest version of this license is in
8 % http://www.latex-project.org/lppl.txt
9 % and version 1.3 or later is part of all distributions of LaTeX
10 % version 2005/12/01 or later.
11 %
12 % This work has the LPPL maintenance status `maintained'.
13 %
14 % The Current Maintainer of this work is Augusto Stoffel.
15 %
16 % This work consists of the files tikzlibrarycd.code.tex, tikz-cd.sty
17 % and tikz-cd-doc.tex.
18 %
19 % ------------------------------------------------------------------------
20 %
21 % This document requires the file pgfmanual-en-macros.tex (distributed
22 % with pgf) to compile. To get cross-references to the pgf manual,
23 % compile it and copy all resulting .aux files to the directory of
24 % tikz-cd-doc.tex.
25
26 \def\pgfautoxrefs{1}
27
28 \documentclass[a4paper]{ltxdoc}
29 \usepackage[hyphens]{url}
30
31 \def\xcolorversion{2.00}
32
33 \usepackage[version=latest]{pgf}
34
35 \usepackage{xkeyval,calc,listings,tikz,fp}
36
37 \usepackage{hyperref}
38 \hypersetup{%
39 colorlinks=false, % use true to enable colors below:
40 linkcolor=blue,%red,
41 filecolor=blue,%magenta,
42 pagecolor=blue,%red,
43 urlcolor=blue,%cyan,
44 citecolor=blue,
45 pdfborder=0 0 0,
46 }
47
48 % We need lots of libraries...
49 \usetikzlibrary{
50 arrows,
51 arrows.meta,
52 calc,
53 fit,
54 patterns,
55 plotmarks,
56 shapes.geometric,
57 shapes.misc,
58 shapes.symbols,
59 shapes.arrows,
60 shapes.callouts,
61 shapes.multipart,
62 shapes.gates.logic.US,
63 shapes.gates.logic.IEC,
64 circuits.logic.US,
65 circuits.logic.IEC,
66 circuits.logic.CDH,
67 circuits.ee.IEC,
68 datavisualization,
69 datavisualization.formats.functions,
70 er,
71 automata,
72 backgrounds,
73 chains,
74 topaths,
75 trees,
76 petri,
77 mindmap,
78 matrix,
79 calendar,
80 folding,
81 fadings,
82 shadings,
83 spy,
84 through,
85 turtle,
86 positioning,
87 scopes,
88 decorations.fractals,
89 decorations.shapes,
90 decorations.text,
91 decorations.pathmorphing,
92 decorations.pathreplacing,
93 decorations.footprints,
94 decorations.markings,
95 shadows,
96 lindenmayersystems,
97 intersections,
98 fixedpointarithmetic,
99 fpu,
100 svg.path,
101 external,
102 }
103
104 \usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
105 \usepackage{amsmath,amssymb}
106 \usepackage{xxcolor}
107 \usepackage{pifont}
108 \usepackage{makeidx}
109 \usepackage{tikz-cd,xr,multicol,microtype}
110
111
112 \IfFileExists{pgfmanual-en-macros}
113 {\input{pgfmanual-en-macros}}
114 {\PackageError{tikz-cd-doc}{
115 This document requires the file pgfmanual-en-macros.tex (distributed
116 with pgf) to compile. Please place a copy of that file in the current
117 directory}{}}
118
119 \IfFileExists{pgfmanual.aux}
120 {\externaldocument[pgfman-]{pgfmanual}}
121 {\PackageWarning{tikz-cd-doc}{
122 Couldn't find pgfmanual.aux. To get cross-references to the pgf
123 manual, compile it and copy all resulting .aux files to the current
124 directory}{}}
125
126 \makeindex
127
128 % Global styles:
129 \tikzset{
130 every plot/.style={prefix=plots/pgf-},
131 shape example/.style={
132 color=black!30,
133 draw,
134 fill=yellow!30,
135 line width=.5cm,
136 inner xsep=2.5cm,
137 inner ysep=0.5cm}
138 }
139
140 \hypersetup{unicode,
141 pdftitle={tikzcd: Commutative diagrams with TikZ},
142 pdfkeywords={Commutative diagrams; TeX; LaTeX; ConTeXt; TikZ; pgf; tikz-cd; tikzcd},
143 }
144
145 \pgfkeys{
146 /pdflinks/search key prefixes in=
147 {/tikz/commutative diagrams/},%,/tikz/,/pgf/} % This really needs to be commented out!
148 /pdflinks/internal link prefix=tikzcd,
149 %
150 /pdflinks/warnings=false,
151 % for debugging:
152 /pdflinks/show labels=false,
153 }
154
155 \tikzset{/codeexample/every codeexample/.append style={/tikz/commutative diagrams/background color=graphicbackground}}
156
157 \tikzset{gray x/.tip={Rays[color=gray]}}
158
159 \newcommand{\displayarrow}[2][]{%
160 \index{#2@\protect\texttt{#2} arrow tip}%
161 \index{Arrow tips!#2@\protect\texttt{#2}}%
162 \texttt{#2} & yields \tikz[baseline=-axis_height] \draw[{#2}-{#2}, line width=rule_thickness, #1] (0,0) -- (1,0);}
163
164 \newcommand{\displayarrowstyle}[1]{
165 \def\mykey{/tikz/commutative diagrams/#1}%
166 \def\mypath{}%
167 \def\myname{}%
168 \firsttimetrue%
169 %\pgfmanualdecomposecount=0\relax%
170 \decompose/tikz/commutative diagrams/#1/\nil%
171 \texttt{#1} & yields
172 \tikz[baseline=-axis_height, line width=rule_thickness] \draw[arrows=gray
173 x-gray x,commutative diagrams/.cd, #1] (0,0) -- (0.6,0);}
174
175 \begin{document}
176 \begin{center}
177 \vspace*{1em}
178 \tikz\node[scale=1.2]{%
179 \color{gray}\Huge\ttfamily \char`\{\textcolor{red!75!black}{tikzcd}\char`\}};
180
181 \vspace{0.5em}
182 {\Large\bfseries Commutative diagrams with \tikzname}
183
184 \vspace{1em}
185 {Version 1.0 \qquad May 4, 2021}
186 \end{center}
187
188 \vspace{1.5em}
189 The general-purpose drawing package Ti\emph{k}Z can be used to typeset
190 commutative diagrams and other kinds of mathematical pictures,
191 generating high-quality results. The present package facilitates the
192 creation of such diagrams by providing a convenient set of macros and
193 reasonable default settings. Familiarity with Ti\emph{k}Z is helpful
194 but not necessary, since the examples contained here cover the most
195 common situations.
196
197 This work may be distributed and/or modified under the conditions of
198 the \LaTeX\ Project Public License, either version 1.3 of this license
199 or (at your option) any later version.
200
201 \tableofcontents
202
203 \section{Getting started}
204 \label{sec:basic-usage}
205
206 To load this package in \LaTeX, type
207 \begin{verse}
208 \index{tikz-cd@\protect\texttt{tikz-cd} package}%
209 \index{Packages and files!tikz-cd@\protect\texttt{tikz-cd}}%
210 |\usepackage{tikz-cd}|%
211 \end{verse}
212 or load \tikzname{} and then type
213 \begin{verse}%
214 \index{cd@\protect\texttt{cd} library}%
215 \index{Libraries!cd@\protect\texttt{cd}}%
216 |\usetikzlibrary{cd}|%
217 \end{verse}
218 This package is compatible with other \TeX\ formats as well.
219 See~\S\ref{sec:usage-plain-tex} and \S\ref{sec:usage-context}.
220
221 \subsection{Creating a diagram}
222 \label{sec:creating-diagrams}
223
224 The basic tool to create a commutative diagram is the following
225 environment.
226
227 \begin{environment}{{tikzcd}\opt{\oarg{options}}}
228 \end{environment}
229
230 The environment contents should describe a matrix, as in \LaTeX's
231 familiar |{tabular}| environment. The optional argument
232 \meta{options} may be used to modify the appearance of the diagram.
233 Any of the customization keys described in this manual, as well as
234 those originally provided by \tikzname{}, can be used here. Arrows
235 between matrix entries can be created with the |\arrow| command
236 described below.
237
238 Everything inside |{tikzcd}| is typeset in math mode, but you will
239 probably want to use it inside an |{equation}| environment or
240 |\[| \dots |\]|,
241 so that the diagram is placed on a new line and centered.
242
243 It is important to note that \textsc{dvi} viewers will not display
244 diagrams correctly. It is necessary to convert the \textsc{dvi} file
245 to \textsc{pdf} or \textsc{ps} format---or, even better, use a tool
246 that generates \textsc{pdf} files directly, such as \texttt{pdflatex}.
247
248 \subsection{Inserting arrows}
249 \label{sec:inserting-arrows}
250
251 Inside the |{tikzcd}| environment, the following synonymous commands
252 are provided to produce arrows.
253
254 \begin{pgfmanualentry}
255 \extractcommand\arrow|[|\meta{options}|]|\@@
256 \extractcommand\ar|[|\meta{options}|]|\@@
257 \pgfmanualbody
258 \end{pgfmanualentry}
259
260 Here, \meta{options} is a comma-separated list of options which can be
261 used to specify the arrow target, add labels, change arrow tips, and
262 perform additional modifications.
263
264 The arrow target can be specified by a direction parameter, which
265 consists of a string of characters |r|, |l|, |d|, |u| (standing for
266 right, left, down and up). Labels can be placed on an arrow by means
267 of the quotes syntax, described in detail in the \pgfname{} manual
268 \cite[\S\ref*{pgfman-section-label-quotes}]{pgfman}. Notice the use
269 of |"\phi"| in the example below.
270
271 \begin{codeexample}[]
272 \begin{tikzcd}
273 A \arrow[rd] \arrow[r, "\phi"] & B \\
274 & C
275 \end{tikzcd}
276 \end{codeexample}
277
278 To further modify the appearance of an arrow, note that \meta{options}
279 may contain any key that can be passed to \tikzname's |\path| command.
280 Similarly, a label can receive additional options via the syntax
281 \begin{verse}
282 |"|\meta{label text}|"|\opt{\meta{label options}}.
283 \end{verse}
284 Both \meta{label text} and \meta{label options} need to be enclosed in
285 curly braces if they contain commas.
286
287 {\catcode`\|=12
288 \begin{codeexample}[]
289 \begin{tikzcd}
290 A \arrow[r, "\phi"] \arrow[d, red]
291 & B \arrow[d, "\psi" red] \\
292 C \arrow[r, red, "\eta" blue]
293 & |[blue, rotate=-15]| D
294 \end{tikzcd}
295 \end{codeexample}
296 }
297
298 The example above also showcases one of the possible ways to pass
299 special options to a \tikzname\ matrix node. See the \pgfname{}
300 manual \cite[\S\ref*{pgfman-section-matrices}]{pgfman} for more
301 information.
302
303 Arrows can have an arbitrary number of labels, by repeated use of
304 arguments in quotes. The example below shows how to control the
305 positioning of labels. Notice in particular that an apostrophe as
306 \meta{label option} causes the label to be placed on the opposite side
307 of the arrow.
308
309 \begin{codeexample}[]
310 \begin{tikzcd}
311 A \arrow[r, "\phi" near start, "\psi"', "\eta" near end] & B
312 \end{tikzcd}
313 \end{codeexample}
314
315 We provide two real-life examples.
316
317 \begin{codeexample}[]
318 \begin{tikzcd}
319 T
320 \arrow[drr, bend left, "x"]
321 \arrow[ddr, bend right, "y"]
322 \arrow[dr, dotted, "{(x,y)}" description] & & \\
323 & X \times_Z Y \arrow[r, "p"] \arrow[d, "q"]
324 & X \arrow[d, "f"] \\
325 & Y \arrow[r, "g"]
326 & Z
327 \end{tikzcd}
328 \end{codeexample}
329
330 \begin{codeexample}[]
331 \begin{tikzcd}[column sep=tiny]
332 & \pi_1(U_1) \ar[dr] \ar[drr, "j_1", bend left=20]
333 &
334 &[1.5em] \\
335 \pi_1(U_1\cap U_2) \ar[ur, "i_1"] \ar[dr, "i_2"']
336 &
337 & \pi_1(U_1) \ast_{ \pi_1(U_1\cap U_2)} \pi_1(U_2) \ar[r, dashed, "\simeq"]
338 & \pi_1(X) \\
339 & \pi_1(U_2) \ar[ur]\ar[urr, "j_2"', bend right=20]
340 &
341 &
342 \end{tikzcd}
343 \end{codeexample}
344
345 \subsection{Changing arrow tips}
346 \label{sec:changing-arrow-tips}
347
348 A set of |\arrow| options is provided to create different kinds of
349 arrows. Some of these options have a short descriptive name, such as
350 |hook|, and others are named after \TeX{} arrow-producing commands
351 (without a ``|\|''), like |dashrightarrow|.%|
352
353 \begin{codeexample}[]
354 \begin{tikzcd}
355 X \arrow[r, hook] \arrow[dr, dashrightarrow]
356 & \bar{X} \arrow[d]\\
357 & Y
358 \end{tikzcd}
359 \end{codeexample}
360
361 The following list shows all available arrow types (each of them is a
362 style key located in |/tikz/commutative diagrams|).
363
364 \begin{multicols}{2}\raggedcolumns
365 \subsubsection*{Basic arrows}
366 \begin{tabular}{ll}
367 \displayarrowstyle{to head}\\
368 \displayarrowstyle{rightarrow}\\
369 \displayarrowstyle{leftarrow}\\
370 \displayarrowstyle{leftrightarrow}\\
371 \displayarrowstyle{Rightarrow}\\
372 \displayarrowstyle{Leftarrow}\\
373 \displayarrowstyle{Leftrightarrow}
374 \end{tabular}
375
376 \subsubsection*{Arrows from bar}
377 \begin{tabular}{ll}
378 \displayarrowstyle{maps to}\\
379 \displayarrowstyle{mapsto}\\
380 \displayarrowstyle{mapsfrom}\\
381 \displayarrowstyle{Mapsto}\\
382 \displayarrowstyle{Mapsfrom}\\
383 \end{tabular}
384
385 \subsubsection*{Arrows with hook}
386 \begin{tabular}{ll}
387 \displayarrowstyle{hook}\\
388 \displayarrowstyle{hook'}\\
389 \displayarrowstyle{hookrightarrow}\\
390 \displayarrowstyle{hookleftarrow}\\
391 \end{tabular}
392
393 \subsubsection*{Arrows with tail}
394 \begin{tabular}{ll}
395 \displayarrowstyle{tail}\\
396 \displayarrowstyle{rightarrowtail}\\
397 \displayarrowstyle{leftarrowtail}\\
398 \end{tabular}
399
400 \subsubsection*{Two-headed arrows}
401 \begin{tabular}{ll}
402 \displayarrowstyle{two heads}\\
403 \displayarrowstyle{twoheadrightarrow}\\
404 \displayarrowstyle{twoheadleftarrow}\\
405 \end{tabular}
406
407 \subsubsection*{Harpoons}
408 \begin{tabular}{ll}
409 \displayarrowstyle{harpoon}\\
410 \displayarrowstyle{harpoon'}\\
411 \displayarrowstyle{rightharpoonup}\\
412 \displayarrowstyle{rightharpoondown}\\
413 \displayarrowstyle{leftharpoonup}\\
414 \displayarrowstyle{leftharpoondown}\\
415 \end{tabular}
416
417 \subsubsection*{Dashed arrows}
418 \begin{tabular}{ll}
419 \displayarrowstyle{dashed}\\
420 \displayarrowstyle{dashrightarrow}\\
421 \displayarrowstyle{dashleftarrow}\\
422 \end{tabular}
423
424 \subsubsection*{Squiggly arrows}
425 \begin{tabular}{ll}
426 \displayarrowstyle{squiggly}\\
427 \displayarrowstyle{rightsquigarrow}\\
428 \displayarrowstyle{leftsquigarrow}\\
429 \displayarrowstyle{leftrightsquigarrow}
430 \end{tabular}
431
432 \subsubsection*{Non-arrows}
433 \begin{tabular}{ll}
434 \displayarrowstyle{no head}\\
435 \displayarrowstyle{no tail}\\
436 \displayarrowstyle{dash}\\
437 \displayarrowstyle{equal}\\
438 \end{tabular}
439 \end{multicols}
440
441 A gray cross (\tikz \path[/pgf/tips=true,gray x-] (0,0) -- (1mm,0);)
442 in the samples above indicates that the corresponding tip is kept
443 unchanged. This allows several arrow styles to be superimposed.
444
445 \begin{codeexample}[]
446 \begin{tikzcd}
447 A \arrow[r, tail, two heads, dashed] & B
448 \end{tikzcd}
449 \end{codeexample}
450
451 % It is also possible to select arrow tips using \tikzname{}'s |arrow|
452 % option directly (e.g., by saying |right hook->|). However, the method
453 % described here above is more appropriate, as it abstracts the choice
454 % of an actual arrow tip design (see also the |arrow style| key below),
455 % and is arguably better from the mnemonic standpoint.
456
457
458 \subsection{Alternative syntax for arrows}
459 \label{sec:altern-synt-arrows}
460
461 The following forms of the arrow command were used before the
462 appearance of the quotes syntax for labels, and now may seem somewhat
463 convoluted. They are nonetheless still available for backwards
464 compatibility.
465
466 \begin{command}{\arrow\opt{\oarg{options}}\marg{direction}\meta{labels}}
467 \end{command}
468
469 Here, \meta{direction} is a string containing the characters |r|, |l|,
470 |d|, |u| and is used to determine the arrow target. Alternatively,
471 you can specify an explicit matrix cell by replacing \meta{direction}
472 with something of the form \meta{row number}\texttt{-}\meta{column
473 number}, or the name of a node. The trailing \meta{labels} can be the
474 empty string or of the form
475 \begin{verse}
476 \opt{\oarg{label options}}\marg{label text}\meta{more labels}.
477 \end{verse}
478 The equivalent command |\ar| can also be used in this form. Here is
479 an example.
480
481 \begin{codeexample}[]
482 \begin{tikzcd}
483 A \arrow{d} \arrow{r}[near start]{\phi}[near end]{\psi}
484 & B \arrow[red]{d}{\xi} \\
485 C \arrow[red]{r}[blue]{\eta}
486 & D
487 \end{tikzcd}
488 \end{codeexample}
489
490 There are further shortened forms:
491 \begin{pgfmanualentry}
492 \extractcommand\rar\opt{\oarg{options}}\meta{labels}\@@
493 \extractcommand\lar\opt{\oarg{options}}\meta{labels}\@@
494 \extractcommand\dar\opt{\oarg{options}}\meta{labels}\@@
495 \extractcommand\uar\opt{\oarg{options}}\meta{labels}\@@
496 \extractcommand\drar\opt{\oarg{options}}\meta{labels}\@@
497 \extractcommand\urar\opt{\oarg{options}}\meta{labels}\@@
498 \extractcommand\dlar\opt{\oarg{options}}\meta{labels}\@@
499 \extractcommand\ular\opt{\oarg{options}}\meta{labels}\@@
500 \pgfmanualbody
501 \end{pgfmanualentry}
502 The first one is equivalent to
503 \begin{verse}
504 |\arrow|{\oarg{options}}|{r}|\meta{labels}
505 \end{verse}
506 and the other ones work analogously.
507
508 \subsection{Usage in plain \TeX{}}
509 \label{sec:usage-plain-tex}
510
511 To use this package in plain \TeX{}, load \tikzname{} and the
512 \texttt{cd} library by saying
513 \begin{verse}
514 |\input tikz.tex|\\
515 \index{cd@\protect\texttt{cd} library}%
516 \index{Libraries!cd@\protect\texttt{cd}}%
517 |\usetikzlibrary{cd}|
518 \end{verse}
519 The |{tikzcd}| environment should then be replaced by the following:
520 \begin{plainenvironment}{{tikzcd}\opt{\oarg{options}}}
521 \end{plainenvironment}
522 All other functions of this library work as described in this manual
523 without change.
524
525 \subsection{Usage in Con\TeX t}
526 \label{sec:usage-context}
527
528 To use this package in Con\TeX t, load \tikzname{} and then the
529 \texttt{cd} library by saying
530 \begin{verse}
531 |\usemodule[tikz]|\\
532 \index{cd@\protect\texttt{cd} library}%
533 \index{Libraries!cd@\protect\texttt{cd}}%
534 |\usetikzlibrary[cd]|
535 \end{verse}
536 The |{tikzcd}| environment should then be replaced by the following:
537 \begin{contextenvironment}{{tikzcd}\opt{\oarg{options}}}
538 \end{contextenvironment}
539 Moreover, you may replace the column and row separators |&|, |\\| by
540 their Con\TeX t analogues |\NC|, |\NR|. However, you should use |\NC|
541 only \emph{between} cells, and not before the first column or after
542 the last column, as in usual Con\TeX t tables. Similarly, |\NR|
543 should be used only between rows.
544
545 All other functions of this library work as described in this manual
546 without change.
547
548 \section{Controlling the appearance of diagrams}
549 \label{sec:chang-appe-diagr}
550
551 This section describes a number of customization keys defined by this
552 package. All keys are located in the path |/tikz/commutative diagrams|.
553 Options passed to |{tikzcd}| or |\arrow| are searched for
554 in that path, and, if not found there, in |/tikz|. To set options
555 globally, it is convenient to use the following command.
556
557 \begin{command}{\tikzcdset\marg{options}}
558 Executes \meta{options} in the path |/tikz/commutative diagrams|.
559 \end{command}
560
561 Besides the keys described in this manual, numerous \tikzname\
562 parameters can affect the appearance of a diagram. However, only a
563 few of them (namely those appearing in |every diagram|, |every cell|,
564 |every arrow|, and |every label| below) are reinitialized when
565 |{tikzcd}| is called. This means that modifying a certain \tikzname\
566 parameter globally may or may not affect the output of |{tikzcd}|.
567
568 We also point out that besides the options and styles provided by this
569 package, several keys defined by \tikzname{} are useful for arrows.
570 Some examples are \texttt{dashed}, |dotted|, and its relatives,
571 |line width=|\meta{dimension}, |color=|\meta{color}, |bend right|, |bend left|,
572 |in=|\meta{angle}, |out=|\meta{angle}, |loop|, etc. See the
573 \pgfname{} manual~\cite[\S\ref*{pgfman-section-cap-joins} and
574 \S\ref*{pgfman-library-to-paths}]{pgfman}. Likewise, \tikzname{}
575 provides several keys that are useful for labels, such as |above|,
576 |below|, |left|, |right|, |swap| (which makes the label be placed on
577 the right side of the arrow, relative to its direction), |sloped|,
578 |pos=|\meta{fraction}, |near start|, |near end|, |inner sep=|\meta{dimension},
579 |font=|\meta{font command}, |text width=|\meta{dimension}, etc. See the \pgfname{}
580 manual~\cite[\S\ref*{pgfman-section-nodes}, esp.\
581 \S\ref*{pgfman-section-pos-option}]{pgfman}.
582
583 \subsection{General options}
584 \label{sec:general-options}
585
586 \begin{stylekey}{/tikz/commutative diagrams/every diagram}
587 This style is applied to every |{tikzcd}| environment. Initially, it
588 contains the following:
589 \begin{verse}
590 |row sep=normal||,|\\
591 |column sep=normal||,|\\
592 |/tikz/baseline=0pt|
593 \end{verse}
594 \end{stylekey}
595
596 The |baseline=0pt| setting is used to make equation numbers be placed
597 correctly (as an exception, one-row diagrams are anchored at their
598 matrix base, which is exactly what you want).
599
600 \begin{key}{/tikz/commutative diagrams/diagrams=\meta{options}}
601 This key appends \meta{options} to the style |every diagram|.
602 \end{key}
603
604 \begin{stylekey}{/tikz/commutative diagrams/every matrix}
605 This style is applied to the \tikzname{} matrix created internally
606 by |{tikzcd}|. Initially, it contains the following:
607 \begin{verse}
608 |/tikz/inner sep=0pt|
609 \end{verse}
610 \end{stylekey}
611
612 \begin{stylekey}{/tikz/commutative diagrams/every cell}
613 This style is applied to every \tikzname{} matrix cell created by
614 |{tikzcd}|. Initially, it contains the following:
615 \begin{verse}
616 |/tikz/shape=asymmetrical rectangle||,|\\
617 |/tikz/inner xsep=1ex||,|\\
618 |/tikz/inner ysep=0.85ex|
619 \end{verse}
620 \end{stylekey}
621
622 The |asymmetrical rectangle| shape is described in
623 \S\ref{sec:asymm-rect-shape}. The |inner xsep|, |inner ysep| options
624 determine the spacing between a diagram entry and any arrows reaching
625 it.
626
627 \begin{key}{/tikz/commutative diagrams/cells=\meta{options}}
628 This key appends \meta{options} to the style |every cell|.
629 \end{key}
630
631 \def\printsepaux+#1em{#1\,em}
632 \def\printsep#1#2{\edef\temp{\pgfkeysvalueof{/tikz/commutative diagrams/#1 sep/#2}}\expandafter\printsepaux\temp}
633
634 \begin{key}{/tikz/commutative diagrams/row sep=\meta{size}}
635 This key acts as a frontend to \tikzname's |/tikz/row sep| key. If
636 the key
637 \begin{verse}
638 |/tikz/commutative diagrams/row sep/|\meta{size}
639 \end{verse}
640 stores a \meta{value}, then it is read and
641 |/tikz/row sep|=\meta{value} is set. If the key above is not
642 initialized, then \meta{size} is presumed to be a dimension, and
643 |/tikz/row sep|=\meta{size} is set.
644
645 The initially available sizes, and their values, are
646 the following:
647 \begin{center}
648 \begin{tabular}{cccccc}
649 |tiny| & |small| & |scriptsize| & |normal| & |large| & |huge| \\
650 \printsep{row}{tiny} & \printsep{row}{small} & \printsep{row}{scriptsize} & \printsep{row}{normal} & \printsep{row}{large} & \printsep{row}{huge}
651 \end{tabular}
652 \end{center}
653 \end{key}
654
655 Notice that setting, say, |row sep=1cm| globally with |\tikzcdset| will
656 have no effect, since the |row sep| option is re-set at the beginning
657 of each diagram. To make all diagrams have |row sep| equal to 1\,cm,
658 you can modify the meaning of |normal| by saying
659 \begin{verse}
660 |\tikzcdset{row sep/normal=1cm}|.
661 \end{verse}
662 You can also create new sizes, but note that \pgfname\ requires new keys to be
663 initialized explicitly. For example, to create a size |my size|,
664 meaning 1\,ex, you should use
665 \begin{verse}
666 |\tikzcdset{row sep/my size/.initial=1ex}|.
667 \end{verse}
668
669 \begin{key}{/tikz/commutative diagrams/column sep=\meta{size}}
670 This works analogously to the |row sep| key above. The sizes available
671 initially are the following:
672 \begin{center}
673 \begin{tabular}{cccccc}
674 |tiny| & |small| & |scriptsize| & |normal| & |large| & |huge| \\
675 \printsep{column}{tiny} & \printsep{column}{small} & \printsep{column}{scriptsize} & \printsep{column}{normal} & \printsep{column}{large} & \printsep{column}{huge}
676 \end{tabular}
677 \end{center}
678 \end{key}
679
680 \begin{key}{/tikz/commutative diagrams/sep=\meta{size}}
681 This key sets |row sep=|\meta{size}, |column sep=|\meta{size}.
682 \end{key}
683
684 In the examples below, the triangular diagrams would look too wide or
685 too tall if the column or row separation were not set appropriately.
686
687 \begin{codeexample}[]
688 \begin{tikzcd}[column sep=small]
689 & A \arrow[dl] \arrow[dr] & \\
690 B \arrow{rr} & & C
691 \end{tikzcd}
692 \end{codeexample}
693
694 \begin{codeexample}[]
695 \begin{tikzcd}[row sep=tiny]
696 & B \arrow[dd] \\
697 A \arrow[ur] \arrow[dr] & \\
698 & C
699 \end{tikzcd}
700 \end{codeexample}
701
702 Section \ref*{pgfman-section-matrices}.3.2 of the \pgfname{} manual
703 \cite{pgfman} contains further details on the spacing of matrix cells.
704
705 \begin{stylekey}{/tikz/commutative diagrams/cramped}
706 By default, a generous amount of white space is added around diagram
707 cells, which is appropriate for large, displayed diagrams. The
708 present style removes some of this extra white space, and is
709 intended for smaller diagrams that should blend with the surrounding
710 text, or very wide material that wouldn't fit the page otherwise.
711 \end{stylekey}
712
713 The picture below shows the (somewhat subtle) difference
714 between the cramped and the non-cramped styles.
715
716 \begin{codeexample}[pre=\minipage{6cm},post=\endminipage]
717 This \begin{tikzcd} A \arrow[r] & B \end{tikzcd} is a regular diagram.\\
718 This \begin{tikzcd}[cramped, sep=small] A \arrow[r] & B \end{tikzcd} is a cramped diagram.\\
719 This $A \to B$ is just a formula.
720 \end{codeexample}
721
722 Keep in mind that while there are some legitimate uses for |{tikzcd}|
723 diagrams on inline formulas, standard \LaTeX\ constructs such as
724 |\overset| and |\xrigthtarrow| are often sufficient and should be
725 preferred.
726
727 \begin{key}{/tikz/commutative diagrams/math mode=\meta{boolean}
728 (default true)}
729 This key determines whether or not the contents of a diagram are
730 typeset in math mode. If set globally or diagram-wise, it affects
731 both the diagram entries and arrow labels. If used with |\arrow|,
732 it affects only its labels.
733 \end{key}
734
735 \begin{key}{/tikz/commutative diagrams/background color=\meta{color} (initially white)}
736 This key stores the name of a color, and is read by
737 styles that fill the background, such as |description| and |crossing over|.
738 It does not cause the background of diagrams to be filled.
739 \end{key}
740
741 \subsection{Global options for arrows}
742 \label{sec:options-arrows}
743
744 \begin{stylekey}{/tikz/commutative diagrams/every arrow}
745 This style is applied to every |\arrow|. Initially, it contains the
746 following:
747 \begin{verse}
748 |/tikz/draw,|\\
749 |/tikz/line width=rule_thickness||,|\\
750 |rightarrow|
751 \end{verse}
752 \end{stylekey}
753
754 \begin{key}{/tikz/commutative diagrams/arrows=\meta{options}}
755 This key appends \meta{options} to the style |every arrow|.
756 \end{key}
757
758 \begin{key}{/tikz/commutative diagrams/arrow style=\meta{style}}
759 This key determines which collection of arrow tips is used by the
760 arrow tip selection styles listed in
761 \S\ref{sec:changing-arrow-tips}. The initial setting is suitable
762 for documents using the Computer Modern font at any size. The
763 available choices for \meta{style} are:
764 \begin{description}
765 \item[\texttt{Latin Modern}] A small variant of the initial
766 settings, intended for documents using the Latin Modern font at
767 any size.
768 \item[\texttt{math font}] This setting uses the |Glyph| meta arrow
769 tip described in \S\ref{sec:font-arrow-tips}.
770 \item[\texttt{tikz}] This setting uses the arrow tips defined in
771 \tikzname's |arrows.meta| library. It honors the option
772 |/tikz/>|.
773 \end{description}
774
775 This key is usually invoked in the document preamble, and should be
776 set only once.
777 \end{key}
778
779 If you are using a font different from Computer Modern or Latin
780 Modern, you may find the best results by selecting the |math font|
781 style. As detailed in \S\ref{sec:font-arrow-tips}, this is not
782 guaranteed to work perfectly with all fonts, but gives good results in
783 many cases. If the \texttt{math font} style gives unsatisfactory
784 results, you can try selecting the \texttt{tikz} style, and setting
785 |/tikz/>| to the value that best matches your font (among those shown
786 in \cite[\S\ref*{pgfman-section-arrows-meta}]{pgfman}).
787
788 \begin{codeexample}[]
789 % in preamble
790 \tikzcdset{
791 arrow style=tikz,
792 diagrams={>={Straight Barb[scale=0.8]}}
793 }
794
795 % in document body
796 \begin{tikzcd}
797 A \arrow[r, tail] \arrow[rd] & B \arrow[d, two heads]\\
798 & D
799 \end{tikzcd}
800 \end{codeexample}
801
802 \subsection{Absolute placement of arrows}
803 \label{sec:absol-positioning}
804
805 The usual behavior of |\arrow| is to produce an arrow starting at the
806 diagram entry where the command appears, and ending at an entry whose
807 location is specified relative to that. The following keys override
808 this behavior, allowing source and target to be selected explicitly.
809
810 \begin{key}{/tikz/commutative diagrams/from=\meta{argument}}
811 If \meta{argument} is of the form \meta{row
812 number}\texttt{-}\meta{column number}, or if it is a string of
813 characters |r|, |l|, |d|, |u|, this key sets the arrow source to be
814 the corresponding cell in the diagram matrix. Otherwise, it assumes
815 the argument is the name of a node and sets the arrow source to
816 \meta{argument}.
817 \end{key}
818
819 \begin{key}{/tikz/commutative diagrams/to=\meta{argument}}
820 Similar to |from|, but refers to the arrow target.
821 \end{key}
822
823 Recall that it is possible to give a specific entry of a \tikzname{}
824 matrix a name by using the \verb!|[!\meta{options}\verb!]|! syntax, as
825 done for entry $C$ in the example below. You must be careful not to
826 create nodes whose name contains only the characters |l|, |r|, |u|,
827 |d| if you want to refer to them using |from| or |to|. The following
828 illustrates several different uses of these keys.
829
830 {\catcode`\|=12
831 \begin{codeexample}[]
832 \begin{tikzcd}
833 A \arrow[to=Z, red] \arrow[to=2-2, blue]
834 & B \\
835 |[alias=Z]| C
836 & D
837 \arrow[from=ul, to=1-2, purple]
838 \end{tikzcd}
839 \end{codeexample}
840 }
841
842 In the next examples, empty labels are used to create nodes for later
843 reference. The |draw=red| option is used to show where these empty
844 nodes are located, but of course you want to remove that when using
845 this technique.
846
847 \begin{codeexample}[]
848 \begin{tikzcd}[column sep=scriptsize]
849 A \arrow[dr] \arrow[rr, ""{name=U, below, draw=red}]{}
850 & & B \arrow[dl] \\
851 & C \arrow[Rightarrow, from=U, "\psi"]
852 \end{tikzcd}
853 \end{codeexample}
854
855 \begin{codeexample}[]
856 \begin{tikzcd}
857 A \arrow[r, bend left=50, ""{name=U, below, draw=red}]
858 \arrow[r, bend right=50, ""{name=D, draw=red}]
859 & B
860 \arrow[Rightarrow, from=U, to=D]
861 \end{tikzcd}
862 \end{codeexample}
863
864 \subsection{Phantom arrows}
865 \label{sec:phantom-arrows}
866
867 Sometimes it is necessary to insert a symbol outside the grid
868 subjacent to the diagram. The easiest way to achieve this is as a
869 label to an invisible arrow.
870
871 \begin{stylekey}{/tikz/commutative diagrams/phantom}
872 Creates an invisible arrow. Labels to this arrow are not invisible.
873 They will be anchored at their center and typeset in full size
874 (i.e., with |\textstyle|). To get smaller labels, as in ordinary
875 arrows, use the |\scriptstyle| command.
876 \end{stylekey}
877
878 In the picture below, the arrow containing the |phantom| option goes from
879 $A$ to $D$, and the |\ulcorner| symbol ($\ulcorner$) is inserted
880 closer to the starting point $A$.
881 \begin{codeexample}[]
882 \begin{tikzcd}
883 A \arrow[r] \arrow[d] \arrow[dr, phantom, "\ulcorner", very near start]
884 & B \arrow[d] \\
885 C \arrow[r]
886 & D
887 \end{tikzcd}
888 \end{codeexample}
889
890 \subsection{Fine-tuning the placement of arrows}
891 \label{sec:fine-tuning-arrows}
892
893 \begin{key}{/tikz/commutative diagrams/shift left=\meta{dimension}
894 (default 0.56ex)}
895 Shifts arrows by \meta{dimension} to the left, relative to the arrow
896 direction. A dimensionless argument causes that multiple of the
897 default value to be used.
898 \end{key}
899
900 \begin{key}{/tikz/commutative diagrams/shift right=\meta{dimension}
901 (default 1)}
902 A shortcut to |shift left=-|\meta{dimension}.
903 \end{key}
904
905 \begin{codeexample}[]
906 \begin{tikzcd}
907 A \arrow[r, red, shift left=1.5ex] \arrow[r]
908 \arrow[dr, blue, shift right=1.5ex] \arrow[dr]
909 & B \arrow[d, purple, shift left=1.5ex] \arrow[d]\\
910 & C
911 \end{tikzcd}
912 \end{codeexample}
913
914 The default values of |shift left| and |shift right| are appropriate
915 for a pair of parallel arrows, and dimensionless arguments are useful
916 to create sets of multiple parallel arrows.
917 \begin{codeexample}[]
918 \begin{tikzcd}
919 A \arrow[r]
920 & B \arrow[r, shift left]
921 \arrow[r, shift right]
922 & C \arrow[r]
923 \arrow[r, shift left=2]
924 \arrow[r, shift right=2]
925 & \cdots
926 \end{tikzcd}
927 \end{codeexample}
928
929 \begin{key}{/tikz/commutative diagrams/shift=\marg{coordinate}}
930 Shifts arrows by \meta{coordinate}.
931 \end{key}
932
933 \begin{key}{/tikz/commutative diagrams/xshift=\meta{dimension}}
934 Shifts arrows right by \meta{dimension}.
935 \end{key}
936
937 \begin{key}{/tikz/commutative diagrams/yshift=\meta{dimension}}
938 Shifts arrows up by \meta{dimension}.
939 \end{key}
940
941 \begin{codeexample}[]
942 \begin{tikzcd}
943 A \arrow[r, yshift=0.7ex] \arrow[r, yshift=-0.7ex]
944 & B \arrow[d, xshift=0.7ex] \arrow[d, xshift=-0.7ex] \\
945 & C
946 \end{tikzcd}
947 \end{codeexample}
948
949 \begin{key}{/tikz/commutative diagrams/start anchor=\opt{{\ttfamily\char`\{}\ooarg{coordinate transformations}}\meta{anchor}\opt{\ttfamily\char`\}}}
950 This key specifies at which anchor of the source node the arrow
951 should start. Optionally, additional coordinate transformations can
952 be supplied. An empty \meta{anchor} argument causes no anchor to be
953 specified, which is the usual behavior.
954 \end{key}
955
956 \begin{key}{/tikz/commutative diagrams/end anchor=\opt{{\ttfamily\char`\{}\ooarg{coordinate transformations}}\meta{anchor}\opt{\ttfamily\char`\}}}
957 This key works analogously, but refers to the target node of the arrow.
958 \end{key}
959
960 See the picture on \S\ref{sec:asymm-rect-shape} for some of the
961 possible values for \meta{anchor}.
962 \begin{codeexample}[]
963 \begin{tikzcd}[cells={nodes={draw=gray}}]
964 A \arrow[r, black]
965 \arrow[r, blue, end anchor=north east]
966 \arrow[r,
967 red,
968 start anchor={[xshift=-1ex]},
969 end anchor={[yshift=2ex]north east}]
970 & B
971 \end{tikzcd}
972 \end{codeexample}
973
974 \begin{key}{/tikz/commutative diagrams/shorten=\meta{dimension}}
975 This key shortens each end of the arrow by \meta{dimension}.
976
977 \begin{codeexample}[]
978 \begin{tikzcd}
979 A \arrow[r, shift left]
980 \ar[r, shorten=2mm, shift right]
981 & B
982 \end{tikzcd}
983 \end{codeexample}
984 \end{key}
985
986 Note that the ends of an arrow can be shortened individually using
987 \tikzname's built-in keys |shorten <| and |shorten >|.
988
989 \subsection{Three-dimensional diagrams}
990 \label{sec:crossing-over}
991
992 \begin{stylekey}{/tikz/commutative diagrams/crossing over}
993 This style makes a thicker line, with color |background color|, to
994 be drawn under the current arrow, simulating the effect of its
995 passing over other arrows.
996
997 \begin{codeexample}[]
998 \begin{tikzcd}
999 A \arrow[dr] & B \arrow[dl, crossing over] \\
1000 C & D
1001 \end{tikzcd}
1002 \end{codeexample}
1003 \end{stylekey}
1004
1005 Note that, since arrows are drawn in the order they are read, it may
1006 be necessary to defer the drawing of certain arrows to achieve the
1007 desired result. This can be done using the |from| key, as shown in the
1008 following picture.
1009
1010 \begin{codeexample}[]
1011 \begin{tikzcd}[row sep=scriptsize, column sep=scriptsize]
1012 & f^* E_V \arrow[dl] \arrow[rr] \arrow[dd] & & E_V \arrow[dl] \arrow[dd] \\
1013 f^* E \arrow[rr, crossing over] \arrow[dd] & & E \\
1014 & U \arrow[dl] \arrow[rr] & & V \arrow[dl] \\
1015 M \arrow[rr] & & N \arrow[from=uu, crossing over]\\
1016 \end{tikzcd}
1017 \end{codeexample}
1018
1019 \begin{key}{/tikz/commutative diagrams/crossing over clearance=\meta{dimension}
1020 (initially 1.5ex)}
1021 This key specifies the width of the background-colored line drawn
1022 under a |crossing over| arrow.
1023 \end{key}
1024
1025 \subsection{Options for labels}
1026 \label{sec:options-labels}
1027
1028 \begin{stylekey}{/tikz/commutative diagrams/every label}
1029 This style is applied to every label produced with |\arrow|. It is initially set
1030 to
1031
1032 \begin{verse}
1033 |/tikz/auto,|\\
1034 |/tikz/font=|\meta{something}|,|\\
1035 |/tikz/inner sep=0.5ex|
1036 \end{verse}
1037 where \meta{something} is something that makes |\scriptstyle| be
1038 applied to labels in math mode.
1039 \end{stylekey}
1040
1041 The key |/tikz/auto| makes the label be placed on the left side of the
1042 arrow, relative to its direction. The key |/tikz/inner sep| controls
1043 the distance between a label and the corresponding arrow.
1044
1045 \begin{key}{/tikz/commutative diagrams/labels=\meta{options}}
1046 This key appends \meta{options} to |every label|.
1047 \end{key}
1048
1049 \begin{stylekey}{/tikz/commutative diagrams/marking}
1050 This style causes the label to be placed over the arrow. It is
1051 useful to decorate arrows using ordinary math symbols.
1052
1053 \begin{codeexample}[]
1054 \begin{tikzcd}
1055 A \arrow[r, "/" marking]
1056 \arrow[rd, "\circ" marking]
1057 & B \\
1058 & C
1059 \end{tikzcd}
1060 \end{codeexample}
1061 \end{stylekey}
1062
1063 \begin{stylekey}{/tikz/commutative diagrams/description}
1064 This style causes the label to be placed over the arrow, with the
1065 background filled. The clearance around the label is determined by
1066 \texttt{/tikz/inner sep}.
1067
1068 \begin{codeexample}[]
1069 \begin{tikzcd}
1070 A \arrow[r, "\phi" description] & B
1071 \end{tikzcd}
1072 \end{codeexample}
1073 \end{stylekey}
1074
1075 \section{Advanced usage}
1076 \label{sec:advanced-usage}
1077
1078 This section provides further details on the functioning of this
1079 package, with the aim of allowing the advanced user to make a more or
1080 less arbitrary use of other \tikzname{} features within |{tikzcd}|.
1081
1082 \subsection{Internals of \texttt{tikzcd} and the arrow commands}
1083 \label{sec:intern-arrow-comm}
1084
1085 The |{tikzcd}| environment works by substituting code of the form
1086 \begin{verse}
1087 |\begin{tikzcd}[|\meta{options}|]|\\
1088 \hspace*{1.5ex} \meta{contents}\\
1089 |\end{tikzcd}|
1090 \end{verse}
1091 with roughly the following:
1092 \begin{verse}
1093 |\begin{tikzpicture}[|\meta{options}|]|\\
1094 \hspace*{1.5ex}| \matrix[matrix of nodes] {|\\
1095 \hspace*{3ex}| |\meta{contents} |\\|\\
1096 \hspace*{1.5ex}| };|\\
1097 \hspace*{1.5ex}| |\meta{paths}\\
1098 |\end{tikzpicture}|
1099 \end{verse}
1100
1101 Not shown above are a number of initialization procedures, such as
1102 defining |\arrow| and its relatives, as well as applying the default
1103 settings specified by |every diagram| and its relatives. Note that
1104 the next-row command |\\| for the last row is inserted by |{tikzcd}|,
1105 and therefore should not be present in \meta{contents}. Notice also
1106 that you can use the key |execute at end picture| in \meta{options}
1107 to have arbitrary \tikzname{} code executed after a diagram is drawn.
1108
1109 Initially, \meta{paths} is the empty string. A command
1110 |\arrow[|\meta{options}|]| does nothing at the point it is inserted,
1111 and causes the following code to be appended to \meta{paths}:
1112 \begin{verse}
1113 |\path[|\meta{options}|] (|\meta{source~node}|) to (|\meta{target~node}|);|
1114 \end{verse}
1115 By default, \meta{source node} and \meta{target node} refer to the
1116 node corresponding to the matrix cell where the command |\arrow| is
1117 present. This can be changed using the |from| and |to| keys, or a
1118 direction argument (a string consisting of characters |r|, |l|, |d|,
1119 |u|).
1120
1121 \subsection{Tweaking \texttt{to} paths}
1122 \label{sec:tweaking-to-paths}
1123
1124 Recall that the \texttt{to} path operation used in the paths created by
1125 |\arrow| can take a number of options, as described in
1126 \S\ref*{pgfman-library-to-paths} of the \pgfname{} manual~\cite{pgfman}. In particular, the
1127 key |/tikz/to path| determines the path that is actually drawn, and
1128 can be used to do all sorts of fiddling.
1129
1130 \begin{codeexample}[]
1131 \begin{tikzcd}
1132 A \arrow[dr, controls={+(1.5,0.5) and +(-1,0.8)}]
1133 \arrow[dr, dashed, to path=|- (\tikztotarget)]
1134 & \\
1135 & B \arrow[loop right]
1136 \end{tikzcd}
1137 \end{codeexample}%|
1138
1139 The following example shows how to produce a ``snake'' map. The arrow
1140 with the |phantom| option (going from $B$ to $E$) has the sole purpose
1141 of creating a coordinate, named |Z|, lying halfway between these two
1142 cells. The arrow starting at $C$ has target $D$, so the macros
1143 |\tikztostart| and |\tikztotarget| will expand to the nodes
1144 corresponding to these two cells in the argument of |to path|. Notice
1145 also the use of |\tikztonodes| at the point where we want the label to
1146 be inserted.
1147 \begin{codeexample}[]
1148 \begin{tikzcd}
1149 A \arrow[r]
1150 & B \arrow[r]
1151 \arrow[d, phantom, ""{coordinate, name=Z}]
1152 & C \arrow[dll,
1153 "\delta",
1154 rounded corners,
1155 to path={ -- ([xshift=2ex]\tikztostart.east)
1156 |- (Z) [near end]\tikztonodes
1157 -| ([xshift=-2ex]\tikztotarget.west)
1158 -- (\tikztotarget)}] \\
1159 D \arrow[r]
1160 & E \arrow[r]
1161 & F
1162 \end{tikzcd}
1163 \end{codeexample}
1164
1165 \subsection{Drawing diagrams directly with Ti\emph{k}Z}
1166 \label{sec:draw-diagr-directly}
1167
1168 If you find that this package is not flexible enough for some
1169 particular application, you can use the methods described in
1170 \cite{milne} and draw diagrams directly with \tikzname. In this case,
1171 you can still use the styles provided here to obtain pictures with a
1172 uniform appearance throughout your document. The pictures below show
1173 how this can be done (the second one is adapted from \cite{milne}).
1174
1175 \begin{codeexample}[]
1176 \begin{tikzpicture}[commutative diagrams/every diagram]
1177 \matrix[matrix of math nodes, name=m, commutative diagrams/every cell] {
1178 X & \bar X \\
1179 & Y \\};
1180 \path[commutative diagrams/.cd, every arrow, every label]
1181 (m-1-1) edge[commutative diagrams/hook] (m-1-2)
1182 edge[commutative diagrams/dashed] (m-2-2)
1183 (m-1-2) edge (m-2-2);
1184 \end{tikzpicture}
1185 \end{codeexample}
1186
1187
1188 \begin{codeexample}[]
1189 \begin{tikzpicture}[commutative diagrams/every diagram]
1190 \node (P0) at (90:2.3cm) {$X\otimes (Y\otimes (Z\otimes T))$};
1191 \node (P1) at (90+72:2cm) {$X\otimes ((Y\otimes Z)\otimes T))$} ;
1192 \node (P2) at (90+2*72:2cm) {\makebox[5ex][r]{$(X\otimes (Y\otimes Z))\otimes T$}};
1193 \node (P3) at (90+3*72:2cm) {\makebox[5ex][l]{$((X\otimes Y)\otimes Z)\otimes T$}};
1194 \node (P4) at (90+4*72:2cm) {$(X\otimes Y)\otimes (Z\otimes T)$};
1195
1196 \path[commutative diagrams/.cd, every arrow, every label]
1197 (P0) edge node[swap] {$1\otimes\phi$} (P1)
1198 (P1) edge node[swap] {$\phi$} (P2)
1199 (P2) edge node {$\phi\otimes 1$} (P3)
1200 (P4) edge node {$\phi$} (P3)
1201 (P0) edge node {$\phi$} (P4);
1202 \end{tikzpicture}
1203 \end{codeexample}
1204
1205 \subsection{Issues with active characters}
1206 \label{sec:issues-with-active-ampersand}
1207
1208 By default, \tikzname{} makes the character |&| active inside
1209 matrices, and this causes the error message
1210 \begin{verse}
1211 |! Package pgfbasematrix Error: Single ampersand used with wrong catcode.|
1212 \end{verse}
1213 when |{tikzcd}| is used inside the argument to a macro such as a Beamer
1214 frame or a footnote. One solution to this problem is to call |{tikzcd}|
1215 with the option |ampersand replacement=\&|, and replace all
1216 occurrences of |&| with |\&| in the diagram. This procedure is also
1217 needed if you want to use matrices in a diagram cell or label.
1218
1219 \begin{codeexample}[/tikz/commutative diagrams/diagrams={column sep=large}]
1220 \begin{tikzcd}[ampersand replacement=\&]
1221 A \oplus B \ar[r, "{\begin{pmatrix} e & f \\ g & h \end{pmatrix}}"]
1222 \& C \oplus D
1223 \end{tikzcd}
1224 \end{codeexample}
1225
1226 An alternative fix to this issue that does not require replacing |&|
1227 with a different column separator consists in adding the following
1228 line to your document after all packages have been loaded:
1229 \begin{verse}
1230 |\def\temp{&} \catcode`&=||\active \let&=||\temp|
1231 \end{verse}
1232 However, this may interfere in unexpected ways with other
1233 packages. Use this trick at your own risk.
1234
1235 A different but related issue is that some packages, notably
1236 \texttt{babel}, modify the catcodes of certain characters in a way
1237 that may upset \tikzname's parser. To fix this, add
1238 \begin{verse}
1239 |\usetikzlibrary{babel}|
1240 \end{verse}
1241 to your document preamble.
1242
1243 \section{Additional goodies}
1244 \label{sec:general-infra}
1245
1246 This package provides some general \pgfname\ infrastructure to achieve
1247 its goals. These additional goodies are documented in this section.
1248
1249 \subsection{The \texttt{asymmetrical rectangle} shape}
1250 \label{sec:asymm-rect-shape}
1251
1252 The following shape is used inside |{tikzcd}| to ensure that arrows
1253 between nodes in the same row are perfectly horizontal, even if the
1254 nodes contain text with different heights and depths.
1255
1256 \begin{shape}{asymmetrical rectangle}
1257 This shape is similar to the |rectangle| shape, but its |center| is
1258 located at a fixed distance of the |base|, as determined by the
1259 |center yshift| key, rather than lying at the shape's geometric
1260 center. The numerical anchors, as well as |east| and |west|, are
1261 modified accordingly, and there are anchors called |real center|,
1262 |real east|, and |real west| matching |rectangle|'s original
1263 definitions. All other anchors provided by |rectangle| are
1264 available and remain unmodified.
1265 \end{shape}
1266
1267 \begin{key}{/tikz/commutative diagrams/center yshift=\meta{dimension}
1268 (initially axis\_height)}
1269 Determines the distance between |asymmetrical rectangle|'s |base|
1270 and |center| anchors.
1271 \end{key}
1272
1273 The picture below shows some of the available anchors.
1274
1275 \begin{center}\Huge
1276 \begin{tikzpicture}
1277 \node[name=s,shape=asymmetrical rectangle,shape example]
1278 {Asymmetrical rectangle\vrule width 1pt height 2cm}; \foreach
1279 \anchor/\placement in {north west/above left, north/above, north
1280 east/above right, west/left, center/right, east/right, real
1281 west/left, real center/right, real east/right, base west/left,
1282 base/right, base east/right, south west/below left, south/below,
1283 south east/below right, text/left, 10/right, 130/above,
1284 230/below, -10/below} \draw[shift=(s.\anchor)] plot[mark=x]
1285 coordinates{(0,0)} node[\placement] {\scriptsize\texttt{\anchor}};
1286 \end{tikzpicture}
1287 \end{center}
1288
1289 % This shape is used for |{tikzcd}|'s matrix cells to ensure arrows
1290 % between nodes in the same row are drawn horizontally. When
1291 % \tikzname{} draws a path between two nodes, it chooses endpoints lying
1292 % on their borders in such a way that the path points towards the
1293 % \texttt{center} of the nodes. With the \texttt{rectangle} shape, the
1294 % anchor \texttt{center} lies halfway between two nonadjacent vertices
1295 % and therefore its position depends on the height and depth of the
1296 % text, potentially causing slanted lines to be draw. The picture
1297 % above, for instance, has a humongous ascender (namely, the rule after
1298 % the word ``rectangle''), so its \texttt{real center} lies well above
1299 % its \texttt{center}.
1300
1301 \subsection{Reading font parameters}
1302 \label{sec:read-font-param}
1303
1304 The following are |pgfmath| functions used to access relevant math
1305 font parameters. They take no arguments, but the result depends of
1306 the currently selected font size.
1307
1308 \begin{math-function}{axis\_height}
1309 Returns the axis height parameter (a.k.a.\ $\sigma_{22}$) of the document's math font.
1310 \end{math-function}
1311
1312 \begin{math-function}{rule\_thickness}
1313 Returns the fraction rule thickness (a.k.a.\ $\xi_8$) of the document's math font.
1314 \end{math-function}
1315
1316 \subsection{Computer Modern arrow tips}
1317 \label{sec:comp-modern-arrow}
1318
1319 The following arrow tips mimic the Computer Modern designs. It is
1320 useful to know that at size 10\,pt, the Computer Modern arrow stems
1321 are 0.4\,pt thick; for other font sizes, scale this parameter
1322 accordingly, or set \texttt{line width=rule\_thickness}.
1323
1324 Notice that by using the mechanism explained in
1325 \S\ref{sec:changing-arrow-tips}, it is not necessary, and in fact not
1326 advisable, to directly refer to the arrow tips listed in this section
1327 inside a |{tikzcd}|.
1328
1329 \begin{multicols}{2}\raggedcolumns
1330 \begin{tabular}{ll}
1331 \displayarrow{cm to}\\
1332 \displayarrow[/tikz/commutative diagrams/double line]{cm implies}\\
1333 \displayarrow[line width=1.5*rule_thickness]{cm bold to}\\
1334 \displayarrow{cm double to}\\
1335 \displayarrow{cm to reversed}\\
1336 \end{tabular}
1337
1338 \begin{tabular}{ll}
1339 \displayarrow{cm bar}\\
1340 \displayarrow{cm left to}\\
1341 \displayarrow{cm right to}\\
1342 \displayarrow{cm left hook}\\
1343 \displayarrow{cm right hook}\\
1344 \end{tabular}
1345 \end{multicols}
1346
1347 % Incidentally, \tikzname's original \texttt{to} arrow tip seems to be
1348 % based on the pre-1992 version of Computer Modern, which, in spite of
1349 % its author's wish \cite{knuth}, can still be found in many systems.
1350 % \TeX{}Live, for instance, distributed the old version up until 2007 or
1351 % 2008. Therefore, an up-to-date \TeX{} distribution may be necessary
1352 % to get matching arrows in formulas and diagrams.
1353
1354 \subsection{Glyph arrow tips}
1355 \label{sec:font-arrow-tips}
1356
1357 As an attempt to provide a general solution to the problem of having
1358 matching arrow tips in text and pictures, this feature produces arrow
1359 tips that consist of (pieces of) font glyphs carefully placed at the
1360 endpoints of the path. To activate it in |{tikzcd}| diagrams, refer
1361 to the |arrow style| key.
1362
1363 \begin{arrowtipsimple}{Glyph}
1364 An arrow tip made from a piece of text. It accepts the following
1365 parameters.
1366
1367 \begin{key}{/pgf/arrow keys/glyph math command=\meta{name}}
1368 The name of a command (to be used inside |$\csname| \dots
1369 |\endcsname$|) producing the desired glyph.
1370 \end{key}
1371
1372 \begin{key}{/pgf/arrow keys/glyph length=\meta{dimension} (initially 1ex)}
1373 The length of the portion of the glyph not clipped away. Also used
1374 to set the `tip end' parameter.
1375 \end{key}
1376
1377 \begin{key}{/pgf/arrow keys/glyph axis=\meta{dimension} (initially axis\_height)}
1378 A vertical displacement applied to the glyph in order to make the
1379 glyph's central axis (typically an arrow stem) aligned with the
1380 path.
1381 \end{key}
1382
1383 \begin{key}{/pgf/arrow keys/glyph shorten=\meta{dimension} (initially -0.1ex)}
1384 An additional amount by which the end of the path is shortened.
1385 This is used to compensate for the gap that usually exists between
1386 the tip end and the glyph's bounding box.
1387 \end{key}
1388 \end{arrowtipsimple}
1389
1390 Below are some usage examples. Notice that glyph arrow tips do not
1391 scale with \pgfname{} line width but their size depends on the current
1392 font size, so you will probably want to set \texttt{line
1393 width=rule\_thickness} when using them. Also, contrarily to the
1394 arrow parameters defined by the \texttt{arrows.meta} library, the
1395 parameters described above are evaluated only at the time the arrow
1396 tip is drawn, so they can (and should) be given in the units em or ex.
1397
1398 \begin{codeexample}[]
1399 \tikzset{
1400 math to/.tip={Glyph[glyph math command=rightarrow]},
1401 loop/.tip={Glyph[glyph math command=looparrowleft, swap]},
1402 weird/.tip={Glyph[glyph math command=Rrightarrow, glyph length=1.5ex]},
1403 pi/.tip={Glyph[glyph math command=pi, glyph length=1.5ex, glyph axis=0pt]},
1404 }
1405
1406 \begin{tikzpicture}[line width=rule_thickness]
1407 \draw[loop-math to, bend left] (0,2) to (1,2);
1408 \draw[math to-weird] (0,1) to (1,1);
1409 \draw[pi-pi] (0,0) to (1,0);
1410 \end{tikzpicture}
1411 \end{codeexample}
1412
1413 It is important to be aware of some drawbacks of this feature. First,
1414 the transition between a line and the arrow tip may become visible
1415 with some printers (especially in low resolutions or draft mode) and
1416 document viewers, as you may be able to see in the samples above.
1417 Second, these rather long tips may
1418 (\tikz[baseline=-axis_height]\draw[dash pattern=on 0.8ex off
1419 0.4ex,-{Glyph[glyph math command=rightarrow]}] (0,0) -- (3.4ex,0);) or may
1420 not (\tikz[baseline=-axis_height]\draw[dash pattern=on 0.8ex off
1421 0.4ex,-{Glyph[glyph math command=rightarrow]}] (0,0) -- (4ex,0);) fit
1422 nicely with dashed or curved lines. Finally, the method used to place
1423 the arrow tip at the end of a stroked path and clip away the arrow
1424 stem makes certain assumptions about the font design and could fail in
1425 cases where unusual design choices are made.
1426
1427 \begin{thebibliography}{9}
1428 \bibitem{milne}
1429 James Milne,
1430 \emph{Guide to commutative diagrams}.
1431 Available at \url{http://www.jmilne.org/not/CDGuide.html}.
1432 \bibitem{pgfman}
1433 Till Tantau,
1434 \emph{The \tikzname{} and \pgfname{} packages: Manual for version 3.1.9}.
1435 Available at \url{http://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf}.
1436 \end{thebibliography}
1437
1438 \printindex
1439
1440 \end{document}
1441
1442 %%% Local Variables:
1443 %%% mode: tex
1444 %%% mode: auto-fill
1445 %%% TeX-engine: luatex
1446 %%% End: