% pb-manual.tex: user's manual for pb-diagram.sty macros % Author: Paul Burchard % 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}