tikz-cd (18jul12)

git-svn-id: svn://tug.org/texlive/trunk@27194 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 123 insertions, 53 deletions

diff --git a/Master/texmf-dist/doc/latex/tikz-cd/tikz-cd-doc.tex b/Master/texmf-dist/doc/latex/tikz-cd/tikz-cd-doc.tex
index 3acee948f03..c90e94e132d 100644
--- a/Master/texmf-dist/doc/latex/tikz-cd/tikz-cd-doc.tex
+++ b/Master/texmf-dist/doc/latex/tikz-cd/tikz-cd-doc.tex
@@ -237,7 +237,7 @@
             \ifx\mathtest\pgfmanualemptytext%
             \index{#2#3@\protect\texttt{#2\protect\ #3} #4 math operators}% 
             \index{Math operators!#2#3@\protect\texttt{#2\protect\ #3}}%
-            \fi%
+vv            \fi%
             \pgfmanualbody
           }
           {\end{pgfmanualentry}}
@@ -1328,12 +1328,13 @@
            
 \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.2b, of March 18, 2012}
+\date{\normalsize Version 0.2c, of July 17, 2012}
 
 \tikzset{commutative diagrams/background color=graphicbackground}
 
 \newcommand{\displayarrow}[2][]{\texttt{#2} & yelds \tikz[baseline=-2.5pt] \draw[#2-#2, line width=0.0929ex, #1] (0,0) -- (1,0);}
-\newcommand{\displayarrowstyle}[2][]{\texttt{#2} #1 & yelds \tikz[baseline=-2.5pt] \draw[commutative diagrams/.cd, #2] (0,0) -- (0.6,0);}
+\newcommand{\displayarrowstyle}[2][]{\texttt{#2} #1 & yelds
+  \tikz[baseline=-\tikzcdaxisheight, line width=\tikzcdrulethickness] \draw[commutative diagrams/.cd, #2] (0,0) -- (0.6,0);}
 
 \begin{document}
 \maketitle
@@ -1358,7 +1359,7 @@ arrows present in the Computer Modern typeface.
 \label{sec:basic-usage}
 
 Commutative diagrams are created with the |tikzcd| environment.  Its
-content describes a matrix, like the |\matrix| command in \tikzname{}
+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 an
 |equation| environment or inside |\[| \dots |\]|, so that the diagram is
@@ -1394,7 +1395,7 @@ passed to \tikzname's |node| operator.
 \end{tikzcd}
 \end{codeexample}
 
-An arrow can actually have an arbitrary number of labels, each one
+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.
 
@@ -1414,7 +1415,7 @@ specifiers of the form |{|\meta{text}|}| or
 Thus, the diagram above can be rewritten as follows.
 \begin{codeexample}[]
 \begin{tikzcd}
-  A \rar{\psi} \dar[color=red]
+  A \drar \rar{\psi} \dar[color=red]
         & B \dar[][color=red]{\psi} \\
   C \rar[color=red][color=blue]{\eta}
         & D
@@ -1452,13 +1453,13 @@ corresponding option (without a ``|\|'') that can be passed to
 \end{codeexample}
 
 Of course, a similar effect could be achieved by directly using
-\tikzname's arrow tip selection scheme (e.g., using the option
-|right hook->|).  However, the method more above is more appropriate, as it
+\tikzname{} options (e.g., using the option
+|right hook->|).  However, the method 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 probably also
 better from the mnemonic standpoint.
 
-The following list shows all arrow styles available.
+The following list shows all available arrows.
 
 {\tikzset{commutative diagrams/.cd, background color=white}
   \begin{quote}
@@ -1574,7 +1575,7 @@ stores a
   set.  If the key above is not initialized, then \meta{size} is
   presumably a dimension, and |/tikz/row sep|=\meta{size} is set.
 
-  The values of \meta{size} initially available, and their values, are
+  The initially available \meta{size}'s, and their values, are
   the following:
   \begin{center}
     \begin{tabular}{cccccc}
@@ -1623,7 +1624,29 @@ too tall if the column or row separation were not set appropriately.
   A \arrow{ur}\arrow{dr} &                          \\
                          & C
 \end{tikzcd}
-  
+\end{codeexample}
+
+The commands below are available only inside a |tikzcd| and are
+intended to be used as arguments to |&| and |\\| when spacing
+adjustments are necessary.
+\begin{command}{\colsep\marg{size}}
+  Returns the value
+  stored in by the key |/tikz/commutative diagrams/column sep/|\meta{size}.
+\end{command}
+\begin{command}{\rowsep\marg{size}}
+  Returns the value
+  stored in by the key |/tikz/commutative diagrams/row sep/|\meta{size}.
+\end{command}
+
+In the following example, $X$ would appear too far from the square
+without any spacing adjustment.
+\begin{codeexample}[]
+\begin{tikzcd}
+  X \ar[bend right]{rdd} \ar[bend left]{rrd} \ar[dashed]{dr}
+    &[\colsep{small}-\colsep{normal}]  & \\[\rowsep{small}-\rowsep{normal}]
+    & A \ar{r}\ar{d}                   & B \ar{d} \\
+    & C \ar{r}                         & D
+\end{tikzcd}
 \end{codeexample}
 
 \begin{key}{/tikz/commutative diagrams/math mode=\meta{boolean}
@@ -1645,7 +1668,7 @@ too tall if the column or row separation were not set appropriately.
 
 Besides the options and styles provided by this package, there are
 several options defined by \tikzname{} that are useful for arrows, such
-as |dashed|, |dotted| and its relatives, |line width=|\meta{dimension}, |color=|\meta{color},
+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{pgfman}.
 
@@ -1690,10 +1713,12 @@ 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=1pt}}
+  diagrams={>=open triangle 45, line width=\tikzcdrulethickness}}
   
 \begin{tikzcd}
   A \arrow{r} \arrow{d} & B \arrow{d}\\
@@ -1706,8 +1731,7 @@ should be instructive.
   This style specifies at which anchor of the current node an arrow
   should start.  The default behavior is not to specify an anchor,
   causing the arrow to start at the point in the boundary of the
-  current node closest to the destination, as explained in
-  \pgfname{} manual~\cite{pgfman}.
+  current node closest to its target.
 \end{key}
 
 \begin{key}{/tikz/commutative diagrams/end anchor=\meta{anchor}
@@ -1743,7 +1767,7 @@ use of \texttt{end anchor} and \texttt{start anchor}.
 
 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 following picture, from \cite{lenders}, illustrates this.
+The following picture, adapted from \cite{lenders}, illustrates this.
 
 \begin{codeexample}[]
 \begin{tikzcd}[row sep=scriptsize, column sep=scriptsize]
@@ -1760,6 +1784,10 @@ The following picture, from \cite{lenders}, illustrates this.
   under a |crossing over| arrow.
 \end{key}
 
+\begin{command}{\tikzcdrulethickness}
+  This macro returns the value (in ex) of the math font default rule
+  thickness.
+\end{command}
 
 \subsection{Options for labels}
 \label{sec:options-labels}
@@ -1770,11 +1798,10 @@ 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 \pgfname{} manual~\cite{pgfman}.
+  command}, |text width=|\meta{dimension}, etc.  See the \pgfname{} manual~\cite{pgfman}.
 
 \begin{stylekey}{/tikz/commutative diagrams/every label}
-  This style works as if it were applied to the optional argument
-  corresponding to each label attached to an arrow.  Initially is set
+  This style is applied to every label produced with |\arrow|.  It is initially set
   to the following:
 
 \begin{quote}\ttfamily{}
@@ -1786,9 +1813,9 @@ to the default), |sloped|, |pos=|\meta{fraction}, |near start|,
 \end{stylekey}
 
 The style |auto| makes the label be placed to the left of the
-arrow, understanding ``front'' as the direction the arrow points at.
-The dimension |inner sep| controls the distance between the
-arrow and the label.
+arrow, considering ``front'' as the direction the arrow points at.
+The dimension |inner sep| controls the distance between an
+arrow and its labels.
 
 \begin{key}{/tikz/commutative diagrams/labels=\meta{options}}
   This key appends \meta{options} to the style
@@ -1850,11 +1877,11 @@ commands |\arrow|, |\ar|, |\rar|, |\lar|, |\dar|, |\uar|, |\urar|,
 |\ular|, |\drar|, |\dlar|.
 
 Initially, \meta{paths} is empty.  The command
-|\arrow[|\meta{options}|]{|\meta{direction}|}| does nothing at the
+|\arrow[|\meta{path options}|]{|\meta{direction}|}| does nothing at the
 point it is inserted, and causes the following code to be added to
 \meta{paths}:
 \begin{quote}
-  |\path[commutative diagrams/every arrow, |\meta{options}|] (|%
+  |\path[commutative diagrams/every arrow, |\meta{path options}|] (|%
   \meta{current node}|) to |\meta{labels}| (|\meta{target~node}|);|
 \end{quote}
 
@@ -1874,15 +1901,17 @@ string
 \end{quote}
 to be appended to \meta{labels}.  Dollars signs surround \meta{label
   text} depending on the setting \texttt{commutative diagrams/math
-  mode}.  For the abbreviated form |\rar| (and similarly for |\dar|,
+  mode}.
+
+For the abbreviated form |\rar| (and similarly for |\dar|,
 |\lar|, etc.), the following are valid usages:
 \begin{quote}
   |\rar{|\meta{label text}|}|\meta{more labels},\\
-  |\rar[|\meta{options}|]{|\meta{label text}|}|\meta{more labels}, or\\
-  |\rar[|\meta{options}|][|\meta{label options}|]{|\meta{label
+  |\rar[|\meta{path options}|]{|\meta{label text}|}|\meta{more labels}, or\\
+  |\rar[|\meta{path options}|][|\meta{label options}|]{|\meta{label
       text}|}|\meta{more labels}.
 \end{quote}
-Their effects are entirely analogous.
+Their effect is entirely analogous to the above.
 
 \subsection{Tweaking \texttt{to} paths}
 \label{sec:tweaking-to-paths}
@@ -1891,7 +1920,7 @@ Recall that the |to| path operation used in the paths created by
 |\arrow| can take a number of options, as described in \S{}14.14
 and \S{}51 of the \pgfname{} manual~\cite{pgfman}.  In particular, the
 option |/tikz/to path| determines the path that is actually drawn, and
-can be used to do all sorts of tweaking.
+can be used to do all sorts of fiddling.
 
 \begin{codeexample}[]
 \begin{tikzcd}
@@ -1917,13 +1946,14 @@ in a way that, in the terminology of the previous section,
 \subsection{The \texttt{asymmetrical rectangle} shape}
 \label{sec:asymm-rect-shape}
 
-The shape \texttt{asymmetrical rectangle}, defined by this package, is
+The \texttt{asymmetrical rectangle} shape, defined by this package, is
 very similar to the \texttt{rectangle} shape, except that its
 \texttt{center} anchor is not located at the geometric center of the
 shape, but rather right above the \texttt{base} anchor, at a distance
-that can be specified by the following key:
+that can be specified by the following key, which is initially set to
+|\tikzcdaxisheight|.
 
-\begin{key}{/tikz/commutative diagrams/center shift=\meta{dimension} (initially 0.575ex)}
+\begin{key}{/tikz/commutative diagrams/center shift=\meta{dimension}}
 \end{key}
 
 The picture below shows some of the available anchors.  All anchors
@@ -1933,8 +1963,8 @@ 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}
-  \begin{tikzpicture}\Huge
+\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
@@ -1949,13 +1979,17 @@ the numerical anchors.  The anchors \texttt{real center}, \texttt{real
 
 This shape is used in the matrix cells inside the \texttt{tikzcd}
 environment to ensure arrows between nodes in the same row are drawn
-horizontally.  Roughly speaking, when \tikzname{} draws a path between
+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 those nodes.  With
+that the path points towards the \texttt{center} of these 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.
 
+\begin{command}{\tikzcdaxisheight}
+  This macro returns the value (in ex) of the math font axis height.
+\end{command}
+
 \subsection{Drawing diagrams directly with Ti\emph{k}Z}
 \label{sec:draw-diagr-directly}
 
@@ -2001,10 +2035,9 @@ how this can be done (the second one is adapted from \cite{milne}).
 
 The naming scheme of the Computer Modern-like arrow tips provided by
 this package parallels that of \pgfname's |arrows| library, documented
-in \S{}23 of \pgfname{} manual~\cite{pgfman}.  To match the Computer Modern
+in \S{}23 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 esoteric
-figure 0.0929\,ex.
+larger font sizes, scale this parameter accordingly, or use the macro |\tikzcdrulethickness|.
 
 Notice that by using the mechanism explained in
 \S\ref{sec:changing-arrow-tips}, it is not necessary, and in fact not
@@ -2012,7 +2045,7 @@ advisable, to directly use 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 the
+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
@@ -2042,7 +2075,6 @@ to get matching arrows in formulas and diagrams.
   \displayarrow{cm right hook}\\
 \end{tabular}
 
-
 \item[Double arrow tips]\ \\
 \begin{tabular}{ll}
   \displayarrow{cm double to}\\
@@ -2058,29 +2090,67 @@ to get matching arrows in formulas and diagrams.
 \end{tabular}
 \end{description}
 
-% \section{Some examples}
-% \label{sec:some-examples}
+\section{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, and it may conflict with
+  future versions of \pgfname.}
+
+As an attempt to provide a general solution to the problem of having
+matching arrow tips in text and in pictures, this feature produces
+arrow tips that consist of (pieces of) characters carefully placed at
+the endpoints of a path.  To activate it in |tikzcd| diagrams, use
+\begin{center}
+  |\tikzset{commutative diagrams/arrow style=math font}|.
+\end{center}
+It is also necessary to load |amssymb| or some other package defining
+the symbols corresponding to the arrow tips you want to use.
+
+The above option 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
+currently selected font size, so you will probably want to set
+\texttt{line width=}|\tikzcdrulethickness| 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=-\tikzcdaxisheight]
+  \draw[math cap-math to, line width=\tikzcdrulethickness] (0,0) -- (1,0);
+  \hspace{1cm}
+  Other \TeX{} engines
+  \makeatletter\def\tikzcd@arrowset{\tikzcd@arrowset@generic}\makeatother
+  \tikz[baseline=-\tikzcdaxisheight]
+  \draw[math cap-math to,line width=\tikzcdrulethickness] (0,0) -- (1,0);
+\end{center}
 
-% \begin{codeexample}[]
-%   \begin{tikzcd}[row sep=small]
-%     H^i(A) \rar & H^i(B) \rar & H^i(C) \arrow[out=0, in=180]{dll}\\
-%     H^{i+1}(A) \rar & H^{i+1}(B) \rar & H^{i+1}(C)
-%   \end{tikzcd}
-% \end{codeexample}
+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.
 
 \section{Change history}
 \label{sec:change-history}
 
 \begin{description}
+\item[Version 0.2c] (July 2012) Added |\tikzcdrulethickness|,
+  |\tikzcdaxisheight|, |\colsep|, |\rowsep|.  Added experimental font arrows.
 \item[Version 0.2b] (March 2012) Added \texttt{asymetrical rectangle} shape.
 \item[Version 0.2a] (December 2011)
-  \begin{itemize}
-  \item Option |/tikz/commutative diagrams/path operation| removed
+  Option |/tikz/commutative diagrams/path operation| removed
     in favor of direct use of |/tikz/to path|.
-  \item Double lines with |tikz| arrow style now use \texttt{double
+  Double lines with |tikz| arrow style now use \texttt{double
       equal sign distance}.
-  \end{itemize}
 \item[Version 0.2] (October 2011) Several changes.
 \item[Version 0.1] (September 2011) Preliminary release. 
 \end{description}