% This document should be typeset with LaTeX;
% it gives a basic user's information about the diagram macros.
% Those macros are necessary for this typesetting,
% so make sure the "diagram" document is in your TeX file.
% Print the document in the "landscape" position
% or remove the instructions \oddsidemargin168mm and
% evensidemargin29mm from the preamble.
% The size of the output has been choosen so that two pages
% of the document can fit nicely on a A4 page.

%% Lines with two %-signs were commented away by Nico verwer,
%% to make this document a4-sized.
%% To restore this file to its original, search for all lines
%% containing %%.
%% \documentstyle[twoside]{article}
\documentstyle[a4]{article} %% remove this line to restore original.

\input{diagram}

%% \hoffset-23.5mm
%% \voffset-20mm
%% \oddsidemargin168mm
%% \evensidemargin27mm
%% \textheight 454pt
%% \textwidth 283pt
\pagestyle{myheadings}
\markboth{}{}


\newcommand{\bs}{$\backslash$}
\newcommand{\p}{\hspace{14pt}}
\newcommand{\vb}{\verb}
\newcommand{\tab}{\begin{tabular}}
\newcommand{\TAB}{\end{tabular}}
\newcommand{\D}{{\em Diagram}}
\newcommand{\tc}[1]{\par\noindent#1}

\title{User's guide for the {\em Diagram} Macros}
\author{Francis Borceux}
\date{UCL, Louvain-la-Neuve,Belgium.
\thanks{bitnet:FBORCEUX@BUCLLN11}}

\begin{document}


\maketitle

\thispagestyle{empty}

%\LARGE\bf\noindent Contents\vspace{10pt}
%
%\normalsize
%
%
%\tc{\makebox[6mm][r]{1.} What are the {\em Diagram}
%Macros?\dotfill2}
%\tc{\makebox[6mm][r]{2.} Inserting in-text arrows.\dotfill2}
%\tc{\makebox[6mm][r]{3.} Backward in-text arrows.\dotfill3}
%\tc{\makebox[6mm][r]{4.} Naming the in-text arrows.\dotfill4}
%\tc{\makebox[6mm][r]{5.} Emphasizing an arrow.\dotfill5}
%\tc{\makebox[6mm][r]{6.} Primary diagram arrows.\dotfill5}
%\tc{\makebox[6mm][r]{7.} Secondary diagram arrows.\dotfill6}
%\tc{\makebox[6mm][r]{8.} Ternary diagram arrows.\dotfill7}
%\tc{\makebox[6mm][r]{9.} Naming the diagram arrows.\dotfill9}
%\tc{\makebox[6mm][r]{10.} Conceiving a diagram.\dotfill10}
%\tc{\makebox[6mm][r]{11.} Typing a diagram.\dotfill12}
%\tc{\makebox[6mm][r]{12.} The variable length option.\dotfill14}
%\tc{\makebox[6mm][r]{13.} Superposing items in a
%diagram.\dotfill16}
%\tc{\makebox[6mm][r]{14.} Drawing curved arows.\dotfill17}
%\tc{\makebox[6mm][r]{15.} The free slope arrows.\dotfill19}
%\tc{\makebox[6mm][r]{16.} The scaling option.\dotfill21}
%\tc{\makebox[6mm][r]{17.} Final adjustments.\dotfill22}
%\tc{\makebox[6mm][r]{18.} Some special characters.\dotfill24}

\tableofcontents
\pagebreak


\section{What are the {\em Diagram} Macros?}

\p{\em Diagram} is a series of Macros intended to produce
easily rather sophisticated diagrams which can appear when typing
category theory. The range of arrows which can be produced includes
plain morphisms, dotted morphisms, monomorphisms, epimorphisms,
bimorphisms, isomorphisms, equalities, pairs of parallel arrows
and pairs of adjoint arrows. Most arrows can be drawned in the
sixteen basic directions of the compass-card (and this inspires
the terminology). Some curved arrows are also available. All
these arrows can be given a name, on either side of the arrow.
For emphasizing, arrows can be printed in bold-face type.  Except
for some special features, the Macros will take care of choosing
the correct length of each arrow as well  as positioning
correctly the various elements which appear in the diagram. The
final result will be a diagram with rows and columns at a
distance of 80 points (1.1in, 28mm) from each other; this
standard distance can be changed for every individual diagram
just by giving a scaling factor.


{\em Diagram} includes also a list of in-text symbols containing in
particular the same variety of arrows in both the forward and the
backward directions.

The {\em Diagram} Macros are \LaTeX\  Macros which make an
intensive use of the \LaTeX\ picture environment and in
particular of the \vb+\vector+ command. To use them for producing
a document, it suffices to have in your \TeX\  file a copy of the
file {\em diagram} and to call it with the command
\vb+\input{diagram}+, in the preamble of your new document. The
{\em Diagram} macros will give good results with 10pt, 11pt and
12pt styles.The following sections should provide you with full
information on how to use the {\em Diagram} macros for producing
your documents.


\section{Inserting in-text arrows.}

\p An in-text arrow is one which you include in a line of text, like
for example when you write:
\begin{quote}Let $f:A\mono B$ be a monomorphism \ldots \end{quote}
Here are the available in-text arrows and the corresponding
commands. The length of an in-text arrow is 20pt.

\begin{tabular}{lll}
plain arrow&\vb+\ar+&\ar\\
dotted arrow&\vb+\dotar+&\dotar\\
monomorphism&\vb+\mono+&\mono\\
epimorphism&\vb+\epi+&\epi\\
bimorphism&\vb+\bimo+&\bimo\\
isomorphism&\vb+\iso+&\iso\\
pair of parallel arrows&\vb+\biar+&\biar\\
equality&\vb+\eql+&\eql\\
pair of adjoint arrows&\vb+\adjar+&\adjar
\end{tabular}

\vspace{3pt}

When you insert an in-text arrow, the {\em Diagram} Macros will
take care of the spacing at both ends of the arrow. The in-text
arrow commands can be used both in paragraph and in Math mode, but
normally you should use them in Math mode to print the surrounding
characters in Math italic. Compare indeed\\
%\hspace*{-10mm}%
\begin{tabular}{ll}
\vb+Let f:A\epi B be an epimorphism  +
&Let f:A\epi B be an epimorphism \TAB

\noindent with\\
%\hspace*{-10mm}%
\tab{ll}
\vb+Let $f:A\epi B$ be an epimorphism+
&Let $f:A\epi B$ be an epimorphism
\TAB

\section{Backward in-text arrows.}

\p It is a general rule of the {\em Diagram} Macros that to draw an
arrow in some given direction, it suffices to preceed the name of
the arrow by a code for the direction. To draw an in-text arrow in
the backward direction, it suffices to add the prefix \vb+bk+ to
the command for that arrow.

\begin{tabular}{lll}
backward plain arrow&\vb+\bkar+&\bkar\\
backward dotted arrow&\vb+\bkdotar+&\bkdotar\\
backward monomorphism&\vb+\bkmono+&\bkmono\\
backward epimorphism&\vb+\bkepi+&\bkepi\\
backward bimorphism&\vb+\bkbimo+&\bkbimo\\
backward isomorphism&\vb+\bkiso+&\bkiso\\
backward pair of parallel arrows&\vb+\bkbiar+&\bkbiar\\
backward equality&\vb+\bkeql+&\bkeql\\
backward pair of adjoint arrows&\vb+\bkadjar+&\bkadjar
\end{tabular}

\section{Naming the in-text arrows.}

\p In a line of text, it is probably a better idea to type
\mbox{$f:A\bimo B$} than $A\Bimo{f}B$. Nevertheless the \D\ Macros
allow you to give an upper name to the single in-text arrows as well
as an upper-lower name to the double in-text arrows. It is a general
rule of the \D\ Macros that to give an upper name to a single arrow
or an upper-lower name to a double arrow, it suffices \nolinebreak
to

\begin{enumerate}
\item type the first letter of the corresponding command as an
upper-case letter
\item give the name(s) of the arrow(s) as argument(s) of the
command.
\end{enumerate}
Here is a list of the available named in-text arrows:\vspace{5pt}

%\hspace*{-7mm}%
\begin{tabular}{lll}
plain arrow $f$&\vb+\Ar{f}+&\Ar{f}\\
dotted arrow $f$&\vb+\Dotar{f}+&\Dotar{f}\\
monomorphism $f$&\vb+\Mono{f}+&\Mono{f}\\
epimorphism $f$&\vb+\Epi{f}+&\Epi{f}\\
bimorphism $f$&\vb+\Bimo{f}+&\Bimo{f}\\
isomorphism $f$&\vb+\Iso{f}+&\Iso{f}\\
pair of parallel arrows $f, g$&\vb+\Biar{f}{g}+&\Biar{f}{g}\\
pair of adjoint arrows $f, g$&\vb+\Adjar{f}{g}+&\Adjar{f}{g}\\
backward plain arrow $f$&\vb+\Bkar{f}+&\Bkar{f}\\
backward dotted arrow $f$&\vb+\Bkdotar{f}+&\Bkdotar{f}\\
backward monomorphism $f$&\vb+\Bkmono{f}+&\Bkmono{f}\\
backward epimorphism $f$&\vb+\Bkepi{f}+&\Bkepi{f}\\
backward bimorphism $f$&\vb+\Bkbimo{f}+&\Bkbimo{f}\\
backward isomorphism $f$&\vb+\Bkiso{f}+&\Bkiso{f}\\
pair of parallel backward arrows $f,g$
&\vb+\Bkbiar{f}{g}+&\Bkbiar{f}{g}\\
backward pair of adjointarrows  $f, g$
&\vb+\Bkadjar{f}{g}+&\Bkadjar{f}{g} \end{tabular}
\vspace{5pt}

The name of an arrow will always be processed in  Math mode at the
scripstyle size; therefore the text characters will be printed in
Math italic and you should not type any \$ sign to introduce a
mathematical symbol in the name of an arrow.

\section{Emphasizing an arrow.}

\p The dotted arrows are a first type of emphasized arrows; their
construction is rather slow. It will be easier for \LaTeX\ to
print an arrow in bold face style: to realize this, just preceed
the command for the arrow by the command \vb+\B+; thus
\vb+$A\B\Mono{f}B$+ produces $A\B\Mono{f}B$. That ``bolding''
process applies to both the ``in text'' and the ``diagram''
arrows.

\section{Primary diagram arrows.}

\p The {\em diagram arrows} are those arrows specially designed to
fit nicely in a diagram; their variety and their names are the same
as those of in-text arrows: plain arrow (\vb+ar+), dotted arrow
(\vb+dotar+), monomorphism (\vb+mono+), epimorphism (\vb+epi+),
bimorphism (\vb+bimo+), isomorphism (\vb+iso+), pair of parallel
arrows (\vb+biar+), equality (\vb+eql+) and pair of adjoint arrows
(\vb+adjar+). You should never use an in-text arrow in a diagram
nor a diagram arrow in a line of text: the technical
characteristics of those pictures are just incompatible!

While an in-text arrow is always horizontal, the possibility must
exist to give a diagram arrow a rather arbitrary direction. For
that reason the name of a diagram arrow starts {\em always} with
the prefix indicating its direction, even in the case of an
horizontal right pointing arrow. The direction of an arrow is
indicated by a direction of the compass-card, using the
classical abbreviations:

\tab{llll}
north( \vb+n+ )&south( \vb+s+ )&east( \vb+e+ )&west( \vb+w+ )
\TAB

The command for producing a primary arrow is obtained by
typing the abbreviation for its direction followed by the
abbreviation for the type of arrow. For example the command
\vb+\wbimo+ will produce a west pointing bimorphism. Here are
other examples.
\DIAG
{\bullet} \n {} \n {\bullet} \n {} \n {\bullet} \nn
{} \n {} \n {\naR{\mbox{\bs\tt nar}}} \n {} \n {}J\nn
{\bullet} \n {\Wmono{\mbox{\bs\tt wmono}}} \n {\bullet}\n
{\Eepi{\mbox{\bs\tt eepi}}} \n {\bullet} \nn
{} \n {} \n {\Sbiar{}{\mbox{\bs\tt sbiar}}} \n {} \n {} \nn
{\bullet} \n {} \n {\bullet} \n {} \n {\bullet}
\diag

The case of adjoint arrows requires a comment. For east and west
pairs of adjoint arrows, the direction is that of the lower arrow;
for north and south pairs of adjoint arrows, the direction is that
of the left arrow.

The standard length of a primary arrow is 50pt, but the length of
an {\em horizontal} arrow is automatically adjusted when the
adjacent vertices have too long names.

\section{Secondary diagram arrows.}

\p The secondary diagram arrows are those which are oriented in
the secondary directions of the compass-card; here are thus the
possible directions and the corresponding abbreviations:

\tab{ll}
north-east ( \vb+ne+ )&south-east ( \vb+se+ )\\
north-west ( \vb+nw+ )&south-west ( \vb+sw+ )
\TAB

The variety of available arrows is the same as for primary arrows:
plain arrow (\vb+ar+), dotted arrow (\vb+dotar+), monomorphism
(\vb+mono+), epimorphism (\vb+epi+), bimorphism (\vb+bimo+),
isomorphism (\vb+iso+), pair  of parallel arrows (\vb+biar+),
equality (\vb+eql+) and pair of  adjoint arrows (\vb+adjar+).
Just as for primary arrows, a secondary  arrow is obtained by
typing the abbreviation  for its direction followed by the
abbreviation for the type of arrow.  For example the command
\vb+\swbiar+ will produce a pair of sout-west pointing arrows.
Here are some examples of what you can produce as secondary
diagram arrows:


\DIAG
{\bullet} \n {} \n {\bullet} \n {} \n {\bullet} \nn
{} \n {\nwbimO{\mbox{\bs\tt nwbimo}}} \n {}
\n {\Neadjar{}{\mbox{\bs\tt neadjar}}} \n {}J\nn
{\bullet} \n {} \n {\bullet} \n {} \n {\bullet} \nn
{} \n {\Swiso{\mbox{\bs\tt swiso}}} \n {}
\n {\Sedotar{\mbox{\bs\tt sedotar}}} \n {} \nn
{\bullet} \n {} \n {\bullet} \n {} \n {\bullet}
\diag

The case of a pair of adjoint arrows requires again a comment. The
direction is always that of the lower arrow.

The secondary diagram arrows have a standard horizontal extent
equal to 58pt.

\section{Ternary diagram arrows.}

\p The ternary diagram arrows are those which are oriented along
the diagonals of a rectangle of sides 1,2. Taking some liberty with
trigonometry and geography, we shall name them after the ternary
directions of the compass-card. Thus, here are the available
directions and the corresponding abbreviations:
\begin{center}
\tab{ll}
north-north-east ( \vb+nne+ )&east-north-east ( \vb+ene+ )\\
east-south-east ( \vb+ese+ )&south-south-east ( \vb+sse+ )\\
south-south-west ( \vb+ssw+ )&west-south-west ( \vb+wsw+ )\\
west-north-west ( \vb+wnw+ )&north-north-west ( \vb+nnw+ )
\TAB
\end{center}

The only type of ternary arrows provided by the \D\ Macros are the
plain arrows. Again you will obtain the command for a ternary arrow
by preceeding the abbreviation \vb+ar+ with the prefix indicating the
direction of the arrow. Here are thus the eight available ternary
arrows:\\
%\hspace*{-10mm}%
\begin{minipage}{12cm}
\DIAG
{\bullet} \n {} \n {\bullet} \n {} \n {\bullet} \n {} \n
{\bullet} \n {} \n {\bullet} \nn
{} \n {} \n {} \n {} \n {} \n {} \n {} \n {} \n {} \nn
{\bullet} \n {} \n {\bullet} \n {\nnwaR{\mbox{\bs\tt nnwar}}} \n
{\bullet} \n {\nneaR{\mbox{\bs\tt nnear}}} \n {\bullet} \n {} \n
{\bullet} \nn
{} \n {} \n {\wnwaR{\mbox{\bs\tt wnwar}}} \n {} \n {} \n {} \n
{\eneaR{\mbox{\bs\tt enear}}} \n {} \n {} \nn
{\bullet} \n {} \n{\bullet} \n {} \n {\bullet} \n {} \n
{\bullet} \n {} \n {\bullet} \nn
{} \n {} \n {\Wswar{\mbox{\bs\tt wswar}}} \n {} \n {} \n {} \n
{\Esear{\mbox{\bs\tt esear}}} \n {} \n {} \nn
{\bullet} \n {} \n {\bullet} \n {\Sswar{\mbox{\bs\tt sswar}}} \n
{\bullet} \n {\Ssear{\mbox{\bs\tt ssear}}} \n {\bullet} \n {} \n
{\bullet} \nn
{} \n {} \n {} \n {} \n {} \n {} \n {} \n {} \n {} \nn
{\bullet} \n {} \n {\bullet} \n {} \n {\bullet} \n {} \n
{\bullet} \n {} \n {\bullet}
\diagv{23}{0}{0}
\end{minipage}

A ternary diagram arrow has a standard horizontal extent equal to
66pt or 132pt according to the case.

\section{Naming the diagram arrows.}

\p The rules for naming the diagram arrows are analogous to those
for naming the in-text arrows, with the additional possibility of
naming the arrow on either of its sides. It suffice to type the
first or the last letter of the command as an upper-case letter
and give the name of the arrow as an argument. Here is an exhaustive
list of the available possibilities.

\begin{description}
\item[Eql:] An equality cannot be named
\item[Vertical ar, mono, epi, bimo:] A first upper-case letter
produces a left name and a last upper-case letter produces a
right name; thus type \vb+\Smono{f}+ to draw a south monomorphism
with left name $f$ and \vb+\nepI{g}+ to draw a north epimorphism
with right name $g$.
\item[Non-vertical ar, mono, epi, bimo:] A first upper-case letter
produces an upper name and a last upper-case letter produces a
lower name; thus type \vb+\War{f}+ to draw a west arrow with upper
name $f$ and \vb+\nebimO{g}+ to draw a north-east bimorphism with
lower name $g$.
\item[Horizontal iso:] A first upper-case letter
produces an upper name and a last upper-case letter produces a
lower name; thus type \vb+\Wiso{f}+ to draw a west isomorphism with
upper name $f$ and \vb+\eisO{g}+ to draw an east isomorphism
with lower name $g$.
\item[Non-horizontal iso:] Type a first upper-case letter to name
it; the name will appear on one side of the arrow and the
``isomorphism symbol'' on the other side; thus \vb+\Nwiso{f}+ draws
a north-west isomorphism with name $f$.
\item[Vertical biar, adjar:] Type a first upper-case letter to name
them and give successively the name of the left arrow and that of
the right arrow; thus \vb+\Sbiar{f}{g}+ draws a pair of south
arrows with left name $f$ and right name $g$.
\item[Non-vertical biar, adjar:] Type a first upper-case letter to
name them and give successively the name of the upper arrow and
that of the lower arrow; thus \vb+\Seadjar{f}{g}+ will produce a
south-east pair of adjoint arrows with upper name $f$ and lower
name $g$.
\end{description}

The name of an arrow will always be processed in  Math mode at the
textstyle size; therefore the text characters will be printed in
Math italic and you should not type any \$ sign to introduce a
mathematical symbol in the name of an arrow. The name of an arrow
will automatically be positioned in order not to bump into the
corresponding arrow.

\section{Conceiving a diagram.}

\p We are now arriving at the central section of this user's guide:
the one which describes the basic principle for realizing a
diagram. This will be better explained on an example. Let us
therefore suppose you want to construct the following diagram.
\DIAG
{X} \n {} \n {} \n {} \n {} \nn
{} \n {\Sedotar{z}} \n {\Esear{y}} \n {} \n {} \nn
{} \n {\sseaR{x}} \n {P} \n {\Eepi{k}} \n {B} \nn
{} \n {} \n {\Smono{h}} \n {} \n {\smonO{g}} \nn
{} \n {} \n {A} \n {\eepI{f}} \n {C}
\diag

This diagram contains several items: five vertices $A,B,C,P,X$,
four primary arrows, one secondary arrow and two ternary arrows;
one of the arrows is emphasized. All those items are very different
in nature, size, orientation, position \ldots The first basic rule
for conceiving a diagram is to ignore completely all those
differences and just treat equally all those items; this allows a
maximum of flexibility and simplicity. To realize this, the \D\
Macros consider a formal pattern of points, at a 40pt distance from
each other, both horizontally and vertically. Then each item of the
diagram is {\em centered} at one of the points of the pattern, using
the {\em picture} environment.

Let us for example visualize the pattern of points on which the
previous diagram has been constructed.
\newcommand{\pat}
{\begin{picture}(0,0)
\multiput(-8000,-8000)(4000,0){5}{\circle*{300}}
\multiput(-8000,-4000)(4000,0){5}{\circle*{300}}
\multiput(-8000,0)(4000,0){5}{\circle*{300}}
\multiput(-8000,4000)(4000,0){5}{\circle*{300}}
\multiput(-8000,8000)(4000,0){5}{\circle*{300}}
\end{picture}}

\DIAG
{X} \n {} \n {} \n {} \n {} \nn
{} \n {\Sedotar{z}} \n {\Esear{y}} \n {} \n {} \nn
{} \n {\sseaR{x}} \n {\cross{P}{\pat}} \n {\Eepi{k}} \n {B} \nn
{} \n {} \n {\Smono{h}} \n {} \n {\smonO{g}} \nn
{} \n {} \n {A} \n {\eepI{f}} \n {C}
\diag

The complete pattern needs not be a square nor even a rectangle. It
is just compulsory to start all the lines from a same (left) column
and leave no hole at all in any line; but lines need not be of equal
length. To fill in the holes which could appear inside a line, it
suffices to attach empty items at the corresponding points of the
pattern. Here is for example the set of items corresponding to the
previous diagram.
\vspace{10pt}

\begin{center}
\begin{picture}(200,200)
\thicklines
\put(0,0){\line(1,0){200}}
\put(0,40){\line(1,0){200}}
\put(0,80){\line(1,0){200}}
\put(0,120){\line(1,0){200}}
\put(0,160){\line(1,0){120}}
\put(0,200){\line(1,0){40}}
\put(0,0){\line(0,1){200}}
\put(40,0){\line(0,1){200}}
\put(80,0){\line(0,1){160}}
\put(120,0){\line(0,1){160}}
\put(160,0){\line(0,1){120}}
\put(200,0){\line(0,1){120}}
\put(20,180){\makebox(0,0){$X$}}
\put(60,140){\makebox(0,0)
{\normalsize\bs\tt\scriptsize Sedotar\{z\}}}
\put(60,100){\makebox(0,0){\bs\tt\scriptsize
sseaR\{x\}}} \put(100,140){\makebox(0,0){\bs\tt\scriptsize
Esear\{y\}}} \put(100,100){\makebox(0,0){$P$}}
\put(100,60){\makebox(0,0){\bs\tt\scriptsize Smono\{h\}}}
\put(100,20){\makebox(0,0){$A$}}
\put(140,100){\makebox(0,0){\bs\tt\scriptsize Eepi\{k\}}}
\put(140,20){\makebox(0,0){\bs\tt\scriptsize eepI\{f\}}}
\put(180,100){\makebox(0,0){$B$}}
\put(180,60){\makebox(0,0){\bs\tt\scriptsize smonO\{g\}}}
\put(180,20){\makebox(0,0){$C$}}
\end{picture}
\end{center}\vspace{10pt}

\section{Typing a diagram.}

\p Let us assume you have determined the nature and the position of
each item of your diagram. Here is what you should type in order to
give that information to the \D\ Macros.

\begin{enumerate}
\item Type the command \vb+\DIAG+ to start the typing of the
diagram;
this command will in particular start a {\em center} environment;
it can be given both in paragraph and in math mode.
\item Type between curly brackets the description of {\em every}
item; this description will automatically be processed in Math mode.
The empty items will thus appear as \{\} in your input.
\item {\em Separate} two consecutive items in a same row by the
``next item command'', which is \vb+\n+. The command \vb+\n+ may
not appear before the first item of a row nor after the last item of
a row.
\item {\em Separate} two consecutive rows of items by the ``next
row command'' which is \vb+\nn+. The command \vb+\nn+ may not appear
before the first row of items nor after the last row of items.
\item Type the command \vb+\diag+ to indicate the end of the
diagram typing.
\end{enumerate}

When you type a diagram using the procedure just indicated, notice
that between the two commands \vb+\DIAG+ and \vb+\diag+
\begin{itemize} \item You can put as much space as you want in a
line to make your input file easier to read;
\item You should never use a \$ sign to type a mathematical symbol,
except if you did include that symbol in a box.
\end{itemize}

With all that in mind, the diagram of the
previous section can be typed as follows
\begin{verbatim}
\DIAG
{X}                                                     \nn
{} \n{\Sedotar{z}}\n{\Esear{y}}                         \nn
{} \n{\sseaR{x}}  \n{P}        \n{\Eepi{k}}\n{B}        \nn
{} \n{}           \n{\Smono{h}}\n{}        \n{\smonO{g}}\nn
{} \n{}           \n{A}        \n{\eepI{f}}\n {C}
\diag
\end{verbatim}
or equivalently as
\begin{verbatim}
\DIAG{X}\n{}\n{}\n{}\n{}\nn{}\n{\Sedotar{z}}
\n{\Esear{y}}\n{}\n{}\nn{}\n{\sseaR{x}}\n{P}
\n{\Eepi{k}}\n{B}\nn{}\n{}\n{\Smono{h}}\n{}
\n{\smonO{g}}\nn{}\n{}\n{A}\n{\eepI{f}}\n{C}\diag
\end{verbatim}

The \D\ Macros will automatically center the diagram horizontally
on the page and will take care of the spacing with the preceeding
and the following text. When a diagram is rather big, you should
make it a figure or a table (see \LaTeX book, 3.5.1 page 60) to
improve the quality of the page-making. If you want to align
horizontally various small diagrams, consider these just as a
unique wide diagram where some columns are completely empty.

\section {The variable length option.}

\p Suppose you want to produce the following diagram:
\DIAG
{A} \n {} \n {\Earv{f}{130}} \n {} \n {C} \nn
{} \n {\seepI{p}} \n {} \n {\nemonO{i}} \n {} \nn
{} \n {} \n {B} \n {} \n {}
\diag
Following the instructions of the previous sections you will
type:
\begin{verbatim}
\DIAG
{A}\n{}         \n{\Ear{f}}\n{}          \n{C}\nn
{} \n{\seepI{p}}\n{}       \n{\nemonO{i}}\nn
{} \n{}         \n{B}      \nn
\diag
\end{verbatim}
and you will get
\DIAG
{A} \n {}          \n {\Ear{f}} \n {}           \n {C} \nn
{}  \n {\seepI{p}} \n {}        \n {\nemonO{i}} \n {}  \nn
{}  \n {}          \n {B}       \n {}           \n {}
\diag
which is not exactly what you wanted!

The \D\ Macros assume that a primary arrow connects two vertices
attached at the two horizontally adjacent points of the pattern, and
a corresponding assumption is made for the secondary and the ternary
arrows. The east arrow of the previous diagram does not satisfy
that assumption: it connects vertices situated at a four intervals
distance. The \D\ Macros provide you with a {\em variable length
option} which allows you to modify the length of an arrow in order
to take care of such particularities. The ``variable length
option'' is a special feature, which means that the \D\ Macros need
your help to handle the problem. In fact, what you have to do is to
decide the new length of the arrow.

Not all arrows have been provided with a ``variable length
option''; here are the possibilities:
\begin{itemize}
\item All the primary arrows, named or unamed, admit a variable
length option.
\item The four secondary plain arrows, named or unamed, admit a
variable length option; the other secondary arrows are not provided
with the variable length option.
\item The ternary arrows do not have the variable length option.
\end{itemize}

To take advantage of the variable length option, it suffices to
follow the name of the corresponding command with the lower-case
letter \vb+v+ and give to that command an additional last argument
which will be
\begin{itemize}
\item The new length of the arrow in the case of a primary arrow
\item The new horizontal extent of the arrow in the case of a
secondary arrow;
\end{itemize}
those two lengthes must be expressed in points. The new arrow will
still be centered with respect to the corresponding point of the
pattern. For example typing \vb+\Earv{f}{130}+ for the east
arrow of the previous diagram will produce the desired result as in
the first diagram. Typing \vb+\smonOv{g}{30}+ will produce a south
monomorphism with right name $g$ and length 30 points, typing
\vb+\Wadjarv{f}{g}{100}+ will produce a west pair of adjoint arrows
with names $f,g$ and length 100 points and typing \vb+\near{82.5}+
will produce an unamed north-east arrow with horizontal extent 82.5
points.

The standard length of a primary arrow is 50pt; since each
interval of the pattern has length 40pt, the new length of a primary
arrow will be  $$50+(n\times 40)$$
where $n$ is the number of intervals the arrow crosses. In the
same way the horizontal extent of a secondary arrow is 58pt,
so that the new horizontal extent of a secondary arrow will be
$$58+(n\times 40)$$
where n is the number of horizontal intervals the arrow crosses.

\section{Superposing items in a diagram.}

\p Sometimes you will like to superpose two items at the same point
of the pattern underlying your diagram, like in the following
example:
\DIAG
{A} \n {\ear} \n {B} \nn
{\nar} \n {\cross{\near}{\sear}} \n {\sar} \nn
{C} \n {\ear} \n {D}
\diag
The command for superposing two items is \vb+\cross{1}{2}+ where 1
and 2 stand for the two items; the two arguments 1 and 2 are
automatically processed in Math mode. The previous diagram can thus
be typed as
%% \pagebreak %% Removed for a4 sized document!
\begin{verbatim}
\DIAG
{A}    \n {\ear}                 \n {B}    \nn
{\nar} \n {\cross{\near}{\sear}} \n {\sar} \nn
{C}    \n {\ear}                 \n {D}
\diag
\end{verbatim}

When superposing two arrows, the \vb+\cross+ command can have the
undesired effect that one of the arrows will bump into the name of
the other arrow. A special command has been designed to correct
such a defect and is explained in section~17. For that reason, the
``cross'' option could be considered as a special feature of the
\D\ Macros: one which requires your help.

\section{Drawing curved arrows.}

\p Drawing curved arrows is another special feature of the
\D\ Macros, thus a process where the \D\ Macros need you help. In
fact you will have to decide the length of the curved arrow and
possibly you will have to adjust the spacing around the diagram (an
easy procedure for that will be described in section~17).

Just plain curved arrows in the primary directions are provided by
the \D\ Macros. The first letter of the command indicates where,
with respect to the diagram, the arrow has to stand (this
determines the concavity of the arrow); the second letter indicates
the overall direction of the arrow; then follows the abbreviation
\vb+curve+ for ``curved arrow''. As usual, the two first
indications are given using the compass-card terminology:
\vb+n,s,e,w+. Typing the first letter as an upper-case letter will
produce a named arrow, the name being given as a first argument of
the command. It is compulsory to give the length of the arrow as a
last argument. By length of the arrow we mean clearly its
horizontal or vertical extent (according to the case), expressed in
points. For example \vb+\Necurve{f}{160}+ will produce a curved
arrow with name $f$ and length 160 points, to be positioned at the
north side of a diagram and with overall east direction.

For more clarity, here are the eight unamed curved arrows (of
length 80 points) and the corresponding commands. The bullets
indicate the position of the formal centers (?!) of these arrows;
each bullet corresponds thus to the point which will coincide with
the corresponding point of the pattern.
\vspace{15pt}
\DIAG
{} \n {\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}
\end{picture}}{\Necurve{\mbox{\bs\tt necurve}}{80}}} \n {} \n {}
\n
{\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}\end{picture}}
{\Nwcurve{\mbox{\bs\tt nwcurve}}{80}}} \n {} \diagv{10}{0}{-5}
\DIAG
{} \n {\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}
\end{picture}}{\Securve{\mbox{\bs\tt securve}}{80}}}  \n {} \n {}
\n
{\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}\end{picture}}
{\Swcurve{\mbox{\bs\tt swcurve}}{80}}}\n {} \nn {} \n {} \n {} \n {}
\n {} \n {} \nn
{\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}\end{picture}}
{\Wscurve{\mbox{\bs\tt wscurve}}{80}}} \n {} \n
{\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}\end{picture}}
{\Wncurve{\mbox{\bs\tt wncurve}}{80}}} \n
{\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}\end{picture}}
{\Escurve{\mbox{\bs\tt escurve}}{80}}} \n {} \n
{\cross{\begin{picture}(0,0)\put(0,0){\circle*{300}}\end{picture}}
{\Encurve{\mbox{\bs\tt encurve}}{80}}} \diagv{0}{0}{40}

