Commutative Diagrams in TeX

Paul Taylor

since 1986

This is a macro package for drawing so-called "commutative" diagrams in category theory and related subjects.

The macros and the manual

Unlike many other packages there is no "installation procedure" - you just copy the macros themselves to your T_EX macros directory.

The manual is available in several formats: LaTeX source, PDF, DVI, 600dpi A4 PostScript and 600dpi A5 PS booklet. The "booklet" form requires a two-sided printer with A4 paper; if you don't have such a thing, don't bother taking the file.

If you have not already done so, please register as a user by sending a message to pt @ cs.man.ac.uk with the words "commutative diagrams" in the subject line.

I have also written some macros for proofs and other things.

Diagonal arrows, PostScript and PDF

T_EX itself and its basic output format (DVI) were designed by Donald Knuth to place letters and symbols from a variety of typefaces on an orthogonal grid, an idea that goes back to Gutenberg's original "movable type" printing press. This means that there is no natural way of drawing diagonal lines or rotating text.

Though DVI has the merit of simplicity, most complex documents nowadays in both the open-source and commercial worlds are distributed in Adobe's PostScript or PDF formats. In particular, the commonest way of printing (the DVI output from) T_EX documents is to use Tomas Rokicki's program dvips.

PostScript and PDF have a much more general coordinate system than T_EX has, and it is very easy to rotate blocks of text. The diagrams package was designed in 1992 to take advantage of this feature of PostScript and (from 2002) PDF. It was always intended to be used in this way, although only in 2004 was the default changed to use this.

Unfortunately, because of the inappropriately set optional behaviour, many users were not enjoying any of the benefits of the package. They were instead using the obsolete pre-1992 code (see below); this generated L^AT_EX-style arrows, that had incompatible arrowheads and didn't meet the objects to which they were supposed to point.

There are other graphical packages, including several that are also used to draw categorical diagrams, that draw diagonal lines in other ways, some of which are understood by xdvi. Like L^AT_EX's picture environment, they do this by juxtaposing many characters (such as diagonal line-segments or dots) from special fonts. These fonts need to be distributed and installed along with the macro packages themselves.

My diagrams package, on the other hand, needs no special fonts, and there is just the macro package itself to install. It achieves the same generality of diagonal arrows as it has horizontal ones by taking advantage of the method that most people use to print their documents. This design decision was taken following consultation with users, and I have always remained convinced that it was the correct one.

The method was adapted to pdftex. If xdvi or other programs implemented extensions to DVI to rotate boxes, it could be used for them too.

DVI previewers

DVI previewers such as xdvi and YAP do not understand the fragments of PostScript that are used to rotate the arrows, so what should be diagonal arrows appear horizontal instead. This behaviour is automatically corrected when you use dvips to print the document.

If, for some reason, you need to use xdvi or yap to display documents containing diagonals, you can still make use of the obsolete code. Use the command \usepackage [UglyObsolete,tight,heads=LaTeX] {diagrams} to load the diagrams package.

Please do not use the obsolete code for publication.

Previous generations understood that you had to understand what tools did and how they worked. Indeed, there was a saying that "bad workmen blame their tools". In the computer age, maybe even more so than in the pre-scientific one, people expect things to "just work", i.e. by magic, without understanding anything.

The pre-1992 pure DVI code in the diagrams package was a useful tool in its day, and I still try to make most of my diagrams work with it. However, if you wish to make extensive use of it, you too will have to understand how it works, and make the manual adjustments that are necessary to make up for the lack of magical programming behind it.

Firstly, since pure DVI cannot rotate characters, only the standard L^AT_EX arrowheads are available for diagonals, so you should only use the heads=LaTeX option, and not (for example) heads=vee.

Second, since it uses L^AT_EX's diagonal line and arrow characters, the only slopes that are allowed are those with numerator and denominator at most 4. However, since the package rounds slopes to simple rationals anyway (even in the "PostScript" code), this is not usually a problem in small diagrams.

But there is a more serious problem than this.

The package makes two "passes" when constructing each diagram: one in which it constructs a "matrix" from the data that you type, and a second in which it takes this matrix apart and stretches each of the arrows to meet its endpoints.

The obsolete "pure DVI" code constructs diagonal lines entirely in the first pass and does not stretch them in the second pass. It just makes a guess at the appropriate length, based on the width and height options for the diagram.

You should always choose the appropriate width and height yourself.

By default, the rows and columns of the diagram are loose - they stretch in the same way as any other matrix or table, and the "PostScript" code corrects for this. This default was chosen to make the package "just work", but diagrams look better if they are of a uniform regular size.

Since the obsolete pure DVI code does not make the necessary correction in the second pass, you have to make sure that its first guess is correct, by setting the width and height yourself, and making the diagram tight. When you set the tight option, you will find at first that the object labels sometimes overprint. The package generates error messages to tell you where this happens, and makes a suggestion for the appropriate size (common height and width), although this is usually too big.

Sometimes you will also need to adjust the shortfall of any arrows that point at large object labels, i.e. the distance between the end of the arrow and the object.

Finally, you may ask why I don't "fix" this code. Indeed I have looked into doing so several times. The answer is quite simply that the small benefit that would accrue from rewriting it does not justify the labour that would be needed. Not only is it much simpler to rotate horizontal arrows, but the the results are also far superior.

