% pb-manual.tex: user's manual for pb-diagram.sty macros
% Author: Paul Burchard <burchard@pobox.com>
% Version Number: 5.0
% Version Date: 20 Oct 1998
% 
% Copyright (c) 1990, 1992, 1995, 1998 by Paul Burchard
%
%	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 2 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, write to the Free Software
%	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%
\def\tooee{LaTeX2e}
\ifx\fmtname\tooee
   \documentclass[12pt]{article}\usepackage{pb-diagram}
\else
   \documentstyle[12pt,pb-diagram]{article}
\fi
\def\diagramversion{5.0}
\title{User's Guide to the Diagram Environment,
   Version \diagramversion}
\author{Paul Burchard (burchard@pobox.com)}
\def\tfrac#1#2{{\textstyle\frac{#1}{#2}}}
\begin{document}
\maketitle

\section{Introduction}

The \verb"diagram" environment allows the
\ifx\fmtname\tooee\LaTeXe\else\LaTeX\fi{} user to easily
create complex commutative diagrams, by placing formula nodes
on a conceptual grid and attaching arrows to them.

The grid used in these diagrams is not a fixed square grid.
Instead, the environment automatically generates a correctly scaled
and shaped rectangular grid which will compactly hold the formulas,
while leaving room for the arrows between them.  Moreover, the
arrows automatically adapt to the spaces between the formulas
being connected.  These features are accomplished with a
three-pass algorithm that takes into account the width
and height of every formula.

The arrows in these diagrams are quite flexible.
Arrows may, in any combination,
\begin{itemize}
 \item point in any of a large number of lattice directions;
 \item span multiple rows and columns of the grid;
 \item cross other arrows;
 \item have labels on either or both sides,
    with adjustable positioning;
 \item have a variety of head, tail, and shaft styles.
\end{itemize}
The fancier arrow styles are made possible by special fonts,
either from Xy-pic or {\sc LamS}-\TeX, but the package can be used
without them if necessary.