Most often you will have to include a curved arrow at a point of
the pattern which is already occupied by another item, a vertex or an
arrow; just use the \vb+\cross+ command of the previous section to
superpose the two items. The length of a curved arrow will generally
be a multiple of 80 points, since this is the normal distance
between two vertices, in a primary direction. Here is an example of
a diagram containing curved arrows:
\DIAG
{A} \n {\Ear{a}} \n {\cross{B}{\Necurve{l}{160}}} \n {\Ear{b}}
\n {C} \nn
{\cross{\Wncurve{e}{80}}{\Sbiar{f}{g}}} \n {}
\n {\saR{h}} \n {} \n {\saR{k}} \nn
{D} \n {\eaR{c}} \n {E} \n {\eaR{d}} \n {F}
\diagv{25}{0}{0}
It should thus be typed as follows:
\begin{verbatim}
\DIAG
{A}\n{\Ear{a}} \n{\cross{B}{\Necurve{l}{160}}}
                          \n{\Ear{b}}\n{C}      \nn
{\cross{\Wncurve{e}{80}}{\Sbiar{f}{g}}}
   \n{}        \n{\saR{h}}\n{}       \n{\saR{k}}\nn
{D}\n {\eaR{c}}\n{E}      \n{\eaR{d}}\n{F}
\diagv{25}{13}{0}
\end{verbatim}