Arrowheads used in my book

You will see that the diagrams in my book Practical Foundations of Mathematics have arrowheads compatible with those of T_EX's ordinary \rightarrow. This was done by modifying the MetaFont source of \rightarrow to reduce its shaft to nothing, ie to make it just an arrowhead.

I regret that I will not be releasing this MetaFont code, or PK files derived from it, because I am not prepared to undertake the support work that would be necessary afterwards. (Not even if you "promise to keep it to yourself", as you will inevitably release DVI files into the world containing references to these characters, obliging me to provide PK files to your readers, and explain to them why they keep getting checksum errors from dvips.)

However, if you are intending to create a new symbols font yourself (to follow the "St. Mary Road" fonts), and undertake the necessary support work, I will be very pleased to give you the MetaFont source for these arrowheads and the other new symbols that are introduced in the book. I now have these in a form that's compatible with teTeX.

Features introduced since September 1992

See also the top of the source file for bug fixes and adjustments to the positioning of things.

3.91 Released 1 September 2006

3.90 Released 11 April 2004

PostScript mode made default.

3.89 Released 7 July 2002

Added support for pdftex, which is recognised automatically.

3.88 Released 1 September 2000

Square hooks made available as arrowtails:

   \newarrow{SquareInto}{sqhook}--->
   \begin{diagram}
        A & \rSquareInto B
   \end{diagram}

3.87 Released 1 September 1999

This version was used for the absolutely final 1200dpi PostScript copy of the book, as it was handed over to CUP in December 1998.

The only change was a 0.2pt fudge to the positioning of the components of arrows. Previously a lot of tweaking had been done in this department.

3.86 Released 1 September 1998

New options hug and nohug in PostScript mode:
```
   \diagramstyle[PS,nohug]
```
uses PostScript for the arrows without rotating the labels, but the way of calculating the actual position of these horizontal labels on will remain subject to alteration for some period of time - please send me examples if you feel that adjustment is needed.
midvshaft and snake for vertical arrows
New option
```
  \rTo[gap=5pt]
```
to create a gap in horizontals and PS diagonals, instead of the hack
```
  \rTo~{\;}
```
which caused ^ and _ labels to be moved too far away from the shaft. The width, here 5pt, defaults to the same value as shortfall.
Added >-> and /verb/<-</ arrowheads; these are the same as > and < but the shaft goes through the extra arrowhead.
Added 2pt space separating labels from vertical arrows.
Identify the cell in which a second-pass error occurs.
Corrected position of hook in \dInto (see \shifthook).
Corrections to \lhtriangle, \dhtriangle, and \newarrowtail{boldhook}.
Suppress indentation of text following diagram (due to L^AT_EX change).
Mangle \left@label and \right@label because of a conflict with Elsevier's macros.
Corrected dot spacing with [dotted] option.

3.85 Released 20 August 1997

New option [leftflush=margin] for left alignment of diagrams on a margin, instead of centering them. [leftflush] is like [flushleft], except that it reckons the alignment from multiple verticals, or from text if there's no vertical.
New options [hug] and [nohug] in PostScript mode: [PS,nohug] uses PS for the arrows without rotating the labels. Beware that this has been done in a lazy way by overprinting empty L^AT_EX-style diagonals carrying the labels, which may therefore be mis-placed.
New option [crab=distance] shifts horizontals and PS diagonals transversally by the specified distance. The abbreviations [crab+] and [crab-] use \PileSpacing, so to put four diagonal lines in parallel do something like
```
  \ruTo[crab--] \ldTo[crab-] \ruTo[crab+] \ldTo[crab++]
```
This doesn't work with [nohug].
New option [snake=distance] shifts the middle of midshaft horizontals and PS diagonals longitudinally by the specified distance.

3.84 Released 2 September 1996

Provided \NWclck etc 2-cell arrows.

3.83 Released 18 May 1995

New [dotted] option to change the filler on an arrow to dots (useful for mediators for universal properties).
Option [LaTeXeqno] uses L^AT_EX's equation number and style for "eqno"; L^AT_EX's \label command picks this up.

3.81 Released 18 July 1994

Stretchable PostScript diagonals implemented.
\overprint{text} sets text in maths and overprints it in the current cell, centered in the column irrespective of other stuff.
Option [repositionpullbacks] redefines \SEpbk etc to use \overprint.
New option [grid] to set column and row widths individually: see manual for examples such as a regular pentagon and cube with perspective.
Option [PostScript=name] takes the name of a DVI�PS translator as argument.
Equilateral triangle or regular hexagon size options.
Introduced landscape and portrait options.
Peter Freyd's \puncture symbol provided.

Earlier Version numbers

2 was circulated to some people in September 1989
3.16 was advertised on types and categories in July 1990 and emailed to those who asked for it.
3.18 was the final bug-fix before the re-write began in April 1992.
3.20 introduced error-recovery, and \newarrow for horizontals and verticals.
3.22 completely rewrote the reformatting program for h and corrected numerous alignment errors; introduced options in square brackets
3.23 fixed a catastrophic error in nested diagrams
3.24 extended \newarrow to diagonals, added trigonometry code, rewrote code for drawing L^AT_EX diagonals, introduced PostScript and TPIC diagonals, consistent choice of arrowheads.