doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 422 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/barr/diagdoc.tex b/Master/texmf-dist/doc/latex/barr/diagdoc.tex
new file mode 100644
index 00000000000..5dd69eb2c58
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/barr/diagdoc.tex
@@ -0,0 +1,422 @@
+\documentstyle[12pt]{article}
+\input diagram
+\textheight=9in \topmargin=0pt\headheight=0pt\headsep=0pt
+\textwidth=6.5in \oddsidemargin=0pt
+\begin{document}
+{\catcode`\ =13\global\let =\ \catcode`\^^M=13
+\gdef^^M{\par\noindent}}
+\def\verbatim{\tt
+\catcode`\^^M=13
+\catcode`\ =13
+\catcode`\\=12
+\catcode`\{=12
+\catcode`\}=12
+\catcode`\_=12
+\catcode`\^=12
+\catcode`\&=12
+\catcode`\~=12
+\catcode`\#=12
+\catcode`\%=12
+\catcode`\$=12
+\catcode`|=0
+}
+ 
+All commercial rights reserved.  May be freely distributed
+and used with the following exceptions:\\
+1. No commercial use without explicit permission.\\
+2. It may not be distributed without this notice.
+ 
+\def\\{{\tt \char 92}}
+ 
+\section*{The diagram macros}
+The file diagram includes a number of macros for drawing commutative
+diagrams in special shapes as well as more flexible macros to paste
+together more complicated diagrams.
+ 
+In general, there are two kinds of macros.  The first kind has the
+following form
+{\tt \\shape\-name[shape\_\-parameters]} and is intended to be used in
+the following way:
+{\verbatim
+$$
+\shapename[shape_parameters]
+$$
+|egroup
+ 
+This will create a shape with the given parameters.  It operates by
+building its own picture environment.
+ 
+The second kind of procedure must be used inside a picture environment
+and allows the user to put a diagram of a given size and shape at a
+given place.  The usual way in which this is used is:
+ 
+{\verbatim
+$$
+\bfig
+\putshape1<optional parameters>(x1,y1)[shape_parameters1]
+|dots
+\putshape(xn,yn)<optional parameters>[shape_parametersn]
+\efig
+$$
+|egroup
+ 
+Here is an example of the first kind of macro.  I will have to explain a
+few details before giving examples of the second.  The code
+{\verbatim
+$$
+\square[A`B`C`D;f`g`h`k]
+$$
+|egroup
+produces the diagram
+$$
+\square[A`B`C`D;f`g`h`k]
+$$
+and the code
+{\verbatim
+$$
+\Atriangle[A`B`C;f`g`h]
+$$
+|egroup
+produces the diagram
+$$
+\Atriangle[A`B`C;f`g`h]
+$$
+The reason for the shape name will be explained later.
+ 
+If an arrow label extends especially high or low, the space
+automatically expands to match.  For example,
+{\verbatim
+$$
+\square[A`B`C`D;\sum_{i=1}^{\infty}`g`h`\Psi^A_k]
+$$
+|egroup
+will get the diagram
+$$
+\square[A`B`C`D;\sum_{i=1}^{\infty}`g`h`\Psi^A_k]
+$$
+and so on.
+ 
+Before going on, I will explain about the parameters.  Any shape will
+have one or two parameters for height and/or length as well as one
+parameter for each arrow in the diagram.  These are in addition to the
+parameters used in the actual procedures.  For example, the procedure
+{\verbatim
+$$
+\square<-1`0`2`-3;1000`700>[A`B`C`D;f`g`h`k]
+$$
+|egroup
+gives the square:
+$$
+\square<-1`0`2`-3;1000`700>[A`B`C`D;f`g`h`k]
+$$
+The meaning is as follows.  The first four parameters refer to four
+arrows in linguistic order (top, left, right, bottom).  A negative
+number gives a backward arrow, while a zero causes it to be omitted.  A
+parameter with an absolute value of 1 is ordinary, while 2 gives an
+arrow with a tail (monomorphism) and 3 a double headed arrow
+(epimorphism).  The last two parameters determine the width and height,
+respectively, in units of 0.01 em (an em is the width of an M, the
+widest letter in a font).  It should be noted that it is not
+possible to give only some of the optional parameters; either all
+must be given or none is.
+ 
+Here are the shapes.  We have already seen the shape {\tt \\square}.
+There are eight different triangles, all isoceles right triangles in
+different orientations.  The names all have the form {\tt
+\\xtriangle}, where x is the letter that most closely resembles the
+actual shape of the triangle.
+ 
+Here are the names, followed by a sample of each one:
+\begin{list}{}{}
+\item{\tt \\btriangle}\samepage
+$$
+\btriangle[A`B`C;f`g`h]
+$$
+\pagebreak[0]
+\item{\tt \\dtriangle}\samepage
+$$
+\dtriangle[A`B`C;f`g`h]
+$$
+\pagebreak[0]
+\item{\tt \\ptriangle}\samepage
+$$
+\ptriangle[A`B`C;f`g`h]
+$$
+\pagebreak[0]
+\item{\tt \\qtriangle}\samepage
+$$
+\qtriangle[A`B`C;f`g`h]
+$$
+\pagebreak[0]
+\item{\tt \\Atriangle}\samepage
+$$
+\Atriangle[A`B`C;f`g`h]
+$$
+\pagebreak[0]
+\item{\tt \\Vtriangle}\samepage
+$$
+\Vtriangle[A`B`C;f`g`h]
+$$
+\pagebreak[0]
+\item{\tt \\Ctriangle}\samepage
+$$
+\Ctriangle[A`B`C;f`g`h]
+$$
+\pagebreak[0]
+\item{\tt \\Dtriangle}\samepage
+$$
+\Dtriangle[A`B`C;f`g`h]
+$$
+\end{list}
+ 
+In addition, there are two special diagrams that come up often enough to
+be worth having a special macros for.
+\begin{list}{}{}
+\item{\tt \\Atrianglepair}\samepage
+$$
+\Atrianglepair[A`B`C`D;f`g`h`k`l]
+$$
+\item{\tt \\Vtrianglepair}\samepage
+$$
+\Vtrianglepair[A`B`C`D;f`g`h`k`l]
+$$
+\end{list}
+Finally, there is one special shape that is probably not used by very
+many mathematicians.  Still I have it and the user might as well share
+it.
+ 
+{\verbatim
+\recurse[A`B`R`C;s`f_0`f`t_0`t]
+|egroup
+$$
+\recurse[A`B`R`C;s`f_0`f`t_0`t]
+$$
+ 
+Notice what happens if the first parameter is empty:
+{\verbatim
+\recurse[`B`R`C;s`f_0`f`t_0`t]
+|egroup
+$$
+\recurse[`B`R`C;s`f_0`f`t_0`t]
+$$
+ 
+This takes care of the simple procedures.  The remaining procedures are
+there as building blocks for more complicated diagrams.
+ 
+These take the form
+\vskip0pt\noindent
+{\tt \\putshape(xpos,ypos)[shape\_parameters]}
+\vskip0pt\noindent
+where
+shape is one of the 11 shapes (excluding {\tt \\recurse}) described
+above
+and the parms are as described there.  The parameters {\tt  xpos} and
+{\tt  ypos} are the offsets from the lower left corner of the picture
+measured in umits of .01 em in the usual \LaTeX\ fashion.
+ 
+There is one
+more shape which is simply an arrow with an attached label.  This is
+called {\tt \\putmorphism} and it is used with the syntax
+\vskip0pt\noindent
+{\tt
+\\putmorphism(xpos,ypos)(run,rise)[node1`node2`label]\{dist\}\{type\}\{loc\}}
+\vskip0pt\noindent
+Here the parameters {\tt  xpos} and
+{\tt  ypos} are as above.  The slope is {\tt rise/run} where {\tt rise}
+and {\tt run} are two numbers that give the slope in accordance with the
+\LaTeX\ rules.  That is rise and run must have no common divisor and
+must not exceed 4 in absolute value.  In addition, these procedures are
+defined so that rise must not be positive and if it is zero, then run
+must be positive.  In other words, all arrows must go in the linguistic
+direction, downwards or to the right.  Arrows can be made to go in the
+reverse direction as explained below.
+ 
+The next three parameters are the node that appears first (in linguistic
+order), the one that appears second and the arrow label.  The next
+paramater is the distance in the sense of \LaTeX\ between the centers of
+the nodes.  This means it is the horizontal component of the distance,
+unless that is negative, in which case it is the vertical distance.  The
+second parameter is the code for the arrowtype, an integer between -3
+and 3 with the same meaning as explained above.  Using negative values
+of this parameter allows one to draw an arrow that goes upwards or left.
+Note, however, that node1 is always the node that is above or to the
+left of node2.  The last parameter should have the value a,b,l,r or m.
+The values a and b are used only for horizontal arrows and direct the
+arrow label to be placed above or below the arrow.  The values l and r
+are used for all other arrows and direct the label to be left or right
+of the arrow.  Finally, a vertical arrow only can be given the parameter
+m, in which case the arrow will be gapped and the label placed in the
+middle of the gap.
+ 
+In general, the simple macros are designed to be used as indicated
+either in the display
+environment or in one of the others, usually
+{\verbatim
+\begin{equation}\begin{array}{c}
+|dots
+\end{array}\end{equation}|egroup
+ 
+The \\putshape macros must be used inside a picture environment that is
+normally placed inside a display or similar environment.  The
+reference point for the positioning parameters is determined as the
+lower left corner of the smallest rectangle with sides parallel to the
+coordinate axes that includes the center points of all nodes on its
+border.  This rectangle will be degenerate in the case of a horizontal
+or vertical morphism.  The reference point may either be on or outside
+the actual figure.  For example, in the case of the btriangle, it is the
+center of the lower left node, while for a qtriangle it is outside the
+triangle itself being the fourth corner of the enclosing square.
+ 
+The macros are made so that they fit together well.  That is why all
+distances are from node centers to node centers.  If a vertex is part of
+two shapes, it is probably best not to repeat it, since it is
+conceivable that round-off errors will cause its two appearances to be
+slightly offset.  It can either be omitted or, since the width is used
+to determine the amount to shorten horizontal arrows, replaced by {\tt
+\\phantom} versions.  Both methods are illustrated in the example given
+at the end.
+ 
+A somewhat baroque (but taken from an actual text) example illustrates
+most of these points.
+{\verbatim
+$$
+\bfig
+\putmorphism(0,2100)(0,-1)[``T\eta'T]{1400}1l
+\putmorphism(0,2100)(1,0)[TT`T`\mu]{700}1a
+\putmorphism(0,2100)(1,-1)[`TTT'`TT\eta']{700}1l
+\putmorphism(700,2100)(1,-1)[`TT'`T\eta]{700}1r
+\put(700,1750){\makebox(0,0){1}}
+\putmorphism(700,1420)(1,0)[\phantom{TTT'}`\phantom{TT'}`\mu
+  T']{700}1a
+\putmorphism(700,1380)(1,0)[\phantom{TTT'}`%
+  \phantom{TT'}`T\sigma]{700}1b
+\putsquare<0`1`1`1;700`700>(700,700)[TTT'`TT'`TT'TT'`TT'T';`T\eta'TT'``]
+\putmorphism(700,700)(1,0)[\phantom{TT'TT'}`%
+  \phantom{TT'T'}`TT'\sigma]{700}1a
+\put(300,1400){\makebox(0,0){2}}
+\put(950,1050){\makebox(0,0){3}}
+\putbtriangle<0`1`0;700>(1400,700)[``TT';T\eta'T'`id`]
+\putmorphism(1400,700)(1,0)[\phantom{TT'T'}`%
+  \phantom{TT'}`T\mu']{700}1a
+\put(1600,1050){\makebox(0,0){6}}
+\putsquare<1`1`0`1;700`700>(0,0)[TT'T`\phantom{TT'TT'}`T'T`T'TT';%
+  TT'T\eta'`\sigma T``T'T\eta']
+\putmorphism(700,0)(1,0)[\phantom{T'TT'}`%
+  \phantom{T'T'}`T'\sigma]{700}1b
+\putsquare<0`0`1`1;700`700>(1400,0)[``T'T'`T';``\sigma`\mu']
+\putmorphism(700,700)(0,-1)[``\sigma TT']{700}1m
+\putmorphism(1400,700)(0,-1)[``\sigma T']{700}1m
+\put(300,350){\makebox(0,0){4}}
+\put(1050,350){\makebox(0,0){5}}
+\put(1750,350){\makebox(0,0){7}}
+\efig
+$$
+|egroup
+which produces
+$$
+\bfig
+\putmorphism(0,2100)(0,-1)[``T\eta'T]{1400}1l
+\putmorphism(0,2100)(1,0)[TT`T`\mu]{700}1a
+\putmorphism(0,2100)(1,-1)[`TTT'`TT\eta']{700}1l
+\putmorphism(700,2100)(1,-1)[`TT'`T\eta]{700}1r
+\put(700,1750){\makebox(0,0){1}}
+\putmorphism(700,1420)(1,0)[\phantom{TTT'}`\phantom{TT'}`\mu
+  T']{700}1a
+\putmorphism(700,1380)(1,0)[\phantom{TTT'}`%
+  \phantom{TT'}`T\sigma]{700}1b
+\putsquare<0`1`1`1;700`700>(700,700)[TTT'`TT'`TT'TT'`TT'T';`T\eta'TT'``]
+\putmorphism(700,700)(1,0)[\phantom{TT'TT'}`%
+  \phantom{TT'T'}`TT'\sigma]{700}1a
+\put(300,1400){\makebox(0,0){2}}
+\put(950,1050){\makebox(0,0){3}}
+\putbtriangle<0`1`0;700>(1400,700)[``TT';T\eta'T'`id`]
+\putmorphism(1400,700)(1,0)[\phantom{TT'T'}`%
+  \phantom{TT'}`T\mu']{700}1a
+\put(1600,1050){\makebox(0,0){6}}
+\putsquare<1`1`0`1;700`700>(0,0)[TT'T`\phantom{TT'TT'}`T'T`T'TT';%
+  TT'T\eta'`\sigma T``T'T\eta']
+\putmorphism(700,0)(1,0)[\phantom{T'TT'}`%
+  \phantom{T'T'}`T'\sigma]{700}1b
+\putsquare<0`0`1`1;700`700>(1400,0)[``T'T'`T';``\sigma`\mu']
+\putmorphism(700,700)(0,-1)[``\sigma TT']{700}1m
+\putmorphism(1400,700)(0,-1)[``\sigma T']{700}1m
+\put(300,350){\makebox(0,0){4}}
+\put(1050,350){\makebox(0,0){5}}
+\put(1750,350){\makebox(0,0){7}}
+\efig
+$$
+ 
+Here is a page of samples of the results from the various
+{\tt\\putshapes}.  The code
+{\verbatim
+$$
+\bfig
+\putsquare(0,0)[A`B`C`D;f`g`h`k]
+\putbtriangle(0,1500)[A`B`C;f`g`h]
+\putdtriangle(2200,1500)[A`B`C;f`g`h]
+\putptriangle(0,3000)[A`B`C;f`g`h]
+\putqtriangle(1000,500)[A`B`C;f`g`h]
+\putCtriangle(1500,750)[A`B`C;f`g`h]
+\putDtriangle(700,1000)[A`B`C;f`g`h]
+\putAtriangle(2000,2200)[A`B`C;f`g`h]
+\putAtrianglepair(0,2500)[A`B`C`D;f`g`h`k`l]
+\putVtriangle(2000,3000)[A`B`C;f`g`h]
+\putVtrianglepair(1000,2500)[A`B`C`D;f`g`h`k`l]
+\efig
+$$
+|egroup
+produces the diagram:
+$$
+\bfig
+\putsquare(0,0)[A`B`C`D;f`g`h`k]
+\putbtriangle(0,1500)[A`B`C;f`g`h]
+\putdtriangle(2200,1500)[A`B`C;f`g`h]
+\putptriangle(0,3000)[A`B`C;f`g`h]
+\putqtriangle(1000,500)[A`B`C;f`g`h]
+\putCtriangle(1500,750)[A`B`C;f`g`h]
+\putDtriangle(700,1000)[A`B`C;f`g`h]
+\putAtriangle(2000,2200)[A`B`C;f`g`h]
+\putAtrianglepair(0,2500)[A`B`C`D;f`g`h`k`l]
+\putVtriangle(2000,3000)[A`B`C;f`g`h]
+\putVtrianglepair(1000,2500)[A`B`C`D;f`g`h`k`l]
+\efig
+$$
+ 
+Added: For horizontal and vertical lines only, arrow parameters of
+$\pm4$, $\pm5$ and $\pm6$ will give dashed lines.
+ 
+Here is a double cube:
+{\verbatim
+$$
+\bfig
+\putsquare(0,750)[A`B`C`D;```]
+\putsquare(0,250)[\phantom{C}`\phantom{D}`E`F;```]
+\putsquare(250,500)[A'`B'`C'`D';```]
+\putsquare(250,0)[\phantom{C'}`\phantom{D'}`E'`F';```]
+\putmorphism(0,1250)(1,-1)[```]{250}1a
+\putmorphism(500,1250)(1,-1)[```]{250}1a
+\putmorphism(0,750)(1,-1)[```]{250}1a
+\putmorphism(500,750)(1,-1)[```]{250}1a
+\putmorphism(0,250)(1,-1)[```]{250}1a
+\putmorphism(500,250)(1,-1)[```]{250}1a
+\efig
+$$
+|egroup
+$$
+\bfig
+\putsquare(0,750)[A`B`C`D;```]
+\putsquare(0,250)[\phantom{C}`\phantom{D}`E`F;```]
+\putsquare(250,500)[A'`B'`C'`D';```]
+\putsquare(250,0)[\phantom{C'}`\phantom{D'}`E'`F';```]
+\putmorphism(0,1250)(1,-1)[```]{250}1a
+\putmorphism(500,1250)(1,-1)[```]{250}1a
+\putmorphism(0,750)(1,-1)[```]{250}1a
+\putmorphism(500,750)(1,-1)[```]{250}1a
+\putmorphism(0,250)(1,-1)[```]{250}1a
+\putmorphism(500,250)(1,-1)[```]{250}1a
+\efig
+$$
+ 
+ 
+ 
+\end{document}