\section{The free slope arrows.}

\p When you have to produce a given diagram of vertices and arrows,
you must clearly choose adequately the position of each vertex so
that all the arrows will be in one of the sixteen directions
considered by the \D\ Macros. Anybody who has read this user's guide
will easily produce an example of a diagram where this requirement
cannot be fulfilled. Nevertheless such a situation is rather
unusual since, for example, the most popular book on category
theory {\em (Saunders MAC LANE -- Categories for the working
mathematician -- Springer,1971)} \ldots does not contain any such
diagram! [Well, I have been lucky: Saunders did not draw the
connecting morphism in the snake lemma!]

The slope of an arrow is a pair $(n,m)$ of integers: when you
move $n$ points left, you move $m$ points up; as usual, a
negative value of $n$ or $m$ indicates a movement in the
opposite direction. For example, here are the slopes of the various
diagram arrows:
\begin{itemize}
\item The primary arrows have slope $(\pm1,0)$ [horizontal arrows]
or $(0,\pm1)$ [vertical arrows];
\item The secondary arrows have slope $(\pm1,\pm1)$;
\item The ternary arrows have slope $(\pm1,\pm2)$ or $(\pm2,\pm1)$
according to the case.
\end{itemize}
In fact, \LaTeX allows you to draw arrows in thirty two other
directions, using the picture environment and the commands
\vb+\put+ and \vb+\vector+; the corresponding available slopes are
$(\pm1,\pm3)$, $(\pm3,\pm1)$, $(\pm1,\pm4)$, $(\pm4,\pm1)$,
$(\pm2,\pm3)$, $(\pm3,\pm2)$, $(\pm3,\pm4)$, $(\pm4,\pm3)$.
The length of an arrow is always specified by giving the horizontal
extent of the arrow, except in the case of vertical arrows where
the actual length is given. So you can just design any arrow or set
of arrows using the picture environment and choose the corresponding
picture as an item of your diagram; the center of your picture will
be positioned automatically at the corresponding point of the
pattern. This is exactly what the \D\ Macros are doing any time you
ask them to draw an arrow.

