| 1 |
% pb-manual.tex: user's manual for pb-diagram.sty macros |
| 2 |
% Author: Paul Burchard <[email protected]> |
| 3 |
% Version Number: 5.0 |
| 4 |
% Version Date: 20 Oct 1998 |
| 5 |
% |
| 6 |
% Copyright (c) 1990, 1992, 1995, 1998 by Paul Burchard |
| 7 |
% |
| 8 |
% This program is free software; you can redistribute it and/or modify |
| 9 |
% it under the terms of the GNU General Public License as published by |
| 10 |
% the Free Software Foundation; either version 2 of the License, or |
| 11 |
% (at your option) any later version. |
| 12 |
% |
| 13 |
% This program is distributed in the hope that it will be useful, |
| 14 |
% but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 15 |
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 16 |
% GNU General Public License for more details. |
| 17 |
% |
| 18 |
% You should have received a copy of the GNU General Public License |
| 19 |
% along with this program; if not, write to the Free Software |
| 20 |
% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. |
| 21 |
% |
| 22 |
\def\tooee{LaTeX2e} |
| 23 |
\ifx\fmtname\tooee |
| 24 |
\documentclass[12pt]{article}\usepackage{pb-diagram} |
| 25 |
\else |
| 26 |
\documentstyle[12pt,pb-diagram]{article} |
| 27 |
\fi |
| 28 |
\def\diagramversion{5.0} |
| 29 |
\title{User's Guide to the Diagram Environment, |
| 30 |
Version \diagramversion} |
| 31 |
\author{Paul Burchard ([email protected])} |
| 32 |
\def\tfrac#1#2{{\textstyle\frac{#1}{#2}}} |
| 33 |
\begin{document} |
| 34 |
\maketitle |
| 35 |
|
| 36 |
\section{Introduction} |
| 37 |
|
| 38 |
The \verb"diagram" environment allows the |
| 39 |
\ifx\fmtname\tooee\LaTeXe\else\LaTeX\fi{} user to easily |
| 40 |
create complex commutative diagrams, by placing formula nodes |
| 41 |
on a conceptual grid and attaching arrows to them. |
| 42 |
|
| 43 |
The grid used in these diagrams is not a fixed square grid. |
| 44 |
Instead, the environment automatically generates a correctly scaled |
| 45 |
and shaped rectangular grid which will compactly hold the formulas, |
| 46 |
while leaving room for the arrows between them. Moreover, the |
| 47 |
arrows automatically adapt to the spaces between the formulas |
| 48 |
being connected. These features are accomplished with a |
| 49 |
three-pass algorithm that takes into account the width |
| 50 |
and height of every formula. |
| 51 |
|
| 52 |
The arrows in these diagrams are quite flexible. |
| 53 |
Arrows may, in any combination, |
| 54 |
\begin{itemize} |
| 55 |
\item point in any of a large number of lattice directions; |
| 56 |
\item span multiple rows and columns of the grid; |
| 57 |
\item cross other arrows; |
| 58 |
\item have labels on either or both sides, |
| 59 |
with adjustable positioning; |
| 60 |
\item have a variety of head, tail, and shaft styles. |
| 61 |
\end{itemize} |
| 62 |
The fancier arrow styles are made possible by special fonts, |
| 63 |
either from Xy-pic or {\sc LamS}-\TeX, but the package can be used |
| 64 |
without them if necessary. |
| 65 |
|
| 66 |
\pagebreak[3] |
| 67 |
To get a feel for how the package works, here are some examples of |
| 68 |
commands for producing arrows: |
| 69 |
\begin{flushright} |
| 70 |
% |
| 71 |
% Catcode hack to get typewriter `\' `{' `}' inside arg of command |
| 72 |
% where \verb is illegal. |
| 73 |
\begingroup |
| 74 |
\catcode`|=0 \catcode`[=1 \catcode`]=2 |
| 75 |
\catcode`\{=12 \catcode`\}=12 \catcode`\\=12 |
| 76 |
|gdef|bbb[\]|gdef|lll[{]|gdef|rrr[}]% |
| 77 |
|endgroup |
| 78 |
\def\ttt{\ifx\fmtname\tooee\fontfamily{cmtt}\selectfont\else\tt\fi}% |
| 79 |
% |
| 80 |
% tighten it up a bit to fit on page in 12pt |
| 81 |
\setlength{\dgARROWLENGTH}{1.5em}% |
| 82 |
\noindent |
| 83 |
$\begin{diagram} |
| 84 |
\node{\makebox[0pt][r]{\ttt\bbb arrow\lll e\rrr \quad}+} |
| 85 |
\arrow{e} \node{+} \node{+} \node{+} \node{+} \\ |
| 86 |
\node{+} \arrow{s,lr}{\makebox[0pt][r]{\ttt\bbb |
| 87 |
arrow\lll s,lr\rrr\lll\bbb alpha\rrr\lll\bbb beta\rrr\quad} |
| 88 |
\alpha}{\beta} |
| 89 |
\node{+} \node{+} \node{+} \node{+} \\ |
| 90 |
\node{+} \node{+} \node{+} \node{+} \node{+} \\ |
| 91 |
\node{\makebox[0pt][r]{\ttt\bbb |
| 92 |
arrow[2]\lll ene,t,3,..\rrr\lll f\_0\rrr\quad}+} |
| 93 |
\arrow[2]{ene,t,3,..}{f_0} \node{+} |
| 94 |
\node{+} \node{+} \node{+} |
| 95 |
\end{diagram}$ |
| 96 |
\end{flushright} |
| 97 |
And here is a simple example diagram: |
| 98 |
\[ |
| 99 |
\begin{diagram} |
| 100 |
\node{A} \arrow{e,t}{a} \arrow{s,l}{c} \arrow{ese} |
| 101 |
\node{B^*} \arrow{e,t}{b^*} |
| 102 |
\node{C} \arrow{s,r}{d} \arrow{wsw} \\ |
| 103 |
\node{D} \arrow[2]{e,b}{e} \node[2]{E} |
| 104 |
\end{diagram} |
| 105 |
\] |
| 106 |
\begin{verbatim} |
| 107 |
\[ |
| 108 |
\begin{diagram} |
| 109 |
\node{A} \arrow{e,t}{a} \arrow{s,l}{c} \arrow{ese} |
| 110 |
\node{B^*} \arrow{e,t}{b^*} |
| 111 |
\node{C} \arrow{s,r}{d} \arrow{wsw} \\ |
| 112 |
\node{D} \arrow[2]{e,b}{e} \node[2]{E} |
| 113 |
\end{diagram} |
| 114 |
\] |
| 115 |
\end{verbatim} |
| 116 |
|
| 117 |
\pagebreak[4] |
| 118 |
\section{Loading the Diagram Package} |
| 119 |
|
| 120 |
To use the \verb"diagram" environment, begin your |
| 121 |
\ifx\fmtname\tooee\LaTeXe\else\LaTeX2e\fi{} file with: |
| 122 |
\begin{verbatim} |
| 123 |
\documentclass{DOCSTYLE}\usepackage{pb-diagram} |
| 124 |
\end{verbatim} |
| 125 |
where \verb"DOCSTYLE" is your document style (e.g., |
| 126 |
\verb"article"). The style file \verb"pb-diagram.sty" needs to |
| 127 |
be placed in one of your system's \TeX{} input directories. |
| 128 |
|
| 129 |
If you are using older versions of \LaTeX{} (2.09 or older), then |
| 130 |
you would begin instead with: |
| 131 |
\begin{verbatim} |
| 132 |
\documentstyle[pb-diagram]{DOCSTYLE} |
| 133 |
\end{verbatim} |
| 134 |
|
| 135 |
If you have {\em METAFONT\/} available on your system, |
| 136 |
and would like to make use of the additional features |
| 137 |
of the Xy-pic fonts (highly recommended!), then you should |
| 138 |
instead begin your |
| 139 |
\ifx\fmtname\tooee\LaTeXe\else\LaTeX2e\fi{} file with: |
| 140 |
\begin{verbatim} |
| 141 |
\documentclass{DOCSTYLE} |
| 142 |
\usepackage[cmtip,arrow]{xy} |
| 143 |
\usepackage{pb-diagram,pb-xy} |
| 144 |
\end{verbatim} |
| 145 |
This option requires that you have Xy-pic installed on your |
| 146 |
system. Xy-pic is available from your nearest CTAN archive |
| 147 |
(e.g. {\tt http://ctan.tug.org/}) in the CTAN directory |
| 148 |
{\tt macros/generic/diagrams/xypic/}. |
| 149 |
|
| 150 |
An alternative set of fonts which enables some of the |
| 151 |
fancier features is the {\sc LamS}-\TeX{} font set; to |
| 152 |
use it, begin your |
| 153 |
\ifx\fmtname\tooee\LaTeXe\else\LaTeX2e\fi{} file with: |
| 154 |
\begin{verbatim} |
| 155 |
\documentclass{DOCSTYLE} |
| 156 |
\usepackage{pb-diagram,lamsarrow,pb-lams} |
| 157 |
\end{verbatim} |
| 158 |
This option requires the {\em METAFONT\/} source files |
| 159 |
\verb"lams1.mf" through \verb"lams5.mf" to be installed. |
| 160 |
|
| 161 |
Installation of additional fonts is system-dependent, |
| 162 |
but will involve moving the \verb".mf" files into the system's |
| 163 |
{\em METAFONT\/} input directory, and then running the |
| 164 |
{\em METAFONT\/} program. This program will generate the |
| 165 |
\verb".tfm" files required for \TeX, and the \verb".pk" or |
| 166 |
\verb".gf" files required for printing and previewing. |
| 167 |
On {\sc unix} systems, the relevant files are typically |
| 168 |
located in \verb"/usr/lib/mf" and \verb"/usr/lib/tex", or |
| 169 |
\verb"/usr/local/lib/mf" and \verb"/usr/local/lib/tex". |
| 170 |
|
| 171 |
If you are having troubling getting \LaTeX{} to properly |
| 172 |
process an older paper which uses this package, check the |
| 173 |
later section, ``Upgrading Papers from Previous Versions.'' |
| 174 |
|
| 175 |
\pagebreak[4] |
| 176 |
\section{Using the Diagram Environment} |
| 177 |
\subsection{Overall Structure of the Environment} |
| 178 |
|
| 179 |
The \verb"diagram" environment should be used in |
| 180 |
{\em math mode only}. Its usage is as follows:\footnote{For |
| 181 |
compatibility reasons, the diagram environment accepts and |
| 182 |
optional argument. When this argument is supplied, the grid |
| 183 |
geometry is calculated in exactly the same way as in version~1.0 |
| 184 |
of this package. Therefore, manuscripts written with version~1.0 |
| 185 |
require no changes to be processed with version~\diagramversion.} |
| 186 |
\begin{verbatim} |
| 187 |
\begin{diagram} |
| 188 |
NODE ARROW ARROW ... NODE ARROW ARROW ... .... \\ |
| 189 |
NODE ARROW ARROW ... NODE ARROW ARROW ... .... \\ |
| 190 |
... |
| 191 |
NODE ARROW ARROW ... NODE ARROW ARROW ... .... |
| 192 |
\end{diagram} |
| 193 |
\end{verbatim} |
| 194 |
|
| 195 |
Each \verb"NODE" places a centered formula at a new grid point, and |
| 196 |
each \verb"ARROW" which follows this \verb"NODE" (but precedes the |
| 197 |
next \verb"NODE") will be attached by its tail to the same grid |
| 198 |
point. The diagram will be automatically be given a geometry which |
| 199 |
accomodates these elements, but you can also fine-tune it afterwards |
| 200 |
by hand if it didn't turn out like you imagined |
| 201 |
(see the section on ``Fine-Tuning'' below). We now explain |
| 202 |
how to specify the \verb"NODE"s and \verb"ARROW"s. |
| 203 |
|
| 204 |
\subsection{Formula Nodes} |
| 205 |
|
| 206 |
A \verb"NODE" is specified by the comand: |
| 207 |
\begin{verbatim} |
| 208 |
\node[NCOLS]{FORMULA} |
| 209 |
\end{verbatim} |
| 210 |
where the optional argument \verb"NCOLS" tells how many grid columns |
| 211 |
to move forward from the previous node (the default is 1). The |
| 212 |
\verb"FORMULA" is the math mode material which you want to place at |
| 213 |
that node in the grid. |
| 214 |
|
| 215 |
The \verb"\\" command moves to the next grid row. As is usual in |
| 216 |
\LaTeX{} arrays, the final row should not end with a \verb"\\", and |
| 217 |
any blank columns at the end of a row need not be entered. More |
| 218 |
generally, it is possible to move \verb"NROWS" rows down at once |
| 219 |
using the command: |
| 220 |
\begin{verbatim} |
| 221 |
\\[NROWS] |
| 222 |
\end{verbatim} |
| 223 |
|
| 224 |
\subsection{Arrows and their Embellishments} |
| 225 |
|
| 226 |
An \verb"ARROW" is specified by the \verb"\arrow" command, which may |
| 227 |
also be used anywhere in math mode, independent of the |
| 228 |
\verb"diagram" environment. Its usage depends on the number of |
| 229 |
labels desired: |
| 230 |
\begin{verbatim} |
| 231 |
\arrow[SIZE]{DIRECTION,OPTIONS} |
| 232 |
\arrow[SIZE]{DIRECTION,ONELABEL,OPTIONS}{LABEL} |
| 233 |
\arrow[SIZE]{DIRECTION,TWOLABEL,OPTIONS}{LABEL1}{LABEL2} |
| 234 |
\end{verbatim} |
| 235 |
The commas should not have any spaces before or after them, and there |
| 236 |
should not be any extra spaces or commas at the beginning or end of |
| 237 |
the list. The optional integer argument \verb"SIZE" tells how many |
| 238 |
times its normal length the arrow should be made. For example, |
| 239 |
\verb"\arrow[2]{e}" will span two columns, while \verb"\arrow[2]{s}" |
| 240 |
will span two rows. |
| 241 |
|
| 242 |
The arrow \verb"DIRECTION" may be chosen from the compass point |
| 243 |
directions: |
| 244 |
\begin{verbatim} |
| 245 |
n,e,s,w,ne,nw,se,sw,nne,nnw,sse,ssw,ene,ese,wnw,wsw |
| 246 |
\end{verbatim} |
| 247 |
If the \verb"pb-lams" style has been loaded, the \verb"DIRECTION" |
| 248 |
may also be chosen from this list: |
| 249 |
\begin{verbatim} |
| 250 |
nee,see,nww,sww, |
| 251 |
neee,nnne,nnnw,nwww,swww,sssw,ssse,seee, |
| 252 |
nnnee,nnnww,sssww,sssee,nneee,nnwww,sswww,sseee |
| 253 |
\end{verbatim} |
| 254 |
(For more information about arrow directions, see the sections |
| 255 |
on ``Fine Tuning'' and ``Customizing'' below.) |
| 256 |
|
| 257 |
Any \verb"LABEL"s present are math mode material. The |
| 258 |
\verb"ONELABEL" specifier may be chosen from: |
| 259 |
\begin{tabbing} |
| 260 |
{\tt xxx}\={\tt x}\qquad\=\kill |
| 261 |
\>{\tt t}\> top\\ |
| 262 |
\>{\tt b}\> bottom\\ |
| 263 |
\>{\tt l}\> left (only for use with vertical arrows)\\ |
| 264 |
\>{\tt r}\> right (only for use with vertical arrows) |
| 265 |
\end{tabbing} |
| 266 |
The \verb"TWOLABEL" specifier may be chosen from: |
| 267 |
\begin{tabbing} |
| 268 |
{\tt xxx}\={\tt x}\qquad\=\kill |
| 269 |
\>{\tt tb}\> top and bottom\\ |
| 270 |
\>{\tt lr}\> left and right (only for use with vertical arrows) |
| 271 |
\end{tabbing} |
| 272 |
|
| 273 |
The \verb"OPTION"s describe the style of the arrow shaft, the symbols |
| 274 |
to be used at the head and tail of the arrow, and the positions of |
| 275 |
the labels. The defaults are: a simple line shaft, a single simple |
| 276 |
arrowhead, no special tail symbol, and labels positioned at the |
| 277 |
midpoint of the arrow shaft. The \verb"OPTION"s may be selected from |
| 278 |
the lists which follow. Most of the options can be combined with |
| 279 |
others; however, not all combinations make sense. In addition, |
| 280 |
options marked with~(*) are only available with |
| 281 |
either \verb"pb-xy" or \verb"pb-lams" loaded; |
| 282 |
and options marked with~(**) are only available with \verb"pb-xy" loaded. |
| 283 |
Shaft options are: |
| 284 |
\begin{tabbing} |
| 285 |
{\tt xxx}\={\tt x}\qquad\=\kill |
| 286 |
\>{\tt ..}\> dotted or dashed arrow shaft\\ |
| 287 |
\>{\tt =}\> double line shaft* (``equals sign'')\\ |
| 288 |
\>{\tt !}\> invisible arrow shaft |
| 289 |
\end{tabbing} |
| 290 |
Arrow head options are: |
| 291 |
\begin{tabbing} |
| 292 |
{\tt xxx}\={\tt x}\qquad\=\kill |
| 293 |
\>{\tt -}\> no arrow heads\\ |
| 294 |
\>{\tt <>}\> arrow heads on both ends\\ |
| 295 |
\>{\tt A}\> double arrow head*\\ |
| 296 |
\>{\tt '}\> left half of arrow head*\\ |
| 297 |
\>{\tt `}\> right half of arrow head* |
| 298 |
\end{tabbing} |
| 299 |
Arrow tail options are: |
| 300 |
\begin{tabbing} |
| 301 |
{\tt xxx}\={\tt x}\qquad\=\kill |
| 302 |
\>{\tt V}\> single arrow tail*\\ |
| 303 |
\>{\tt J}\> left fish hook arrow tail*\\ |
| 304 |
\>{\tt L}\> right fish hook arrow tail*\\ |
| 305 |
\>{\tt S}\> squiggle arrow tail* |
| 306 |
\>{\tt T}\> ``mapsto'' arrow tail** |
| 307 |
\end{tabbing} |
| 308 |
In the default configuration, the label positioning options are: |
| 309 |
\begin{tabbing} |
| 310 |
{\tt xxx}\={\tt x}\qquad\=\kill |
| 311 |
\>{\tt 1}\> 1/4 of way from tail end\\ |
| 312 |
\>{\tt 2}\> 2/4 of way from tail end (the default)\\ |
| 313 |
\>{\tt 3}\> 3/4 of way from tail end |
| 314 |
\end{tabbing} |
| 315 |
However, if more flexibility is needed, there is an |
| 316 |
\verb"ARROWPARTS" parameter which specifies how many pieces the arrow |
| 317 |
will be divided into to determine the meaning of the label |
| 318 |
positioning option. (In general, the positioning option may be any |
| 319 |
single digit.) For example, to position a label 5/6 of the way from |
| 320 |
the tail end of the arrow, you would use commands like these: |
| 321 |
\begin{verbatim} |
| 322 |
\dgARROWPARTS=6 |
| 323 |
\begin{diagram} |
| 324 |
... \arrow{e,t,5}{MYLABEL} ... |
| 325 |
\end{diagram} |
| 326 |
\end{verbatim} |
| 327 |
\verb"ARROWPARTS" should be even, so that ordinary labels can |
| 328 |
be properly positioned at the half-way point. |
| 329 |
|
| 330 |
|
| 331 |
\section{Fine Tuning the Diagrams} |
| 332 |
|
| 333 |
Many of the parameters used by the \verb"diagram" environment are |
| 334 |
accessible to you and documented here so that the existing features |
| 335 |
can be fine-tuned. |
| 336 |
|
| 337 |
The most important parameter is \verb"\dgARROWLENGTH", which |
| 338 |
specifies the minimum length for all arrows. The \verb"diagram" |
| 339 |
environment will independently adjust the horizontal and vertical |
| 340 |
scales of its rectangular grid until at least that much room is |
| 341 |
available for each arrow. This calculation takes into account |
| 342 |
the room that must be set aside for the each of the two formulas |
| 343 |
being connected by an arrow. The default minimum arrow length is |
| 344 |
\begin{verbatim} |
| 345 |
\dgARROWLENGTH=2.5em |
| 346 |
\end{verbatim} |
| 347 |
The \verb"\arrow" command may also be used outside of the diagram |
| 348 |
environment; in that case, its length is instead controlled by |
| 349 |
the parameter |
| 350 |
\begin{verbatim} |
| 351 |
\dgTEXTARROWLENGTH=1.1em |
| 352 |
\end{verbatim} |
| 353 |
|
| 354 |
Some anomalies you may encounter: the collision of formulas is not |
| 355 |
checked unless an arrow connects them. Therefore, if two formulas |
| 356 |
turn out to overlap you can just connect them with an invisible arrow. |
| 357 |
|
| 358 |
Another problem may occur when you simulate ``arrow fragments'' |
| 359 |
using a finer grid. The arrow-length checker does not know what |
| 360 |
is a ``fragment'' and so it will force each fragment to be |
| 361 |
\verb"\dgARROWLENGTH" long. The easiest way to fix this is to |
| 362 |
locally divide \verb"\dgARROWLENGTH" by the scale factor between |
| 363 |
the coarse and fine grids. For example: |
| 364 |
{\samepage |
| 365 |
\begin{verbatim} |
| 366 |
\divide\dgARROWLENGTH by2 |
| 367 |
\begin{diagram} |
| 368 |
\node[2]{A}\arrow[2]{s}\\ |
| 369 |
\node{B}\arrow{e,-} \node{}\arrow{e,t}{\alpha} \node{C}\\ |
| 370 |
\node[2]{D} |
| 371 |
\end{diagram} |
| 372 |
\end{verbatim} |
| 373 |
\[ |
| 374 |
\divide\dgARROWLENGTH by2 |
| 375 |
\begin{diagram} |
| 376 |
\node[2]{A}\arrow[2]{s}\\ |
| 377 |
\node{B}\arrow{e,-} \node{}\arrow{e,t}{\alpha} \node{C}\\ |
| 378 |
\node[2]{D} |
| 379 |
\end{diagram} |
| 380 |
\] |
| 381 |
} |
| 382 |
|
| 383 |
The space set aside for a formula |
| 384 |
further includes padding to keep the arrows from actually touching the |
| 385 |
formulas. The padding increases the apparent horizontal size of |
| 386 |
each formula by \verb"\dgHORIZPAD" and the apparent vertical size |
| 387 |
by \verb"\dgVERTPAD". The default values of these parameters are: |
| 388 |
\begin{verbatim} |
| 389 |
\dgHORIZPAD=1em |
| 390 |
\dgVERTPAD=2ex |
| 391 |
\end{verbatim} |
| 392 |
|
| 393 |
The ratio of the horizontal and vertical scales of the grid, |
| 394 |
known as the {\em aspect ratio\/}, cannot be completely |
| 395 |
arbitrary because of the slope limitations of font-based arrows. |
| 396 |
In order that the full required set of compass-point directions be |
| 397 |
available, the optimal calculated aspect ratio will be approximated |
| 398 |
so as to be compatible with the available fonts. In plain |
| 399 |
\LaTeX{} mode the possibile aspect ratios are half-integers up to~2, |
| 400 |
while in {\sc LamS}-\TeX{} mode they are half-integers up to~3. |
| 401 |
|
| 402 |
\verb"\dgLABELOFFSET" is the (approximate) distance which will |
| 403 |
separate labels from their arrows. An arrow is divided into |
| 404 |
\verb"\dgARROWPARTS" parts for custom positioning of labels along the |
| 405 |
arrow (the only sensible choices for this number are 2,4,6,8,10). By |
| 406 |
default, |
| 407 |
\begin{verbatim} |
| 408 |
\dgLABELOFFSET=.7ex |
| 409 |
\dgARROWPARTS=4 |
| 410 |
\end{verbatim} |
| 411 |
|
| 412 |
The following two parameters regulate the appearance of dotted arrows |
| 413 |
in plain \LaTeX{} mode: |
| 414 |
\begin{verbatim} |
| 415 |
\dgDOTSPACING=0.35em |
| 416 |
\dgDOTSIZE=1.5\fontdimen8\tenln |
| 417 |
\end{verbatim} |
| 418 |
|
| 419 |
By default, nodes are typeset \verb"\displaystyle", and labels |
| 420 |
\verb"\scriptstyle". This is controlled by the commands |
| 421 |
\verb"\dgeverynode" (which is executed prior to the formula of each |
| 422 |
node) and \verb"\dgeverylabel" (which is executed prior to the |
| 423 |
formula of each label). They can be changed with |
| 424 |
\verb"\renewcommand", like this: |
| 425 |
\begin{verbatim} |
| 426 |
\renewcommand{\dgeverynode}{\displaystyle} |
| 427 |
\renewcommand{\dgeverylabel}{\scriptstyle} |
| 428 |
\end{verbatim} |
| 429 |
These commands may alternatively be defined to take one argument, |
| 430 |
which will be the content of the node or label. |
| 431 |
|
| 432 |
|
| 433 |
\section{Customizing the Package} |
| 434 |
|
| 435 |
The \verb"diagram" environment was designed in a modular way to make |
| 436 |
it easy to add features. |
| 437 |
|
| 438 |
To add a new option to the \verb"\arrow" command---say |
| 439 |
\verb"**"---you need only define a command named \verb"\dgo@**" which |
| 440 |
sets the desired parameters. Let's say you want the \verb"**" option |
| 441 |
to make \verb"\arrow" use a custom arrow design of yours. Since |
| 442 |
\verb"\dg@VECTOR" is the parameter that governs the arrow-drawing |
| 443 |
code, you would say |
| 444 |
\begin{verbatim} |
| 445 |
\@namedef{dgo@**}{\let\dg@VECTOR=\myamazingvector} |
| 446 |
\end{verbatim} |
| 447 |
where \verb"\myamazingvector" is your custom arrow code (analogous |
| 448 |
to \LaTeX's \verb"\vector" command). Note that if this definition is |
| 449 |
not in a style file, it needs to be bracketed with |
| 450 |
\verb"\makeatletter...\makeatother". You can then use your custom |
| 451 |
arrow style like any other option: |
| 452 |
\begin{verbatim} |
| 453 |
\arrow{sw,t,**}{\Gamma} |
| 454 |
\end{verbatim} |
| 455 |
|
| 456 |
Adding new arrow direction codes is done by defining commands of the |
| 457 |
form \verb"\dgt@DIRCODE". These commands set \verb"\vector"-like |
| 458 |
parameters to specify the arrow direction (thinking of the arrow as |
| 459 |
laid out on a grid where the basic rectangle is unit wide and one |
| 460 |
unit high). For example: |
| 461 |
\begin{verbatim} |
| 462 |
\@namedef{dgt@sse}{\dg@DX=1 \dg@DY=-2 \dg@SIZE=1 } |
| 463 |
\end{verbatim} |
| 464 |
|
| 465 |
You can also customize the way the grid geometry is computed by |
| 466 |
redefining the \verb"\dggeometry" command. It must set |
| 467 |
the integer parameters \verb"\dg@XGRID" and \verb"\dg@YGRID" and |
| 468 |
the length parameter \verb"\unitlength". Each grid rectangle |
| 469 |
will then be 1000\verb"\dg@XGRID" by 1000\verb"\dg@YGRID" |
| 470 |
\verb"\unitlength"s in size. The assigned values of |
| 471 |
\verb"\dg@XGRID" and \verb"\dg@YGRID" should be smallish numbers |
| 472 |
(to avoid arithmetic overflow) with \verb"XGRID":\verb"YGRID" |
| 473 |
as the desired aspect ratio. As inputs, |
| 474 |
you should use the pre-supplied values of \verb"\dg@XGRID" and |
| 475 |
\verb"\dg@YGRID", which are the calculated minimum width and |
| 476 |
height that grid rectangles must have, measured in scaled |
| 477 |
points (sp). |
| 478 |
|
| 479 |
In plain \LaTeX{} mode, the aspect ratio must be a half-integer |
| 480 |
between~$\tfrac12$ and~2 (or the inverse of such) in order to |
| 481 |
support the basic 16 compass directions. In {\sc LamS}-\TeX{} mode, |
| 482 |
the aspect ratio need only be a half-integer between~$\tfrac12$ |
| 483 |
and~3 in order to support these same basic directions; and when |
| 484 |
the aspect ratio is chosen from these values, almost all the |
| 485 |
arrow directions $(p,q)$ with $\max(|p|,|q|)\le 3$ are supported. |
| 486 |
The exceptions are that arrows of type $(\pm 3,\,\pm 2)$ are |
| 487 |
only rendered approximately in some aspect ratios, and that |
| 488 |
arrows of type $(\pm 3,\,\pm 1)$ are not supported unless |
| 489 |
the aspect ratio is a half-integer between~$\tfrac12$ and~2. |
| 490 |
The \verb"\dggeometry" macro for {\sc LamS}-\TeX{} mode |
| 491 |
{\em automatically\/} detects when it needs to restrict the |
| 492 |
aspect ratio because of a type $(\pm 3,\,\pm 1)$ arrow in |
| 493 |
the diagram. |
| 494 |
|
| 495 |
|
| 496 |
\section{Upgrading Papers from Previous Versions} |
| 497 |
|
| 498 |
Some slightly incompatible changes have been made during |
| 499 |
the evolution of this package. |
| 500 |
|
| 501 |
Beginning with version~3.5, the files and names of the packages |
| 502 |
were reorganized to simplify electronic publication. Here is a |
| 503 |
dictionary to make the translation: |
| 504 |
\begin{center} |
| 505 |
\begin{tabular}{|l|l|} \hline |
| 506 |
Old Packages & New Packages \\ \hline |
| 507 |
\tt diagram & \tt pb-diagram \\ |
| 508 |
\tt lamsarrow,diagram & \tt pb-diagram,lamsarrow,pb-lams \\ \hline |
| 509 |
\end{tabular} |
| 510 |
\end{center} |
| 511 |
The order of the packages must be as shown in the table. |
| 512 |
|
| 513 |
Beginning with version~4.0, a bug which caused occasional diagrams |
| 514 |
to come out twice too large was eliminated. If you have an old paper |
| 515 |
which was tuned for the earlier geometry calculation, you can get |
| 516 |
the previous behavior back by including the command |
| 517 |
\verb"\let\dggeometry=\dgoldgeometry" in the document's preamble. |
| 518 |
|
| 519 |
|
| 520 |
\section{Implementation Notes} |
| 521 |
|
| 522 |
All command names defined in the \verb"pb-diagram.sty" style file |
| 523 |
begin with ``\verb"\dg"'', except \verb"\diagram", |
| 524 |
\verb"\enddiagram", \verb"\node", \verb"\arrow", |
| 525 |
\verb"\\", and the \LaTeX{} enhancements \verb"\newoptcommand", |
| 526 |
\verb"\newoptenvironment", \verb"\renewoptcommand", and |
| 527 |
\verb"\renewoptenvironment". All private commands contain an `@' in |
| 528 |
their names. The commands \verb"\node" and \verb"\\" are only defined |
| 529 |
within the \verb"diagram" environment. Spaces following the |
| 530 |
\verb"\end{diagram}" are ignored. |
| 531 |
|
| 532 |
In all the macro files in this package, lines have been limited to |
| 533 |
less than~70 characters to avoid problems with electronic mailing. |
| 534 |
|
| 535 |
|
| 536 |
\section{Copyright and Acknowledgments} |
| 537 |
|
| 538 |
The \verb"pb-diagram" package is |
| 539 |
copyright \copyright\ 1990, 1992, 1995, 1998 by Paul Burchard. |
| 540 |
|
| 541 |
This program is free software; you can redistribute it and/or modify |
| 542 |
it under the terms of the GNU General Public License as published by |
| 543 |
the Free Software Foundation; either version 2 of the License, or |
| 544 |
(at your option) any later version. |
| 545 |
|
| 546 |
This program is distributed in the hope that it will be useful, |
| 547 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 548 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 549 |
GNU General Public License for more details. |
| 550 |
|
| 551 |
You should have received a copy of the GNU General Public License |
| 552 |
along with this program; if not, write to the Free Software |
| 553 |
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. |
| 554 |
|
| 555 |
The file \verb"pb-xy.sty" is |
| 556 |
copyright \copyright\ 1998 by Bill Richter, |
| 557 |
and is also distributed under the terms of the GNU General Public License. |
| 558 |
|
| 559 |
The fonts \verb"lams1.mf" through \verb"lams5.mf", as well as the |
| 560 |
macros in \verb"lamsarrow.sty", are copyright \copyright\ 1989, |
| 561 |
1990, 1991 by The Texplorators Corporation, 1572 West Gray \#377, |
| 562 |
Houston, TX 77019--4948. Beginning with version 4.1 of this package, |
| 563 |
the fonts include a patch by Ingo Hadan which makes them compatible |
| 564 |
with recent versions of \verb"cmbase.mf", and in particular, eliminating |
| 565 |
a division-by-zero error that caused certain glyphs to appear wildly deformed. |
| 566 |
|
| 567 |
I would like to acknowledge inspiration from a macro package of |
| 568 |
Marc-Paul van der Hulst. Bill Richter was of major help to me with |
| 569 |
his topological torture-testing of this package, and he provided |
| 570 |
some spectacular example diagrams for distribution with this package. |
| 571 |
Dan Christensen made many good suggestions which were incorporated |
| 572 |
into version 4.0. |
| 573 |
|
| 574 |
\end{document} |