\documentclass{article}
\input diagxy
\xyoption{curve}
\begin{document}
\def\xypic{\hbox{\rm\Xy-pic}}
\title{A new diagram package (Version 2)}
\author{Michael Barr\\Dept of Math and Stats\\McGill University\\805
Sherbrooke St. W\\Montreal, QC Canada H3A 2K6\\[5pt] barr(a)barrs.org}
\maketitle
\section*{Why a new diagram package?}
This started when a user of my old package, diagram, wrote to ask me if
dashed lines were possible. The old package had dashed lines for
horizontal and vertical arrows, but not any other direction. The reason
for this was that \LaTeX\ used rules for horizontal and vertical arrows,
but had its own fonts for other directions. While rules could be made
any size, the smallest lines in other directions were too long for
decent looking dashes. Presumably, Lamport was worried about compile
time and file size if the lines were too short, considerations that have
diminished over the years since. Also arrows could be drawn in only 48
different directions, which is limiting. My macros were not very well
implemented for slopes like 4 and 1/4, since I never used such lines.
There was certainly an alternative, \xypic, for those who wanted
something better. But it was hard to learn and I was not entirely happy
with the results. The basic interface used an \verb+\halign+. This
meant that no extra space was allotted to an arrow that had a large
label. In addition, the different slots could have different horizontal
size, which could result in a misshapen diagram. I used it in a paper
that had a `W' shaped diagram whose nodes had different widths and the
result was quite obviously misshapen. On the other hand, the graphics
engine underlying \xypic\ is really quite remarkable and it occurred to
me that I could try to redraft diagram as a front end. The result is
the current package. It has been tested only with version 3.7, so there
is no guarantee it would work with any earlier version (or, for that
matter, later).
The syntax described below is not compatible with the original diagram
package. Every front end of this sort represents a trade-off between
simplicity and utility. A package that simply upgraded the syntax to
allow more dashed (and dotted) lines would have been just as easy to
implement, but would have made poor use of the wonderful possibilities
of the underlying \xypic\ package. Also there would have been too many
different arrow specifications (they would have had to go at least in
the range $[-9,9]$) for easy memory) and still would not have included
things like inclusion arrows. To those who would have liked a simpler
syntax, I apologize. To those who would want more flexibility, I remind
that the entire \xypic\ package is there for use.
There is one point that cannot be made too strongly. {\em Watch for
errant spaces.} Unlike the diagram package, which was carried out in
math mode so that spaces were ignored. \xypic\ is not in math mode and
spaces will mess up your diagrams. Unlike diagram, it should not be
necessary to put any objects inside \verb+\phantom+. In diagram, for
reasons that I now understand, objects did not always register properly.
This was a flaw built in to the very heart of the package and is not
worth correcting, although it could have been done better in the first
place. If you see an object in double vision, then the virtually
certain cause is that a space has gotten in there somewhere. I have
attempted to prevent this by liberal use of \verb+\ignorespaces+ in the
definitions, but one cannot always be sure and while testing, I found a
number seemingly innocuous spaces that messed up diagrams.
\subsection*{Differences from the previous version}
\begin{enumerate}
\item \verb+\scalefactor{decimal number}+ changes all dimensions by the
factor.
\item New macros \verb+\Square, \hSquares, \vSquares+ that calculate
their own widths.
\item New macro \verb+\cube+.
\item Internal macro \verb+\label+ that conflicted with \LaTeX\ renamed.
\item Added certain procedures designed for inline and displayed
equations that are not full-fledged diagrams. These also calculate
the length of the arrow to contain the label.
\item Corrected certain spacing anomolies.
\item Now does work with plain \TeX.
\end{enumerate}
\section*{The basic syntax}
The basic syntax is built around an operation \verb+\morphism+ that is
used as
\begin{verbatim}
\morphism(x,y)|label pos|/{shape}/<dx,dy>[N`N`A]
\end{verbatim}
The parameters \verb+x+ and \verb+y+ give the location of the source
node within a fixed local coordinate system and \verb-x+dx- and
\verb-y+dy- and locate the target. To be precise, the first coordinate
is the horizontal center of the node and the second is that of the base
line. These distances are given in terms of \verb+\ul+'s, (for
unitlength), which is user assignable. I have, for the time being, set
it to .01em, which is probably too small. In the original version of
diagram, it was .1em. This was reasonable for diagrams, but since the
multipliers had to be integers, it turned out to inconveniently large
for certain internal computations. (Strictly speaking, the multipliers
could be any decimal number, but \TeX\ does not permit arithmetic with
any but whole numbers.) Since all the internal computations are carried
out by \xypic, this is no longer a consideration and in the production
version, I may go back to the original .1em. Note that by basing
distances on ems, I make things automatically scale when changing point
size. The parameter \verb+label pos+ is one of \verb+a,b,l,r,m+ that
stand for above, below, left, right, or mid and describe the positioning
of the arrow label on the arrow. The label \verb+m+ stands for a label
positioned in the middle of a split arrow. Although \verb+a+ and
\verb+b+ can be used in any direction, they give uncertain results when
used on vertical arrows and similarly \verb+l+ and \verb+r+ should not
be used on horizontal arrows.
The \verb+shape+ describes the shape of the arrow. An arrow is thought
of as consisting of three parts, the tail, the shaft and the head. You
may specify just the head, in which case the shaft will be an ordinary
line, or all three. However, since the tail can be (and usually is)
empty, in practice you can also describe the shaft and tail. In
addition, it is possible to modify the arrow in various ways. Although
the parameter is shown within braces, the braces can be omitted unless
one of the modifier characters is \verb+/+, in which case, {\em the
entire parameter} must be put in braces. It is important to
note that it will not work just to put the \verb+/+ inside the braces,
since this will interfere with the internal parsing of \xypic. The head
and tail shapes are basically one of \verb+>+, \verb+>>+, \verb+(+,
\verb+)+, \verb*+ >+, and \verb*+< +. Each of these may also be
preceded by \verb+^+ or \verb+_+ and others are user definable. For
details, see the \xypic\ reference manual. The first of these is an
ordinary head, while the second is for an epic arrow. The third is not
much used, but the superscripted version makes and inclusion tail, as
will be illustrated below. The reverse ones give reversed arrowheads.
The sign \verb*+ + stands for an obligatory space and it leaves extra
space for a tailed (monic) arrow, which otherwise runs into the source
node. Although there are many possibilities for shafts, including
alphanumeric characters, there are basically three that interest us:
\verb+-+, which is an ordinary shaft, \verb+--+, which produces a dashed
arrow, \verb+=+, which gives a double arrow (although with only one
arrowhead), and
\verb+.+, which makes a dotted arrow. Thus
\verb+>+ or
\verb+->+ will produce an ordinary arrow, \verb+->>+ an epic arrow,
\verb*+ >->+ makes a monic arrow, and \verb+-->>+ would make a dashed
epic arrow. The descriptions \verb+<-, <<-,+ \verb*+<-< +, and
\verb+<<--+ give the reversed versions. Note that \verb+<+ does not
give a reversed arrow, since \xypic\ interprets that as a reversed head,
not a tail.
If the shape parameter begins with an \verb+@+, it is interpreted
differently. In that case, it has the form \verb+@{shape}@+ modifier,
where the modifier is as described in the \xypic\ reference guide. I
just mention a couple of them. The parameter \verb+@{->}@<3pt>+, for
example, would give an ordinary arrow moved three points in the
direction perpendicular to that of the arrow. If you give
\verb+{@{-->}@/^5pt/}+, you will get an epic arrow that is curved in the
direction perpendicular to the direction of the arrow by five points.
(As far as I can tell, there is no difference between
\verb+^-5pt+ and
\verb+_5pt+ so the syntax could be simplified and made consistent with
that of \verb+<dimen>+ described above.)
It is imperative that a specification such as \verb+@{>}@/5pt/+ be
enclosed in braces because of the \verb+/+s.
Finally, the \verb+N+s are the source and
target of the arrow and \verb+L+ is the label. Currently, the \verb+L+
is set in \verb+\scriptstyle+ size, but this can easily be changed by
putting \verb+\let\labelstyle=\textstyle+ in your file.
\subsection*{A word about parameters}
I have already mentioned the necessity of enclosing certain arrow shape
specifications in braces. Owing to certain built-in limitations of
\TeX, I have used a number of different delimiters:
\verb+(, ), |, /, [, ], `, ;+. Any of these that appear inside an
argument could conceivably cause problems. They were chosen as the
least likely to appear
inside mathematics (except for \verb+(, )+ which appear in positions
that are unlikely to cause problems). However, be warned that this is a
possible cause of mysterious error messages. If it is indeed then
enclosing the offending parameter in braces should cure the problem. In
most, but not all, cases, enclosing the offending character will solve
the problem. The exceptions come when the braces interfere with
\xypic's somewhat arcane parsing mechanism. There will be no problem if
it is just part of a mathematical expression.
\section*{Shapes}
Using the basic \verb+\morphism+ macro, I have a defined a number of
shapes, squares (really rectangles) and variously oriented triangles. I
will probably do a few other shapes as I had done for the old package,
such as \verb+\cube+ and a $3 \times 3$ diagram. The basic shapes are
exactly the same, but the options are done entirely differently. Here
is the syntax of the \verb+\square+ macro:
\begin{verbatim}
\square(x,y)|lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}/<dx,dy>[N`N`N`N;L`L`L`L]
\end{verbatim}
Each of the first four sets of parameters is optional and any subset of
them can be omitted. (Note that only the sets can be omitted, once you
give \verb+dx+, you also have to give \verb+dy+ and so on.) The first
two describe the horizontal and vertical size of the square, the next
four give the label placements using the same five characters as above,
the next four give the shapes of the arrows using the same syntax as
discussed above. The last group is the location. The meaning of this
varies a bit with the shape. For a square, it is the midpoint of the
baseline of the lower left corner node. For a triangle that has a lower
left corner, it is the same. Otherwise, \verb+x+ is the midpoint of the
leftmost node and \verb+y+ is the baseline of the lowest node. As with
the old macros, different shapes should fit together accurately, in fact
more accurately than with the old ones.
Here is a listing of the shapes, together with the groups of parameters.
In all cases, the first four groups are optional and any subset of them
will work. However, they must come in order. Note that the names of
the triangles are related to the shape as the shape that best
approximates the shape of the letter. For example, a \verb+\ptriangle+
is a right triangle that has its hypotenuse going from upper right to
lower left. Triangles with lower case names have their legs horizontal
and vertical, while those with capitalized names have their hypotenuse
horizontal or vertical. In those cases, one of \verb+dx+ or \verb+dy+
is the length of a leg and the other is {\em half} the length of the
hypotenuse. In all cases, the order of the nodes and of the arrows is
linguistic, first moving from left to right and then down. The defaults
are reasonable, but with triangles, there is not always a natural
direction for arrows. I always made mistakes in the order with my
macros and this is certainly a defect. But the order is the same. In
every case the braces around the shape specification can be removed
unless it includes the following delimiter (that is, \verb+`+ or
\verb+/+, as the case may be.)
\begin{verbatim}
\square(x,y)|lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}/<dx,dy>%
[N`N`N`N;L`L`L`L]
\ptriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\qtriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\dtriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\btriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\Atriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\Vtriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\Ctriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\Dtriangle(x,y)|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N`N`N;L`L`L]
\Atrianglepair(x,y)|lp`lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}`{sh}/%
<dx,dy>[N`N`N`N;L`L`L`L`L]
\Vtrianglepair(x,y)|lp`lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}`{sh}/%
<dx,dy>[N`N`N`N;L`L`L`L`L]
\Ctrianglepair(x,y)|lp`lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}`{sh}/%
<dx,dy>[N`N`N`N;L`L`L`L`L]
\Dtrianglepair(x,y)|lp`lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}`{sh}/%
<dx,dy>[N`N`N`N;L`L`L`L`L]
\end{verbatim}
(Of course, the \verb+%+ signs are required if you break the
macro at such points.)
To make a diagram, you have to enclose it inside \verb+\xy ... \endxy+.
You will almost always want it displayed, for which the simplest is to
enclose it in \verb+$$\xy ... \endxy$$+. For old times sake, I have
also let \verb+\bfig+ and \verb+\efig+ be synonyms for \verb+\xy+ and
\verb+\endxy+, resp. (In case you wonder, these go all the back to a
main frame formatter running at McGill when Charles Wells and I were
first writing TTT, where \verb+.BFIG+ and \verb+.EFIG+ were used to make
displays, at least as far as that primitive formatter was capable of.)
You could instead make definitions as follows:
\begin{verbatim}
\def\bfig{$$\xy}
\def\efig{\endxy$$}
\end{verbatim}
in which case you will automatically get a display. I do not do this
because my spelling checker is programmed to ignore stuff in math or
display mode and the \verb+$$+ marks the display mode. Besides which, I
have defined the \verb+Ctl-F+ key on my editor so that pressing it gives
\begin{verbatim}
$$\bfig
_
\efig$$
\end{verbatim}
with the cursor at the position marked by the underline.
\section{Examples}
Many people---including me--- learn mainly by example and
I will give a number of examples here. The formal
syntax can be learned in the \xypic\ reference manual. We begin with
\begin{verbatim}
$$\bfig
\square[A`B`C`D;e`f`g`m]
\efig$$
\end{verbatim}
produces
$$\bfig
\square[A`B`C`D;e`f`g`m]
\efig$$
This can be modified, for example
\begin{verbatim}
$$\bfig
\square/>>`>`>` >->/[A`B`C`D;e`f`g`m]
\efig$$
\end{verbatim}
produces
$$\bfig
\square/>>`>`>` >->/[A`B`C`D;e`f`g`m]
\efig$$
This can be put together with a morphism as follows:
\begin{verbatim}
$$\bfig
\square/>>`>`>` >->/[A`B`C`D;e`f`g`m]
\morphism(500,500)|m|/.>/<-500,-500>[B`C`h]
\efig$$
\end{verbatim}
which makes a familiar diagram:
$$\bfig
\square/>>`>`>` >->/[A`B`C`D;e`f`g`m]
\morphism(500,500)|m|/.>/<-500,-500>[B`C`h]
\efig$$
The same diagram could have been made by
\begin{verbatim}
$$\bfig
\ptriangle|a`l`m|/>>`>`.>/[A`B`C;e`f`h]
\dtriangle/`>` >->/[B`C`D;`g`m]
\efig$$
\end{verbatim}
You can fit two squares together, horizontally:
\begin{verbatim}
$$\bfig
\square|a`l`m`b|[A`B`C`D;f`g`h`k]
\square(500,0)/>``>`>/[B`E`D`F;l``m`n]
\efig$$
\end{verbatim}
$$\bfig
\square|a`l`m`b|[A`B`C`D;f`g`h`k]
\square(500,0)/>``>`>/[B`E`D`F;l``m`n]
\efig$$
or vertically
\begin{verbatim}
$$\bfig
\square(0,500)|a`l`r`m|[A`B`C`D;f`g`h`k]
\square/`>`>`>/[C`D`E`F;`l`m`n]
\efig$$
\end{verbatim}
$$\bfig
\square(0,500)|a`l`r`m|[A`B`C`D;f`g`h`k]
\square/`>`>`>/[C`D`E`F;`l`m`n]
\efig$$
or a square and a triangle
\begin{verbatim}
$$\bfig
\Ctriangle/<-`>`>/<400,400>[\hbox{\rm rec}(A,B)`B`X;r_0(A,B)`f`t_0]
\square(400,0)/<-``>`<-/<1000,800>[\hbox{\rm rec}(A,B)`A\times\hbox{\rm
rec}(A,B)`X`A\times X;r(A,B)``\hbox{\rm id}_A\times f`t]
\efig$$
\end{verbatim}
gives the diagram
$$\bfig
\Ctriangle/<-`>`>/<400,400>[\hbox{\rm rec}(A,B)`B`X;r_0(A,B)`f`t_0]
\square(400,0)/<-``>`<-/<1000,800>[\hbox{\rm rec}(A,B)`A\times\hbox{\rm
rec}(A,B)`X`A\times X;r(A,B)``\hbox{\rm id}_A\times f`t]
\efig$$
This diagram is on page 361 of the third edition of Category Theory for
Computing Science to describe recursion.
Here is an example using the procedure for sliding an arrow sideways.
This one could even be used in a text,
\xy \morphism(0,0)|a|/@{>}@<3pt>/<400,0>[A`B`d]
\morphism(0,0)|b|/@{>}@<-3pt>/<400,0>[A`B`e]\endxy
which was made using
\begin{verbatim}
\xy \morphism(0,0)|a|/@{>}@<3pt>/<400,0>[A`B`d]
\morphism(0,0)|b|/@{>}@<-3pt>/<400,0>[A`B`e]\endxy
\end{verbatim}
Later we will introduce a number of inline procedures.
Something a bit different that illustrates the use of another shaft
\verb+=+ that gives a 2-arrow, as well as curved arrows:
\begin{verbatim}
$$\bfig
\morphism(0,0)|a|/{@{>}@/^1em/}/<500,0>[A`B`f]
\morphism(0,0)|b|/{@{>}@/_1em/}/<500,0>[A`B`g]
\morphism(250,50)|a|/=>/<0,-100>[``]
\efig$$
\end{verbatim}
$$\bfig
\morphism(0,0)|a|/{@{>}@/^1em/}/<500,0>[A`B`f]
\morphism(0,0)|b|/{@{>}@/_1em/}/<500,0>[A`B`g]
\morphism(250,50)|a|/=>/<0,-100>[``]
\efig$$
In order to use curved arrows, you must insert \verb+\xyoption{curve}+
into your file. Here are two ways of doing three arrows between two
objects, depending on what you like:
\begin{verbatim}
$$\bfig
\morphism(0,0)|a|/@{>}@<5pt>/<500,0>[A`B`f]
\morphism(0,0)|m|/@{>}/<500,0>[A`B`g]
\morphism(0,0)|b|/@{>}@<-5pt>/<500,0>[A`B`h]
\efig$$
\end{verbatim}
which gives
$$\bfig
\morphism(0,0)|a|/@{>}@<5pt>/<500,0>[A`B`f]
\morphism(0,0)|m|/@{>}/<500,0>[A`B`g]
\morphism(0,0)|b|/@{>}@<-5pt>/<500,0>[A`B`h]
\efig$$
and
\begin{verbatim}
$$\bfig
\morphism(0,0)|a|/{@{>}@/^5pt/}/<500,0>[A`B`f]
\morphism(0,0)|m|/@{>}/<500,0>[A`B`g]
\morphism(0,0)|b|/{@{>}@/^-5pt/}/<500,0>[A`B`h]
\efig$$
\end{verbatim}
which gives
$$\bfig
\morphism(0,0)|a|/{@{>}@/^5pt/}/<500,0>[A`B`f]
\morphism(0,0)|m|/@{>}/<500,0>[A`B`g]
\morphism(0,0)|b|/{@{>}@/^-5pt/}/<500,0>[A`B`h]
\efig$$
Either of these could also be used inline.
There is a macro \verb+\place(x,y)[N]+ where \verb+N+
is any object that places that object anywhere. I have changed the name
in order to avoid clashing with the \LaTeX\ picture mode's \verb+\put+.
Here is an example that uses a construction that is undocumented here,
but uses a documented \Xy\ construction:
\begin{verbatim}
\newbox\anglebox
\setbox\anglebox=\hbox{\xy \POS(75,0)\ar@{-} (0,0) \ar@{-} (75,75)\endxy}
\def\angle{\copy\anglebox}
$$\bfig
\square[A`B`C`D;f`g`h`k]
\place(100,400)[\angle]
\efig$$
\end{verbatim}
\newbox\anglebox
\setbox\anglebox=\hbox{\xy \POS(75,0)\ar@{-} (0,0) \ar@{-} (75,75)\endxy}
\def\angle{\copy\anglebox}
$$\bfig
\square[A`B`C`D;f`g`h`k]
\place(100,400)[\angle]
\efig$$
Notice that you get a headless arrow by using \verb+\ar@{-}+.
Here is a special code installed at the request of Jonathon Funk:
\begin{verbatim}
$$\bfig
\pullback|b`r`r`b|<800,800>[P`X`Y`Z;t`u`v`w]%
|a`m`b|/>`-->`>/<500,500>[A;f`g`h]
\efig$$
\end{verbatim}
$$\bfig
\pullback|b`r`r`b|<800,800>[P`X`Y`Z;t`u`v`w]%
|a`m`b|/>`-->`>/<500,500>[A;f`g`h]
\efig$$
The full syntax for this is
\begin{verbatim}
\pullback(x,y)|lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}/<dx`dy>[N`N`N`N;L`L`L]%
|lp`lp`lp|/{sh}`{sh}`{sh}/<dx,dy>[N;L`L`L]
\end{verbatim}
Of these only the nodes placed inside brackets are obligatory. The
first sets of parameters are exactly as for \verb+\square+ and the
remaining parameters are for the nodes and labels of the outer arrows.
There is no positioning parameters for them; rather you set the
horizontal and vertical separations of the outer node from the square.
Here are some more special constructions. In general, if you are doing
a square, you should use \verb+\Square+ instead of \verb+\square+
because if figures its own width. The syntax is almost the same, except
that \verb+dx+ is omitted. For example,
\begin{verbatim}
$$\bfig
\Square/^{ (}->`>`>`^{ (}->/<350>[{\rm Hom}(A,2^B)`{\rm Sub}(A\times B)`
{\rm Hom}(A',2^{B'})`{\rm Sub}(A'\times B');\alpha(A,B)```\alpha(A',B')]
\efig$$
\end{verbatim}
will produce the square
$$\bfig
\Square/^{ (}->`>`>`^{ (}->/<350>[{\rm Hom}(A,2^B)`{\rm Sub}(A\times B)`
{\rm Hom}(A',2^{B'})`{\rm Sub}(A'\times B');\alpha(A,B)```\alpha(A',B')]
\efig$$
There are a couple of points to note here. Note the use of the
argument \verb+^{ (}->+ to get the inclusion arrow. The complication is
created by the necessity of adding a bit of extra space before the hook.
You get pretty much the same effect by putting a bit of extra space
after the node:
\begin{verbatim}
$$\bfig
\Square/^(->`>`>`^(->/<350>[{\rm Hom}(A,2^B)\,`{\rm Sub}(A\times B)`
{\rm Hom}(A',2^{B'})\,`{\rm Sub}(A'\times B');\alpha(A,B)```\alpha(A',B')]
\efig$$
\end{verbatim}
The full syntax is
\begin{verbatim}
\Square(x,y)|lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}/<dy>[N`N`N`N;L`L`L`L]
\end{verbatim}
There are also macros for placing two \verb+\Square+s together
horizontally or vertically. The first is \verb+\hSquares+ with the
syntax
\begin{verbatim}
\hSquares(x,y)|lp`lp`lp`lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}`{sh}`{sh}`{sh}/%
<dy>[N`N`N`N`N`N;L`L`L`L`L`L`L]
\end{verbatim}
The second is \verb+\vSquares+ with a similar syntex except that there
are two \verb+dy+ parameters, one for each square:
\begin{verbatim}
\hSquares(x,y)|lp`lp`lp`lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}`{sh}`{sh}`{sh}/%
<dy,dy>[N`N`N`N`N`N;L`L`L`L`L`L`L]
\end{verbatim}
There is a macro for making cubes. The syntax is
\begin{verbatim}
\cube(x,y)|lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}/<dx,dy>[N`N`N`N;L`L`L`L]%
(x,y)|lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}/<dx,dy>[N`N`N`N;L`L`L`L]%
|lp`lp`lp`lp|/{sh}`{sh}`{sh}`{sh}/[L`L`L`L]
\end{verbatim}
The first line of parameters is for the outer square and the second for
the inner square, while the remaining parameters are for the arrows
between the squares. Only the parameters in square brackets are
required; there are defaults for the others. Here is an example:
\begin{verbatim}
$$\bfig
\cube(0,0)|a`r`l`b|/ >->` >->`>`>/<1500,1500>[A`B`C`D;f`g`h`k]%
(300,300)|a`r`l`b|/>`>`>`>/<400,400>[A'`B'`C'`D';f'`g'`h'`k']%
|m`m`m`m|/<-`<-`<-`<-/[\alpha`\beta`\gamma`\delta]
\efig$$
\end{verbatim}
gives the somewhat misshapen diagram
$$\bfig
\cube(0,0)|a`r`l`b|/ >->` >->`>`>/<1500,1500>[A`B`C`D;f`g`h`k]%
(300,300)|a`r`l`b|/>`>`>`>/<400,400>[A'`B'`C'`D';f'`g'`h'`k']%
|m`m`m`m|/<-`<-`<-`<-/[\alpha`\beta`\gamma`\delta]
\efig$$
because the parameters were oddly chosen. The defaults center the
squares. I discovered accidently, while debugging the cube that what I
though was an out-of-range choice of parameters would produce an offset
cube:
\begin{verbatim}
$$\bfig
\cube|a`r`l`b|/ >->` >->`>`>/<1000,1000>[A`B`C`D;f`g`h`k]%
(400,400)|a`r`l`b|/>`>`>`>/<900,900>[A'`B'`C'`D';f'`g'`h'`k']%
|r`r`r`r|/<-`<-`<-`<-/[\alpha`\beta`\gamma`\delta]
\efig$$
\end{verbatim}
gives
$$\bfig
\cube|a`r`l`b|/ >->` >->`>`>/<1000,1000>[A`B`C`D;f`g`h`k]%
(400,400)|a`r`l`b|/>`>`>`>/<900,900>[A'`B'`C'`D';f'`g'`h'`k']%
|r`r`r`r|/<-`<-`<-`<-/[\alpha`\beta`\gamma`\delta]
\efig$$
\subsection*{Empty placement and moving labels}
The label placements within \verb+|x|+ is valid only for
\verb+x = a,b,r,l,m+. If you use any other value, or leave it empty,
the label entry is ignored, but you can use any valid \xypic\ label, as
described in Figure 13 of the reference manual. One place you might
want to use this is for the placement of the labels along an arrow. In
\xypic\ the default placement of the label is midway between the
midpoints of the nodes. If the two nodes are of widely different sizes,
this can result in strange placements; therefore I always place them
midway along the arrow. However, as the following illustrates, this can
be changed.
\begin{verbatim}
$$\bfig
\morphism(0,900)||/@{->}^<>(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,600)||/@{->}^<(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,300)||/@{->}^>(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,0)||/@{->}^(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\efig$$
\end{verbatim}
which produces
$$\bfig
\morphism(0,900)||/@{->}^<>(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,600)||/@{->}^<(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,300)||/@{->}^>(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,0)||/@{->}^(0.7){f}/<800,0>[A^B\times B^C\times C`C`]
\efig$$
Here is the explanation. The label placement argument is empty (it
cannot be omitted) and the arrow entry is empty. However, placing
\verb+^(0.7){f}+ inside the arrow shape places the label \verb+f+ 7/10
of the way between the nodes. Unmodified, this places it 7/10 of the
way between the centers of the nodes. This may be modified by \verb+<+,
which moves the first (here the left) reference point to the beginning
of the arrow, \verb+>+ which moves the second reference point to the end
of the arrow, or by both, which moves both reference points. In most
cases, you will want both. Incidentally, \verb+-+ is a synonym for the
sequence \verb+<>(.5)+ and that is the default placement in my package.
Here are some more examples that illustrates the special sequence
\verb+\hole+ used in conjunction with \verb+|+ that implements
\verb+m+ as well as the fact that these things can be stacked. For more
details, I must refer you to the reference manual.
\begin{verbatim}
$$\bfig
\morphism(0,600)||/@{->}|-\hole/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,300)||/@{->}|-\hole^<>(.7)f/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,0)||/@{->}|-\hole^<>(.7)f_<>(.3)g/<800,0>[A^B\times
B^C\times C`C`]
\efig$$
\end{verbatim}
produces
$$\bfig
\morphism(0,600)||/@{->}|-\hole/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,300)||/@{->}|-\hole^<>(.7)f/<800,0>[A^B\times B^C\times C`C`]
\morphism(0,0)||/@{->}|-\hole^<>(.7)f_<>(.3)g/<800,0>[A^B\times
B^C\times C`C`]
\efig$$
Here is another version of the cube we looked at above, using these
special placements and \verb+\hole+'s to break some lines and make it
neater.
\begin{verbatim}
$$\bfig
\cube|a`r`l`b|/@{ >->}^<>(.6){f}` >->`@{>}_<>(.4){h}`>/%
<1000,1000>[A`B`C`D;`g``k]%
(400,400)|a```b|/>`@{>}|(.33)\hole^<>(.6){g'}`>`@{>}%
|(.67)\hole_<>(.4){k'}/<900,900>[A'`B'`C'`D';f'``h'`]%
|r`r`r`r|/<-`<-`<-`<-/[\alpha`\beta`\gamma`\delta]
\efig$$
\end{verbatim}
$$\bfig
\cube|a`r`l`b|/@{ >->}^<>(.6){f}` >->`@{>}_<>(.4){h}`>/%
<1000,1000>[A`B`C`D;`g``k]%
(400,400)|a```b|/>`@{>}|(.33)\hole^<>(.6){g'}`>`%
@{>}|(.67)\hole_<>(.4){k'}/<900,900>[A'`B'`C'`D';f'``h'`]%
|r`r`r`r|/<-`<-`<-`<-/[\alpha`\beta`\gamma`\delta]
\efig$$
This one is probably worth saving as a template. Note that the
\verb+\hole+'s by reference to the center of the nodes. That way they
will always miss hitting the arrows no matter what the size of the node.
If the nodes are unusually large, the cube may be magnified using
\verb+\scalefactor+.
\subsection*{Inline macros}
Here we illustrate a few of the macros for inline---or
displayed---equations the package contains. In each case, the macro may
have a superscript or subscript or both (in which case the superscript
must come first) and the arrow(s) grow long enough to hold the super- or
subscript. If you type
\verb+$A\to B\to^f C\to_g D\to^h_{{\rm Hom}(X,Y)} E$+, you get
$A\to B\to^f C\to_g D\to^h_{{\rm Hom}(X,Y)} E$. Similarly, the macro
\verb+\toleft+ reverses the arrows. The remaining macros of this sort
are \verb+\mon+ which gives a monic arrow, \verb+\epi+ which gives an
epic arrow, \verb+\two+ that gives a pair of arrows, as well as
leftwards pointing versions, \verb+\monleft+, \verb+\epileft+, and
\verb+twoleft+ of each of them. Here is one more
example:
\begin{verbatim}
$A\twoleft B\twoleft^f C\twoleft_g D\twoleft^h_{{\rm Hom}(X,Y)} E$
\end{verbatim}
gives $A\twoleft B\twoleft^f C\twoleft_g D\twoleft^h_{{\rm Hom}(X,Y)} E$.
There is an almost unlimited variety of such procedures possible. The
ones that are provided can be used as templates to define new ones with,
say, curved arrows or three arrows or whatever a user might have need
of.
\subsection*{2-arrows}
There is a macro for making 2-arrows of a fixed size, but varying
orientation. They should be put at the appropriate position in a
diagram. The size actually varies with the direction by about 10\%
because there is no simple way of implementing the sin$\circ$arctan and
cos$\circ$arctan functions and I have used rational approximating
functions, but the variation seems acceptable. The worst cases are
those of slopes $\pm3$ and $\pm1/3$, which are about 5\% too short, and
$\pm1$, which are about 5\% too long. These two cases are illustrated
below. The two parameters are two integers \verb+dx+ and \verb+dy+
whose ratio is the slope of the arrow. They need not be relatively
prime, but arithmetic overflow could occur if they were too large. Here
is a sampler
\begin{verbatim}
$$\bfig
\place(0,0)[\twoar(1,0)]
\place(200,0)[\twoar(0,1)]
\place(400,0)[\twoar(1,1)]
\place(600,0)[\twoar(0,-1)]
\place(800,0)[\twoar(1,2)]
\place(1000,0)[\twoar(1,3)]
\place(1200,0)[\twoar(1,-3)]
\place(1400,0)[\twoar(-3,1)]
\place(1600,0)[\twoar(-1,-3)]
\place(1800,0)[\twoar(255,77)]
\efig$$
\end{verbatim}
$$\bfig
\place(0,0)[\twoar(1,0)]
\place(200,0)[\twoar(0,1)]
\place(400,0)[\twoar(1,1)]
\place(600,0)[\twoar(0,-1)]
\place(800,0)[\twoar(1,2)]
\place(1000,0)[\twoar(1,3)]
\place(1200,0)[\twoar(1,-3)]
\place(1400,0)[\twoar(-3,1)]
\place(1600,0)[\twoar(-1,-3)]
\place(1800,0)[\twoar(255,77)]
\efig$$
\subsection*{Diagram from TTT}
The last example is a complicated diagram from TTT:
\begin{verbatim}
$$\bfig
\morphism(0,2100)|l|/>/<0,-1400>[TT`TT'T`T\eta'T]
\morphism(0,2100)|a|/>/<700,0>[TT`T`\mu]
\morphism(0,2100)|l|/>/<700,-700>[TT`TTT'`TT\eta']
\morphism(700,2100)|r|/>/<700,-700>[`TT'`T\eta]
\place(700,1750)[1]
\morphism(700,1400)|b|/@<-20\ul>/<700,0>[TTT'`TT'`T\sigma]
\square(700,700)|a`m`m`a|/@<20\ul>`>``>/<700,700>[TTT'`
TT'`TT'TT'`TT'T';\mu T' `T\eta'TT'``]
\morphism(700,700)|a|/>/<700,0>[TT'TT'`TT'T'`TT'\sigma]
\place(300,1400)[2]
\place(1050,1050)[3]
\btriangle(1400,700)|m`r`a|/>`>`>/<700,700>[TT'`TT'T'`TT';
T\eta'T'`\hbox{\rm id}`]
\place(1600,1050)[6]
\square|a`l`m`b|<700,700>[TT'T`TT'TT'`T'T`T'TT';
TT'T\eta'`\sigma T`\sigma TT'`T'T\eta']
\square(1400,0)|a`m`r`b|<700,700>[TT'T'`TT'`T'T'`T';
T\mu'`\sigma T' `\sigma`\mu']
\morphism(700,0)|b|/>/<700,0>[T'TT'`T'T'`T'\sigma T']
\place(300,350)[4]
\place(1050,350)[5]
\place(1750,350)[7]
\efig$$
\end{verbatim}
$$\bfig
\morphism(0,2100)|l|/>/<0,-1400>[TT`TT'T`T\eta'T]
\morphism(0,2100)|a|/>/<700,0>[TT`T`\mu]
\morphism(0,2100)|l|/>/<700,-700>[TT`TTT'`TT\eta']
\morphism(700,2100)|r|/>/<700,-700>[`TT'`T\eta]
\place(700,1750)[1]
\morphism(700,1400)|b|/@<-20\ul>/<700,0>[TTT'`TT'`T\sigma]
\square(700,700)|a`m`m`a|/@<20\ul>`>``>/<700,700>[TTT'`
TT'`TT'TT'`TT'T';\mu T' `T\eta'TT'``]
\morphism(700,700)|a|/>/<700,0>[TT'TT'`TT'T'`TT'\sigma]
\place(300,1400)[2]
\place(1050,1050)[3]
\btriangle(1400,700)|m`r`a|/>`>`>/<700,700>[TT'`TT'T'`TT';
T\eta'T'`\hbox{\rm id}`]
\place(1600,1050)[6]
\square|a`l`m`b|<700,700>[TT'T`TT'TT'`T'T`T'TT';
TT'T\eta'`\sigma T`\sigma TT'`T'T\eta']
\square(1400,0)|a`m`r`b|<700,700>[TT'T'`TT'`T'T'`T';
T\mu'`\sigma T' `\sigma`\mu']
\morphism(700,0)|b|/>/<700,0>[T'TT'`T'T'`T'\sigma T']
\place(300,350)[4]
\place(1050,350)[5]
\place(1750,350)[7]
\efig$$
\end{document}