You can avoid some typing (but just that!), by using the ``free slope
arrow Macro'' to produce directly a diagram arrow, like for
primary, secondary and ternary arrows. It has the following form
where, as a matter of convention, the origin of the coordinates is
the point of the pattern at which you want to include the free slope
arrow:

\vb+\Freear{n}{a}{b}{x}{y}{u}{v}{l}+\\
where
\begin{itemize}
\item \vb+n+ is the name of the arrow;
\item \vb+(a,b)+ are the coordinates (in points) of the place where
you want the lower left corner of that name to be positioned;
\item \vb+(x,y)+ are the coordinates of the origin of the arrow;
\item \vb+(u,v)+ is the slope of the arrow (it must be one of the
slopes just indicated);
\item \vb+l+ is the horizontal extent (in points) of the arrow, or
its length in the case of a vertical arrow.
\end{itemize}
If you do not want to name the arrow, just type, following the
usual \D\ Macros convention:

\vb+\freear{x}{y}{u}{v}{l}+\\
Clearly, the ``free slope arrow'' option is not a \D\ Macros
feature: it is just plain \LaTeX\ job.


\section{The scaling option.}

\p The ``variable length'' option has allowed us to design properly
the diagram of \S 12. But you can possibly not be satisfied with
the final product, because the resulting diagram is unusually big
for the few arrows it does contain. This is easily corrected!

