Commutative Diagrams in TeX

Paul Taylor

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

Unlike many other packages there is no “installation procedure” — you just put the macros themselves in your TEX macros directory.

Version 3.96 was released on 31 December 2019.

If your browser displays the text of the macros instead of offering to save them to a file then you should “save page as diagrams.sty”. There is a danger that you will corrupt the text if you use “cut and paste”.

The MD5sum of V3,95.tex is 969b7e452df4ca4b2ca6722b530ea7c6

The manual is available in several formats: LaTeX source, PDF, DVI and 600dpi A4 PostScript.

If you have not already done so, please register as a user by sending a message to diagrams @ PaulTaylor.EU 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

TEX 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) TEX documents is to use Tomas Rokicki’s program dvips.

PostScript and PDF have a much more general coordinate system than TEX 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 LATEX-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 LATEX’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.

It also works automatically under XeTeX. I would like to thank Apostolos Syropoulos for his help in implementing this.

Although currently xdvi complains bitterly and refuses to work if DVI files contain boxes that have been rotated using embedded PostScript, I believe that it would in principle be possible to patch the xdvi program to do rotation of this kind. If this could be done then an extension to DVI could be agreed in the form of two special commands bturn and eturn.

See below for how to use the obsolete “pure DVI” code if you really have to.

License and obfuscated source

I have received a lot of personal abuse regarding this package.

From time to time people ask me to release it under a GPL or similar license. I have offered to do this if someone can identify a suitable standard license that does not require me to publish the (unobfuscated) source code.

The existing source code is not suitable for publication. I am the only person who is able to judge this. It contains a lot of personal notes from my learning of the details of how TEX works. It does not contain any adequate explanation of the workings of the diagrams package itself: that exists only inside my head.

It is on my personal agenda to edit, re-organise and amplify the source code to make it suitable for publication. However, doing so would not be a trivial task (especially if the result is still going to work!): I will need to devote my full concentration to it for a period of a few weeks, to the exclusion of everything else.

Unfortunately, my life in the past five years has not allowed me to concentrate even on my mathematical research, let alone on maintaining a program that in fact works pretty well. My mother was diagnosed with Alzheimer’s in November 2009 and died in January 2013. Although we did not know it at the time, my father also had a form of dementia (“with Lewy Bodies”) and died in February 2012. Meanwhile, my brother stole their money and behaved selfishly and arrogantly towards me. Now my priority is to do the repairs to my 1876 house in London that were neglected owing to lack of money and time.

Please note that, when I do eventually publish the source code, the obsolete “pure DVI” functions will be completely removed.

Using the obsolete “pure DVI” code

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 LATEX arrowheads are available for diagonals, so you should only use the heads=LaTeX option, and not (for example) heads=vee.

Second, since it uses LATEX’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.

I have analysed the log files for my site from September 2007 to November 2009. For just those files that I offer in multiple formats, counting each ip address just once for each file even if it downloaded it repeatedly and excluding known robots, I found that the distribution of accesses was:

PDF: 74%    DVI: 13%    PS: 8%    Booklet: 5%

Arrowheads used in my book

You will see that the diagrams in my book Practical Foundations of Mathematics have arrowheads compatible with those of TEX’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.95 Released 31 December 2014

3.94 Released 11 May 2011

3.93 Released 9 June 2009

The package now automatically recognises when it is being run under XeTeX. I would like to thank Apostolos Syropoulos for his help in implementing this.

3.92 Released 31 December 2007

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

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

3.85 Released 20 August 1997

3.84 Released 2 September 1996

Provided \NWclck etc 2-cell arrows.

3.83 Released 18 May 1995

3.81 Released 18 July 1994

Earlier Version numbers

This document was translated from LATEX by HEVEA.