\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath,tikz-cd}
\usepackage{pgfmanualstyle}
\usepackage{hyperref}

\hypersetup{pdftitle={The tikz-cd package},
            pdfauthor={Florêncio Neves},
            pdfkeywords={commutative diagrams, latex, tikz, pgf},
            colorlinks
           }
           
\title{The \texttt{tikz-cd} package}
\author{\normalsize Florêncio Neves\footnote{\emph{E-mail:} \href{mailto:florencioneves@gmail.com}{\texttt{florencioneves@gmail.com}}}}
\date{\normalsize Version 0.1\footnote{\color{red}This is a preliminary version.  Future versions may not be backwards-compatible.  Comments are welcome.}}

\makeatletter
\definecolor{graphicbackground}{rgb}{0.96,0.96,0.8}
\def\tikzcd@bgcolor{graphicbackground}
\makeatother

\newcommand{\displayarrow}[2][]{\texttt{#2} & yelds \tikz[baseline=-2.5pt] \draw[#2-#2, line width=0.44pt, #1] (0,0) -- (1,0);}
\newcommand{\displayarrowstyle}[2][]{\texttt{#2} & yelds \tikz[baseline=-2.5pt] \draw[/commutative diagrams/current arrows, #2, #1] (0,0) -- (0.4,0);}

\begin{document}
\maketitle

The general-purpose drawing package \tikzname{} 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 purpose of this package is to make the process of
creation of such diagrams easier by providing a convenient set of
macros and reasonable default settings.  This package also includes an
arrow tip library that match closely the arrows present in the
Computer Modern typeface.

PGF version 2.10 is required.

\tableofcontents

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

Commutative diagrams are created with the |tikzcd| environment.  Its
content describes a matrix, like 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 an
|equation| environment or inside |\[ \]|, so that the diagram will be
placed on a new line and centered.

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

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

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

If you want to save typing, the command |\ar| is provided as a
shortcut to |\arrow|.  There are also commands |\lar|, |\rar|, |\uar|
and |\dar|, that act like |\arrow{l}|, |\arrow{r}| and so forth.  They
can take up to three optional argument:\ one in square braces to
control the arrow, one in square braces to control the label, and one
in curly braces to specify a label.  Thus, the previous diagram can be
rewritten as follows.
\begin{codeexample}[]
\begin{tikzcd}
  A \lar{\psi} \dar[color=red]
        & B \dar[color=red]{\psi} \\
  C \lar[color=red][color=blue]{\eta}
        & D
\end{tikzcd}
\end{codeexample}

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

If you are familiar with \tikzname, you certainly noticed that you can
produce different kids of arrows by passing arguments like |right hook->|
to the |\arrow| command.  This package provides an alternative
way of doing this.  Namely, there are styles named after \LaTeX{}
arrow producing commands for this purpose.  Thus, instead of
|\arrow[right hook->]{l}|, you can use |\arrow[hookrightarrow]{l}|, as
in the example below.
\begin{codeexample}[]
  \begin{tikzcd}
    X \arrow[hookrightarrow]{l} \arrow[dashed]{ld}
                          & \bar{X} \arrow{d}\\
                          & Y
  \end{tikzcd}
\end{codeexample}

The complete list of arrow types available so far is given below.  It
will be made comprehensive in the future.

\begin{tabular}{ll}
  \displayarrowstyle{rightarrow}\\
  \displayarrowstyle{leftarrow}\\
  \displayarrowstyle{hookrightarrow}\\
  \displayarrowstyle{hookleftarrow}\\
  \displayarrowstyle{hookrightarrow}\\
  \displayarrowstyle{rightharpoonup}\\
  \displayarrowstyle{rightharpoondown}\\
  \displayarrowstyle{leftharpoonup}\\
  \displayarrowstyle{leftharpoondown}\\
\end{tabular}

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

In the future, a customization scheme using |pgfkeys| will be implemented.  For now, you can change the appearance of diagrams by understanding some of |tikz-cd|'s internals.  The |tikzcd| environment generates codes with the following basic structure:
\begin{codeexample}[code only]
  \begin{tikzpicture}[ ... ]
    \matrix (m) [ ... ] {
        &  ... & \\
        &  ... & \\};
    \path[ ... ] ...;
  \end{tikzpicture}
\end{codeexample}
There are styles
\begin{quote}
|/commutative diagrams/picture style|,\\
|/commutative diagrams/matrix style|, and\\
|/commutative diagrams/path style|\\
\end{quote}
that are applied at the relevant places.  By appending things to these styles, you can control the behavior of diagrams quite arbitrarily.  The arrow tip styles are stored in |/commutative diagrams/current arrows|.


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

By using the mechanism explained in \S\ref{sec:changing-arrow-tips}, it is not necessary to know the technical details in this section.

The naming scheme of the Computer Modern-like arrow tips provided by this package follows that of |pgf|'s |arrows| library, as described in Section 23 of the |pgf| manual.  You can of course use these arrow tips outside the |tikzcd| environment; in this case, you will probably want to know that in order to match the Computer Modern font at size $10\,\mathrm{pt}$, it is necessary to set \texttt{line width} to $0.4\,\mathrm{pt}$; for larger font sizes, scale this parameter accordingly.


\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`\|} & yelds \tikz[baseline=-2.5pt] \draw[cm |-cm |, line width=0.44pt] (0,0) -- (1,0);\\
  \displayarrow{cm o}\\
  \displayarrow{cm *}\\
  \displayarrow{cm 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}

\section{Some examples}
\label{sec:some-examples}

The following example is taken from \cite{milne}.
\begin{codeexample}[]
\begin{tikzcd}
  T
  \arrow[bend left]{dll}{x}
  \arrow[bend right]{ddl}{y}
  \arrow[dotted]{dl}[description]{(x,y)} & & \\
      & X \times_Z Y \arrow{l}{p} \arrow{d}{q} & X \arrow{d}{f} \\
      & Y \arrow{l}{g}                         & Z
\end{tikzcd}
\end{codeexample}

\begin{thebibliography}{9}
\bibitem{lenders}
  Felix Lenders,
  \emph{Commutative diagrams using TikZ}.
  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}.
\end{thebibliography}
\end{document}