Replacing the initial command \vb+\DIAG+ by the corresponding
``variable scale'' command \vb+\DIAGV{n}+ will scale the original
pattern of points by n\% and adjust correspondingly the length of
every arrow in the diagram. For example typing
\begin{verbatim}
\DIAGV{50}
{A}\n{}         \n{\Earv{f}{130}}\n{}          \n{C}\nn
{} \n{\seepI{p}}\n{}             \n{\nemonO{i}}\nn
{} \n{}         \n{B}
\diag
\end{verbatim}
will produce the following result
\DIAGV{50}
{A} \n {}          \n {\Earv{f}{130}} \n {}           \n {C} \nn
{}  \n {\seepI{p}} \n {}              \n {\nemonO{i}} \nn
{}  \n {}          \n {B}
\diag

Since text characters (and various other things) are unaffected by
the scaling process, you should avoid reducing exagerately a
diagram. In most cases, a reduction up to 50\% gives excellent
results. On the other hand, an enlargement can be helpful when
handling vertices with very long names.

This ``variable scale'' option is particularly useful when
designing ``three dimensional'' diagrams, which require very often a
rather dense pattern of reference points and many ``long'' arrows
produced via the ``variable length'' option. For example to design
the following cube

\DIAGV{50}
{} \n{} \n{B} \n{} \n{\Earv{b}{130}} \n{} \n{D} \nn
{} \n{\Near{a}} \n{} \n{} \n{} \n{\Near{d}} \n{} \nn
{A} \n{} \n{\cross{\Earv{\movename{c}{10}{0}}{130}}
  {\Sarv{\movename{f}{0}{-8}}{130}}}
  \n{} \n{C} \n{} \n{\saRv{h}{130}} \nn
{} \nn
{\Sarv{e}{130}} \n{} \n{F} \n{}
  \n{\cross{\eaRv{\movename{j}{-10}{0}}{130}}
  {\saRv{\movename{g}{0}{8}}{130}}}
  \n{} \n{H} \nn
{} \n{\Near{i}} \n{} \n{} \n{} \n{\neaR{l}} \nn
{E} \n{} \n{\eaRv{k}{130}} \n{} \n{G}
\diag
it suffices to type
\begin{verbatim}
\DIAGV{50}
{} \n{} \n{B} \n{} \n{\Earv{b}{130}} \n{} \n{D} \nn
{} \n{\Near{a}} \n{} \n{} \n{} \n{\Near{d}} \n{} \nn
{A} \n{} \n{\cross{\Earv{\movename{c}{10}{0}}{130}}
  {\Sarv{\movename{f}{0}{-13}}{130}}}
  \n{} \n{C} \n{} \n{\saRv{h}{130}} \nn
{} \nn
{\Sarv{e}{130}} \n{} \n{F} \n{}
  \n{\cross{\eaRv{\movename{j}{-10}{0}}{130}}
  {\saRv{\movename{g}{0}{13}}{130}}}
  \n{} \n{H} \nn
{} \n{\Near{i}} \n{} \n{} \n{} \n{\neaR{l}} \nn
{E} \n{} \n{\eaRv{k}{130}} \n{} \n{G}
\diag
\end{verbatim}
where the \vb+\movename+ command is explained in the next section.