\pagebreak[3]
To get a feel for how the package works, here are some examples of
commands for producing arrows:
\begin{flushright}
%
% Catcode hack to get typewriter `\' `{' `}' inside arg of command
% where \verb is illegal.
\begingroup
   \catcode`|=0 \catcode`[=1 \catcode`]=2
   \catcode`\{=12 \catcode`\}=12 \catcode`\\=12
   |gdef|bbb[\]|gdef|lll[{]|gdef|rrr[}]%
|endgroup
\def\ttt{\ifx\fmtname\tooee\fontfamily{cmtt}\selectfont\else\tt\fi}%
%
% tighten it up a bit to fit on page in 12pt
\setlength{\dgARROWLENGTH}{1.5em}%
\noindent
$\begin{diagram}
      \node{\makebox[0pt][r]{\ttt\bbb arrow\lll e\rrr \quad}+}
         \arrow{e} \node{+} \node{+} \node{+} \node{+} \\
      \node{+} \arrow{s,lr}{\makebox[0pt][r]{\ttt\bbb
         arrow\lll s,lr\rrr\lll\bbb alpha\rrr\lll\bbb beta\rrr\quad}
           \alpha}{\beta}
         \node{+} \node{+} \node{+} \node{+} \\
      \node{+} \node{+} \node{+} \node{+} \node{+} \\
      \node{\makebox[0pt][r]{\ttt\bbb
               arrow[2]\lll ene,t,3,..\rrr\lll f\_0\rrr\quad}+}
         \arrow[2]{ene,t,3,..}{f_0} \node{+}
               \node{+} \node{+} \node{+}
\end{diagram}$
\end{flushright}
And here is a simple example diagram:
\[
   \begin{diagram}
     \node{A} \arrow{e,t}{a} \arrow{s,l}{c} \arrow{ese}
       \node{B^*} \arrow{e,t}{b^*}
         \node{C} \arrow{s,r}{d} \arrow{wsw} \\
     \node{D} \arrow[2]{e,b}{e} \node[2]{E}
   \end{diagram}
\]
\begin{verbatim}
   \[
   \begin{diagram}
     \node{A} \arrow{e,t}{a} \arrow{s,l}{c} \arrow{ese}
       \node{B^*} \arrow{e,t}{b^*}
         \node{C} \arrow{s,r}{d} \arrow{wsw} \\
     \node{D} \arrow[2]{e,b}{e} \node[2]{E}
   \end{diagram}
   \]
\end{verbatim}

\pagebreak[4]
\section{Loading the Diagram Package}

To use the \verb"diagram" environment, begin your
\ifx\fmtname\tooee\LaTeXe\else\LaTeX2e\fi{} file with:
\begin{verbatim}
   \documentclass{DOCSTYLE}\usepackage{pb-diagram}
\end{verbatim}
where \verb"DOCSTYLE" is your document style (e.g.,
\verb"article").  The style file \verb"pb-diagram.sty" needs to
be placed in one of your system's \TeX{} input directories.

If you are using older versions of \LaTeX{} (2.09 or older), then
you would begin instead with:
\begin{verbatim}
   \documentstyle[pb-diagram]{DOCSTYLE}
\end{verbatim}

If you have {\em METAFONT\/} available on your system,
and would like to make use of the additional features
of the Xy-pic fonts (highly recommended!), then you should
instead begin your
\ifx\fmtname\tooee\LaTeXe\else\LaTeX2e\fi{} file with:
\begin{verbatim}
   \documentclass{DOCSTYLE}
   \usepackage[cmtip,arrow]{xy}
   \usepackage{pb-diagram,pb-xy}
\end{verbatim}
This option requires that you have Xy-pic installed on your
system.  Xy-pic is available from your nearest CTAN archive
(e.g. {\tt http://ctan.tug.org/}) in the CTAN directory
{\tt macros/generic/diagrams/xypic/}.

An alternative set of fonts which enables some of the
fancier features is the {\sc LamS}-\TeX{} font set; to
use it, begin your
\ifx\fmtname\tooee\LaTeXe\else\LaTeX2e\fi{} file with:
\begin{verbatim}
   \documentclass{DOCSTYLE}
   \usepackage{pb-diagram,lamsarrow,pb-lams}
\end{verbatim}
This option requires the {\em METAFONT\/} source files
\verb"lams1.mf" through \verb"lams5.mf" to be installed.

Installation of additional fonts is system-dependent,
but will involve moving the \verb".mf" files into the system's
{\em METAFONT\/} input directory, and then running the
{\em METAFONT\/} program.  This program will generate the
\verb".tfm" files required for \TeX, and the \verb".pk" or
\verb".gf" files required for printing and previewing.
On {\sc unix} systems, the relevant files are typically
located in \verb"/usr/lib/mf" and \verb"/usr/lib/tex", or 
\verb"/usr/local/lib/mf" and \verb"/usr/local/lib/tex".

If you are having troubling getting \LaTeX{} to properly
process an older paper which uses this package, check the
later section, ``Upgrading Papers from Previous Versions.''

\pagebreak[4]
\section{Using the Diagram Environment}
\subsection{Overall Structure of the Environment}

The \verb"diagram" environment should be used in
{\em math mode only}.  Its usage is as follows:\footnote{For
compatibility reasons, the diagram environment accepts and
optional argument.  When this argument is supplied, the grid
geometry is calculated in exactly the same way as in version~1.0
of this package. Therefore, manuscripts written with version~1.0
require no changes to be processed with version~\diagramversion.}
\begin{verbatim}
   \begin{diagram}
      NODE ARROW ARROW ... NODE ARROW ARROW ... .... \\
      NODE ARROW ARROW ... NODE ARROW ARROW ... .... \\
      ...
      NODE ARROW ARROW ... NODE ARROW ARROW ... ....
   \end{diagram}
\end{verbatim}

Each \verb"NODE" places a centered formula at a new grid point, and
each \verb"ARROW" which follows this \verb"NODE" (but precedes the 
next \verb"NODE") will be attached by its tail to the same grid 
point. The diagram will be automatically be given a geometry which 
accomodates these elements, but you can also fine-tune it afterwards 
by hand if it didn't turn out like you imagined
(see the section on ``Fine-Tuning'' below).  We now explain
how to specify the \verb"NODE"s and \verb"ARROW"s.

\subsection{Formula Nodes}

A \verb"NODE" is specified by the comand:
\begin{verbatim}
   \node[NCOLS]{FORMULA}
\end{verbatim}
where the optional argument \verb"NCOLS" tells how many grid columns 
to move forward from the previous node (the default is 1).  The 
\verb"FORMULA" is the math mode material which you want to place at 
that node in the grid.

The \verb"\\" command moves to the next grid row.  As is usual in 
\LaTeX{} arrays, the final row should not end with a \verb"\\", and 
any blank columns at the end of a row need not be entered.  More 
generally, it is possible to move \verb"NROWS" rows down at once 
using the command:
\begin{verbatim}
   \\[NROWS]
\end{verbatim}

\subsection{Arrows and their Embellishments}

An \verb"ARROW" is specified by the \verb"\arrow" command, which may 
also be used anywhere in math mode, independent of the
\verb"diagram" environment.  Its usage depends on the number of 
labels desired:
\begin{verbatim}
   \arrow[SIZE]{DIRECTION,OPTIONS}
   \arrow[SIZE]{DIRECTION,ONELABEL,OPTIONS}{LABEL}
   \arrow[SIZE]{DIRECTION,TWOLABEL,OPTIONS}{LABEL1}{LABEL2}
\end{verbatim}
The commas should not have any spaces before or after them, and there 
should not be any extra spaces or commas at the beginning or end of 
the list.  The optional integer argument \verb"SIZE" tells how many 
times its normal length the arrow should be made.  For example, 
\verb"\arrow[2]{e}" will span two columns, while \verb"\arrow[2]{s}" 
will span two rows.

The arrow \verb"DIRECTION" may be chosen from the compass point 
directions:  
\begin{verbatim}
   n,e,s,w,ne,nw,se,sw,nne,nnw,sse,ssw,ene,ese,wnw,wsw
\end{verbatim}
If the \verb"pb-lams" style has been loaded, the \verb"DIRECTION"
may also be chosen from this list:
\begin{verbatim}
   nee,see,nww,sww,
   neee,nnne,nnnw,nwww,swww,sssw,ssse,seee,
   nnnee,nnnww,sssww,sssee,nneee,nnwww,sswww,sseee
\end{verbatim}
(For more information about arrow directions, see the sections
on ``Fine Tuning'' and ``Customizing'' below.)

Any \verb"LABEL"s present are math mode material.  The 
\verb"ONELABEL" specifier may be chosen from:
\begin{tabbing}
   {\tt xxx}\={\tt x}\qquad\=\kill
   \>{\tt t}\> top\\
   \>{\tt b}\>  bottom\\
   \>{\tt l}\>  left (only for use with vertical arrows)\\
   \>{\tt r}\>  right (only for use with vertical arrows)
\end{tabbing}
The \verb"TWOLABEL" specifier may be chosen from:
\begin{tabbing}
   {\tt xxx}\={\tt x}\qquad\=\kill
   \>{\tt tb}\>  top and bottom\\
   \>{\tt lr}\>  left and right (only for use with vertical arrows)
\end{tabbing}

The \verb"OPTION"s describe the style of the arrow shaft, the symbols 
to be used at the head and tail of the arrow, and the positions of 
the labels.  The defaults are: a simple line shaft, a single simple 
arrowhead, no special tail symbol, and labels positioned at the 
midpoint of the arrow shaft.  The \verb"OPTION"s may be selected from 
the lists which follow.  Most of the options can be combined with 
others; however, not all combinations make sense.  In addition,
options marked with~(*) are only available with 
either \verb"pb-xy" or \verb"pb-lams" loaded;
and options marked with~(**) are only available with \verb"pb-xy" loaded.
Shaft options are:
\begin{tabbing}
   {\tt xxx}\={\tt x}\qquad\=\kill
   \>{\tt ..}\> dotted or dashed arrow shaft\\
   \>{\tt =}\>  double line shaft* (``equals sign'')\\
   \>{\tt !}\>  invisible arrow shaft
\end{tabbing}
Arrow head options are:
\begin{tabbing}
   {\tt xxx}\={\tt x}\qquad\=\kill
   \>{\tt -}\>  no arrow heads\\
   \>{\tt <>}\> arrow heads on both ends\\
   \>{\tt A}\>  double arrow head*\\
   \>{\tt '}\>  left half of arrow head*\\
   \>{\tt `}\>  right half of arrow head*
\end{tabbing}
Arrow tail options are:
\begin{tabbing}
   {\tt xxx}\={\tt x}\qquad\=\kill
   \>{\tt V}\>  single arrow tail*\\
   \>{\tt J}\>  left fish hook arrow tail*\\
   \>{\tt L}\>  right fish hook arrow tail*\\
   \>{\tt S}\>  squiggle arrow tail*\\
   \>{\tt T}\>  ``mapsto'' arrow tail**
\end{tabbing}
In the default configuration, the label positioning options are:
\begin{tabbing}
   {\tt xxx}\={\tt x}\qquad\=\kill
   \>{\tt 1}\>  1/4 of way from tail end\\
   \>{\tt 2}\>  2/4 of way from tail end (the default)\\
   \>{\tt 3}\>  3/4 of way from tail end
\end{tabbing}
However, if more flexibility is needed, there is an
\verb"ARROWPARTS" parameter which specifies how many pieces the arrow 
will be divided into to determine the meaning of the label 
positioning option.  (In general, the positioning option may be any
single digit.)  For example, to position a label 5/6 of the way from
the tail end of the arrow, you would use commands like these:
\begin{verbatim}
   \dgARROWPARTS=6
   \begin{diagram}
      ... \arrow{e,t,5}{MYLABEL} ...
   \end{diagram}
\end{verbatim}
\verb"ARROWPARTS" should be even, so that ordinary labels can
be properly positioned at the half-way point.


\section{Fine Tuning the Diagrams}

Many of the parameters used by the \verb"diagram" environment are 
accessible to you and documented here so that the existing features 
can be fine-tuned.

The most important parameter is \verb"\dgARROWLENGTH", which 
specifies the minimum length for all arrows.  The \verb"diagram"
environment will independently adjust the horizontal and vertical
scales of its rectangular grid until at least that much room is
available for each arrow.  This calculation takes into account
the room that must be set aside for the each of the two formulas
being connected by an arrow.  The default minimum arrow length is
\begin{verbatim}
   \dgARROWLENGTH=2.5em
\end{verbatim}
The \verb"\arrow" command may also be used outside of the diagram
environment; in that case, its length is instead controlled by
the parameter
\begin{verbatim}
   \dgTEXTARROWLENGTH=1.1em
\end{verbatim}

Some anomalies you may encounter: the collision of formulas is not
checked unless an arrow connects them.  Therefore, if two formulas
turn out to overlap you can just connect them with an invisible arrow.

Another problem may occur when you simulate ``arrow fragments''
using a finer grid.  The arrow-length checker does not know what
is a ``fragment'' and so it will force each fragment to be
\verb"\dgARROWLENGTH" long.  The easiest way to fix this is to
locally divide \verb"\dgARROWLENGTH" by the scale factor between
the coarse and fine grids.  For example:
{\samepage
\begin{verbatim}
   \divide\dgARROWLENGTH by2
   \begin{diagram}
                          \node[2]{A}\arrow[2]{s}\\
     \node{B}\arrow{e,-}  \node{}\arrow{e,t}{\alpha}  \node{C}\\
                          \node[2]{D}
   \end{diagram}
\end{verbatim}
\[
   \divide\dgARROWLENGTH by2
   \begin{diagram}
                          \node[2]{A}\arrow[2]{s}\\
     \node{B}\arrow{e,-}  \node{}\arrow{e,t}{\alpha}  \node{C}\\
                          \node[2]{D}
   \end{diagram}
\]
}

The space set aside for a formula
further includes padding to keep the arrows from actually touching the
formulas.  The padding increases the apparent horizontal size of
each formula by \verb"\dgHORIZPAD" and the apparent vertical size
by \verb"\dgVERTPAD". The default values of these parameters are:
\begin{verbatim}
   \dgHORIZPAD=1em
   \dgVERTPAD=2ex
\end{verbatim}

The ratio of the horizontal and vertical scales of the grid,
known as the {\em aspect ratio\/}, cannot be completely
arbitrary because of the slope limitations of font-based arrows.
In order that the full required set of compass-point directions be
available, the optimal calculated aspect ratio will be approximated
so as to be compatible with the available fonts.  In plain
\LaTeX{} mode the possibile aspect ratios are half-integers up to~2,
while in {\sc LamS}-\TeX{} mode they are half-integers up to~3.

\verb"\dgLABELOFFSET" is the (approximate) distance which will 
separate labels from their arrows.  An arrow is divided into 
\verb"\dgARROWPARTS" parts for custom positioning of labels along the 
arrow (the only sensible choices for this number are 2,4,6,8,10).  By 
default,
\begin{verbatim}
   \dgLABELOFFSET=.7ex
   \dgARROWPARTS=4
\end{verbatim}

The following two parameters regulate the appearance of dotted arrows 
in plain \LaTeX{} mode:
\begin{verbatim}
   \dgDOTSPACING=0.35em
   \dgDOTSIZE=1.5\fontdimen8\tenln
\end{verbatim}

By default, nodes are typeset \verb"\displaystyle", and labels
\verb"\scriptstyle".  This is controlled by the commands 
\verb"\dgeverynode" (which is executed prior to the formula of each 
node) and \verb"\dgeverylabel" (which is executed prior to the 
formula of each label).  They can be changed with 
\verb"\renewcommand", like this:
\begin{verbatim}
   \renewcommand{\dgeverynode}{\displaystyle}
   \renewcommand{\dgeverylabel}{\scriptstyle}
\end{verbatim}
These commands may alternatively be defined to take one argument,
which will be the content of the node or label.


\section{Customizing the Package}

The \verb"diagram" environment was designed in a modular way to make 
it easy to add features.

To add a new option to the \verb"\arrow" command---say 
\verb"**"---you need only define a command named \verb"\dgo@**" which 
sets the desired parameters.  Let's say you want the \verb"**" option 
to make \verb"\arrow" use a custom arrow design of yours.  Since 
\verb"\dg@VECTOR" is the parameter that governs the arrow-drawing 
code, you would say
\begin{verbatim}
   \@namedef{dgo@**}{\let\dg@VECTOR=\myamazingvector}
\end{verbatim}
where \verb"\myamazingvector" is your custom arrow code (analogous
to \LaTeX's \verb"\vector" command).  Note that if this definition is 
not in a style file, it needs to be bracketed with 
\verb"\makeatletter...\makeatother".  You can then use your custom 
arrow style like any other option:
\begin{verbatim}
   \arrow{sw,t,**}{\Gamma}
\end{verbatim}

Adding new arrow direction codes is done by defining commands of the 
form \verb"\dgt@DIRCODE".  These commands set \verb"\vector"-like 
parameters to specify the arrow direction (thinking of the arrow as 
laid out on a grid where the basic rectangle is unit wide and one 
unit high).  For example:
\begin{verbatim}
   \@namedef{dgt@sse}{\dg@DX=1 \dg@DY=-2 \dg@SIZE=1 }
\end{verbatim}

You can also customize the way the grid geometry is computed by
redefining the \verb"\dggeometry" command.  It must set 
the integer parameters \verb"\dg@XGRID" and \verb"\dg@YGRID" and
the length parameter \verb"\unitlength".  Each grid rectangle
will then be 1000\verb"\dg@XGRID" by 1000\verb"\dg@YGRID"
\verb"\unitlength"s in size.  The assigned values of
\verb"\dg@XGRID" and \verb"\dg@YGRID" should be smallish numbers
(to avoid arithmetic overflow) with \verb"XGRID":\verb"YGRID"
as the desired aspect ratio.  As inputs,
you should use the pre-supplied values of \verb"\dg@XGRID" and
\verb"\dg@YGRID", which are the calculated minimum width and
height that grid rectangles must have, measured in scaled
points (sp).

In plain \LaTeX{} mode, the aspect ratio must be a half-integer 
between~$\tfrac12$ and~2 (or the inverse of such) in order to
support the basic 16 compass directions.  In {\sc LamS}-\TeX{} mode,
the aspect ratio need only be a half-integer between~$\tfrac12$
and~3 in order to support these same basic directions; and when
the aspect ratio is chosen from these values, almost all the
arrow directions $(p,q)$ with $\max(|p|,|q|)\le 3$ are supported.
The exceptions are that arrows of type $(\pm 3,\,\pm 2)$ are
only rendered approximately in some aspect ratios, and that
arrows of type $(\pm 3,\,\pm 1)$ are not supported unless
the aspect ratio is a half-integer between~$\tfrac12$ and~2.
The \verb"\dggeometry" macro for {\sc LamS}-\TeX{} mode
{\em automatically\/} detects when it needs to restrict the
aspect ratio because of a type $(\pm 3,\,\pm 1)$ arrow in
the diagram.


\section{Upgrading Papers from Previous Versions}

Some slightly incompatible changes have been made during
the evolution of this package.

Beginning with version~3.5, the files and names of the packages
were reorganized to simplify electronic publication.  Here is a
dictionary to make the translation:
\begin{center}
\begin{tabular}{|l|l|} \hline
   Old Packages & New Packages \\ \hline
   \tt diagram & \tt pb-diagram \\
   \tt lamsarrow,diagram & \tt pb-diagram,lamsarrow,pb-lams \\ \hline
\end{tabular}
\end{center}
The order of the packages must be as shown in the table.

Beginning with version~4.0, a bug which caused occasional diagrams
to come out twice too large was eliminated.  If you have an old paper
which was tuned for the earlier geometry calculation, you can get
the previous behavior back by including the command
\verb"\let\dggeometry=\dgoldgeometry" in the document's preamble.


\section{Implementation Notes}

All command names defined in the \verb"pb-diagram.sty" style file
begin with ``\verb"\dg"'', except \verb"\diagram",
\verb"\enddiagram", \verb"\node", \verb"\arrow",
\verb"\\", and the \LaTeX{} enhancements \verb"\newoptcommand",
\verb"\newoptenvironment", \verb"\renewoptcommand", and
\verb"\renewoptenvironment".  All private commands contain an `@' in
their names.  The commands \verb"\node" and \verb"\\" are only defined 
within the \verb"diagram" environment.  Spaces following the 
\verb"\end{diagram}" are ignored.

In all the macro files in this package, lines have been limited to
less than~70 characters to avoid problems with electronic mailing.


\section{Copyright and Acknowledgments}

The \verb"pb-diagram" package is
copyright \copyright\ 1990, 1992, 1995, 1998 by Paul Burchard.

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 2 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, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

The file \verb"pb-xy.sty" is
copyright \copyright\ 1998 by Bill Richter,
and is also distributed under the terms of the GNU General Public License.

The fonts \verb"lams1.mf" through \verb"lams5.mf", as well as the
macros in \verb"lamsarrow.sty", are copyright \copyright\ 1989,
1990, 1991 by The Texplorators Corporation, 1572 West Gray \#377,
Houston, TX 77019--4948.  Beginning with version 4.1 of this package,
the fonts include a patch by Ingo Hadan which makes them compatible
with recent versions of \verb"cmbase.mf", and in particular, eliminating
a division-by-zero error that caused certain glyphs to appear wildly deformed.

I would like to acknowledge inspiration from a macro package of 
Marc-Paul van der Hulst.  Bill Richter was of major help to me with 
his topological torture-testing of this package, and he provided
some spectacular example diagrams for distribution with this package.
Dan Christensen made many good suggestions which were incorporated
into version 4.0.

\end{document}