Commutative Diagrams in TeXPaul 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.
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.
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.
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
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:
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.
See also the top of the source file for bug fixes and adjustments to the positioning of things.
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.
PostScript mode made default.
Added support for pdftex, which is recognised automatically.
\newarrow{SquareInto}{sqhook}--->
\begin{diagram}
A & \rSquareInto B
\end{diagram}
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.
\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.
\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.
>-> and <-< arrowheads; these are the same
as > and < but the shaft goes through the extra
arrowhead.
\dInto (see \shifthook).
\lhtriangle, \dhtriangle,
and \newarrowtail{boldhook}.
\left@label and \right@label because of a
conflict with Elsevier’s macros.
[dotted] 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.
[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 LATEX-style diagonals carrying the labels, which
may therefore be mis-placed.
[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].
[snake=distance] shifts the middle of midshaft
horizontals and PS diagonals longitudinally by the specified
distance.
Provided \NWclck etc 2-cell arrows.
[dotted] option to change the filler on an arrow to
dots (useful for mediators for universal properties).
[LaTeXeqno] uses LATEX’s equation number and style
for “eqno”; LATEX’s \label command picks this up.
\overprint{text} sets text in maths and overprints it in the
current cell, centered in the column irrespective of other stuff.
[repositionpullbacks]
redefines \SEpbk etc to use \overprint.
[grid] to set column and row widths individually:
see manual for examples such as a regular pentagon and cube with perspective.
[PostScript=name] takes the name of a DVI→PS
translator as argument.
\puncture symbol provided.
\newarrow for
horizontals and verticals.
\newarrow to diagonals, added
trigonometry code, rewrote code for drawing LATEX diagonals,
introduced PostScript and TPIC diagonals, consistent choice of
arrowheads.
This document was translated from LATEX by HEVEA.