\section{Final adjusments.}

\p The \D\ Macros are intended to provide you with a powerful tool
for designing diagrams, so in normal circumstances, no adjusment at
all should be necessary. But in some unusual cases, for example
when you use the special features of the \D\ Macros, you can want to
interact for correcting some imperfections. Some Macros have been
designed to help you realizing this.

If the vertices of a same row have names of different heights,
those names will no longer stand at the same altitude since they
are centered at the corresponding points of the pattern. There is  a
``normalizing'' command \vb+\N+ which you can apply to the ``high
vertices'' in order to correct this defect: instead of typing
\vb+{vertex}+ type \vb+{\N{vertex}}+, where \vb+vertex+ stands here
for the name of the vertex.

You can want to move the name of an arrow, especially when you have
used the \vb+\cross+ command to superpose two named arrows. If $f$
is the name of the arrow, instead of \vb+{f}+ you just type
\vb+{\movename{f}{n}{m}}+ where n and m are integers (positive or
negative); the name of the arrow will be moved \vb+n+ pt right
and \vb+m+ pt up. In the same way the
commands \vb+\movearrow{\Ear{f}}{n}{m}+ and
\vb+\moveverterx{A}{n}{m}+ will
move respectively the east arrow $f$ and the vertex $A$, \vb+n+
pt right and \vb+m+ pt up.

Because the curved arrows are very ``excentric'' with respect to
their formal center, they will cause problems of spacing when drawn
along an outer edge of a diagram. Drawing a curved arrow along the
upper or the lower edge of a diagram will generally cause the
diagram to overlap the surrounding text; drawing a curved arrow
along just one vertical side of a diagram will cause bad horizontal
centering. Those defects can be corrected by using the ``variable
spacing'' option of the diagram commands. Just replace the final
command \vb+\diag+ by the corresponding ``variable spacing''
command \vb+\diagv{t}{l}{b}+ where
\begin{itemize}
\item \vb+t+ is the vertical space, expressed in points, to be
added at the top of the diagram;
\item \vb+l+ is the horizontal space, expressed in points, to be
added left of the diagram;
\item \vb+b+ is the vertical space, expressed in points, to be
added at the bottom of the diagram.
\end{itemize}
This command will not work properly if your diagram is wider than
the textwidth; in that case, include the diagram in a mini-page
environment (see \LaTeX book, page 98) wide enough to contain it and
position this mini-page in your document using, for example, the
commands  \vb+\hspace*+ and \vb+\vspace*+.

Finally, some unexpected troubles can occur if you
introduce in a diagram items which have not been designed in a
way which is compatible with the internal structure of the \D\
Macros. You will most often get rid of the problem by including the
new item in a box of formal dimensions (0,0).

\section{Some special characters.}

\p This last section contains some {\em text} symbols which you can
want to use in connection with the \D\ Macros.

The ``commutative diagram'' symbol \com\ can be produced by giving
the command \vb+\com+ and the ``adjoint'' symbol \adj\ is obtained
via the command \vb+\adj+.

Finally here are some commands for designing natural
transformations, with or without name.\vspace{10pt}

\begin{tabular}{ll}
{\bs\tt nat} & \nat \\ & \\
{\bs\tt Nat\{F\}\{$\alpha$\}\{G\}} & \Nat{F}{\alpha}{G} \\ & \\
{\bs\tt binat} & \binat \\ & \\
{\bs\tt Binat\{F\}\{$\alpha$\}\{G\}\{$\beta$\}\{H\}} &
\Binat{F}{\alpha}{G}{\beta}{H}
\end{tabular}

\vspace{10pt}

In the case of named natural transformations, the names of the
functors and the natural transformations are processed in Math
mode; thus do not include any \$ sign for putting a mathematical
symbol in those names. Here is how those symbols will be positioned
in a line of text:\\
$$A\nat B\binat C$$


\end{document}
