%% $Id: xy.doc,v 3.7 1999/02/16 15:12:50 krisrose Exp $ %% %% Basic Xy-pictures: Xy-pic bootstrap and kernel macros. %% Copyright (c) 1991-1999 Kristoffer H. Rose %% %% This file is part of the Xy-pic package for graphs and diagrams in TeX. %% Copyright (c) 1991-1999 Kristoffer H. Rose %% %% The Xy-pic package is free software; you can redistribute it and/or modify %% it under the terms of the GNU General Public License as published by the %% Free Software Foundation; either version 2 of the License, or (at your %% option) any later version. %% %% The Xy-pic package is distributed in the hope that it will be useful, but %% WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY %% or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License %% for more details. %% %% You should have received a copy of the GNU General Public License along %% with this package; if not, write to the Free Software Foundation, Inc., %% 675 Mass Ave, Cambridge, MA 02139, USA. %% \ifx\xyloaded\undefined\else\message{not reloaded}\endinput\fi \let\xyloaded=\relax % NOTE: Apart from the actual macros (as also found in xy.tex), this file % contains both the Xy-pic kernel reference manual and TeXnical documentation. % See xyrefer.man and xysource.man for how to typeset this information. \message{Bootstrap\string'ing\string:} {\catcode96 12\catcode`\#6\catcode`\.12\catcode`\:12\catcode`\'12\catcode`\@11 \ifx\xywarnifdefined\undefined\else \immediate\write16{}% \immediate\write16{Xy-pic Warning: \string\xywarnifdefined\space redefined.}% \immediate\write16{}\fi \gdef\xywarnifdefined#1{\ifx#1\undefined\else \immediate\write16{}% \immediate\write16{Xy-pic Warning: `\string#1' redefined.}% \immediate\write16{}\fi} \xywarnifdefined\xydef@ \gdef\xydef@#1{\xywarnifdefined#1\gdef#1} \xywarnifdefined\xylet@ \gdef\xylet@#1{\xywarnifdefined#1\global\let#1} \xywarnifdefined\xynew@ \gdef\xynew@#1#2{\xywarnifdefined#2\csname new#1\endcsname#2}} \message{catcodes\string,} \xywarnifdefined\xyuncatcodes \xywarnifdefined\xyreuncatcodes \def\xyreuncatcodes{\edef\xyuncatcodes{% \catcode92 0 \catcode123 1 \catcode125 2 \catcode37 14 \catcode 9 \the\catcode 9 \catcode10 \the\catcode10 \catcode12 \the\catcode12 \catcode35 \the\catcode35 \catcode36 \the\catcode36 \catcode38 \the\catcode38 \catcode43 \the\catcode43 \catcode45 \the\catcode45 \catcode46 \the\catcode46 \catcode47 \the\catcode47 \catcode60 \the\catcode60 \catcode61 \the\catcode61 \catcode62 \the\catcode62 \catcode64 \the\catcode64 \catcode96 \the\catcode96 \newlinechar \the\newlinechar \endlinechar \the\endlinechar }} \xyreuncatcodes \xywarnifdefined\xycatcodes \def\xycatcodes{% \catcode 9 10 \catcode 35 6 \catcode 36 3 \catcode 38 4 \catcode 43 12 \catcode 45 12 \catcode 46 12 \catcode 47 12 \catcode 60 12 \catcode 61 12 \catcode 62 12 \catcode 64 11 \catcode 96 12 } \xycatcodes \message{docmode,} {\catcode`\|0 \xywarnifdefined|DOCMODE \gdef|DOCMODE#1{\ifx(#1\relax \xycatcodes \expandafter\ignorespaces \else \skipspecials@ \expandafter\docm@\fi}% \xywarnifdefined\skipspecials@ \gdef\skipspecials@{% \catcode`\\12 \catcode`\{12 \catcode`\}12 \catcode`\#12 \catcode`\%12 \catcode`\^^L12 \endlinechar`\^^J }% \catcode`\/=12 \lccode`\/`\\% \lccode`\D`\D \lccode`\O`\O \lccode`\C`\C \lccode`\M`\M \lccode`\E`\E \lowercase{% \xywarnifdefined\docm@ \gdef\docm@{\docm@i}% \xywarnifdefined\docm@i \gdef\docm@i#1^^J{\docm@ii#1/DOCMODE\docm@iii}% \xywarnifdefined\docm@ii \gdef\docm@ii#1/DOCMODE{\def\next@{#1}\futurelet\next\docm@iii}% \xywarnifdefined\docm@iii \gdef\docm@iii#1\docm@iii{% \ifx\next\docm@iii \let\next\next@ \docecho@ \let\next@\docm@ \else\ifx\next@\empty \let\next@\docfinish@ \else \edef\next@{\noexpand\docm@iv\next@/DOCMODE#1\noexpand\docm@iv}% \fi\fi \next@}% \xywarnifdefined\docm@iv \gdef\docm@iv#1/DOCMODE\docm@iv{\def\next{#1}\docecho@ \docm@}}% \xywarnifdefined\docecho@ \global\let\docecho@\relax \xywarnifdefined\docfinish@ \gdef\docfinish@{\xyuncatcodes|DOCMODE\next}} \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% After giving an overview of the \Xy-pic environment in \S??[env], this \FILE\ document the basic concepts of \Xy-picture construction in \S??[basics], including the maintained `graphic state'. The following sections give the precise syntax rules of the main \Xy-pic constructions: the position language in~\S??[pos], the object constructions in~\S??[object], and the picture `decorations' in~\S??[decor]. \S??[objectlib] presents the kernel repertoire of objects for use in pictures; \S??[option] documents the interface to \Xy-pic options like the standard `feature' and `extension' options. \DOCMODE1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Details of the implementation are not discussed here but in the complete \TeX\-nical documentation~\cite{RM95:Xy-picCSTC}. \DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Section \S??[algo] documents the more complicated algorithms used to compute directions, edges, and connections. \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{The \Xy-pic implementation} ??=[env] This section briefly discusses the various aspects of the present \Xy-pic kernel implementation of which the user should be aware. \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Loading \Xy-pic} ??=[env.loading]??w[loading] \Xy-pic is careful to set up its own environment in order to function with a large variety of formats. For most formats a single line with the command $$ ??c![\input xy] $$ in the preamble of a document file should load the kernel (see `integration with standard formats' below for variations possible with certain formats, in particular \LaTeX~\cite{L94:LaTeX}). The rest of this section describes things you must consider if you need to use \Xy-pic together with other macro packages, style options, or formats. The less your environment deviates from plain \TeX\ the easier it should be. \DOCMODE1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Consult the \TeX\-nical documentation~\cite{RM95:Xy-picCSTC} for the exact requirements for other definitions to coexist with \Xy-pic. \DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph*{File header:} ??w[file header] Here is what actually happens in the header of |xy.doc|. It contains the copyright message, protection against ??w![loading] the file more than once, and then bootstrap code to handle category codes and the ??c![DOCMODE] format---we explain each separately below: \DOCHEADER \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph*{Privacy:} ??w[privacy] \Xy-pic will warn about control sequences it redefines---thus you can be sure that there are no conflicts between \Xy-pic-defined control sequences, those of your format, and other macros, provided you load??w[loading] \Xy-pic last and get no ??w![warning messages] like $$ |Xy-pic Warning: `|\dots|' redefined.|??w[redefined] $$ In general the \Xy-pic kernel will check all control sequences it redefines "except" that (1)~generic temporaries like ??c![\next] are not checked, (2)~predefined font identifiers (see~\S??[env.fonts]) are assumed intentionally preloaded, and (3)~some of the more exotic control sequence names used internally (like |@{-}|) are only checked to be different from ??c![\relax]. \DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% This is handled by ??c![\xywarnifdefined]---after we have ensured that it is unique itself\footnote{This may seem paranoid but in fact many inconvieniences in the \TeX\ world stem from the fact that somebody copied somebody elses definition of, say, {\tt\string\xywarnifdefined}, modified it, and then used it in something that somehow got distributed! The `flat name space' problem remains \TeX\ largest problem as a programming language in this \TeX\ hackers opinion.}. ??c![\xydef@], ??c![\xylet@], and |\xynew@{||}|??c[\xynew@] are abbreviations used to this end throughout \Xy-pic instead of ??c![\let], ??c![\def], and the |\new| commands. Next some auxilliaries: |\xydefcsname@| is similar to |\xydef@| except that it builds the control sequence with ??c![\csname] \dots\ ??c![\endcsname] which means that it is |\relax| when undefined---there is thus no way to prevent redefinition of control sequences bound to ??c![\relax]~\frowny. \DOCMODE( \xydef@\xydefcsname@#1{\DN@{#1}\DNii@##1{% \ifx ##1\relax\else \xywarning@{\string`\string##1\string' redefined}\fi \def##1}% \expandafter\nextii@\csname\codeof\next@\endcsname} \DOCMODE) |\xyletcsnamecsname@| is to ??c![\let] one weird control sequence be the same as another using several |\expandafter|s: \DOCMODE( \xydef@\xyletcsnamecsname@#1#2{\def\1{#1}\def\2{#2}\DN@##1##2{% \ifx ##1\relax\else \xywarning@{`\string##1\string' redefined}\fi \let##1=##2}% \expandafter\expandafter\expandafter\next@ \expandafter\csname\expandafter\codeof\expandafter\1\expandafter\endcsname \csname\codeof\2\endcsname} \DOCMODE) Finally ??c![\codeof]: a useful hack used to allow any characters in control sequences: ??c![\codeof] expands to the characters of the control sequence as a string of `other' characters, \ie, all of category 12 and with a \verb*/ /$_{12}$ after every control sequence. The must be a macro or it blows up. \DOCMODE( \xywarnifdefined\codeof \xywarnifdefined\codeof@ {\catcode`\:=12 % to ensure that all of :-> and <-: are other :-) \gdef\codeof#1{\expandafter\codeof@\meaning#1<-:} \gdef\codeof@#1:->#2<-:{#2}} \DOCMODE) \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph*{Category codes:\ } The situation is complicated by the flexibility of \TeX's input format. The culprit is the `??w![category code]' concept of \TeX\ (\cf~\cite[p.37]{K84:TeXbook}): when loaded \Xy-pic requires the characters {\tt\char32}|\{}%| (the first is a space) to have their standard meaning and all other printable characters to have the "same category as when \Xy-pic will be used"---in particular this means that (1)~you should surround the ??w![loading] of \Xy-pic with ??c![\makeatother] \dots\ ??c![\makeatletter] when loading it from within a \LaTeX\ package, and that (2)~\Xy-pic should be loaded after files that change category codes like the ??c![german.sty] that makes |"| active??w[active characters]. Some styles require that you reset the catcodes for every diagram, \eg, with ??c![french.sty] you should use the command |\english| before every |\xymatrix|. \DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% We define ??c![\xyuncatcodes] to restore the current catcodes, and ??c![\xycatcodes] to install our own. Here is an exact list of the category codes which \Xy-pic requires (all standard in plain \TeX): $$ \vcenter{\tabskip=.5em plus1fil \halign to\displaywidth{#\hfil&&\hfil#\hfil\cr character(s) &|\| &|{| &|}| &CR &TAB SP&|A|--|Z| |a|--|z| &|0|--|9| &|%| \cr category code & 0 & 1 & 2 & 5 & 10 & 11 & 12 & 14 \cr} }$$ Furthermore none of the remaining printable ASCII characters $$ |!"#$&'()*,/:;?@[]^_`||~| $$ may be of category 0, 1, 2, 9, 14, or 15, because all should be tokens allowed in the replacement text of a |\def|---this also means that they may not be active characters defined to be ``|\outer|''! All other catcodes needed are established using ??c![\xycatcodes] defined above---this is the reason the macros must be loaded at a time where the category codes are stable (otherwise it will make them stable!). Internally \Xy-pic enforces the following category codes: $$ \vcenter{\tabskip=.5em plus1fil \halign to\displaywidth{#\hfil&&\hfil#\hfil\cr character &|#|&|$|&|&|&|'|&|+|&|-|&|.|&|<|&|=|&|>|&|@|&|`|\cr ASCII code & 35& 36& 38& 39& 43& 45& 46& 60& 61& 62& 64& 96\cr category code& 6 & 3 & 4 & 12& 12& 12& 12& 12& 12& 12& 11& 12\cr abbreviation&|HASH|&|DOLL|&|AND|&|RQ|&|PLUS|&|DASH|&|DOT| &|LT|&|EQ|&|GT|&|AT|&|LQ|\cr} }$$ with special control sequences named |\add||@| that take an argument and expand to it followed by the original character token, \ie, many tests throughout the program look like |\addDOT@| |\ifx| |\next| \dots \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \DOCMODE( \xywarnifdefined\addAT@ \xywarnifdefined\addHASH@ \xywarnifdefined\addDOLL@ \xywarnifdefined\addAND@ \xywarnifdefined\addRQ@ \xywarnifdefined\addPLUS@ \xywarnifdefined\addDASH@ \xywarnifdefined\addDOT@ \xywarnifdefined\addLT@ \xywarnifdefined\addEQ@ \xywarnifdefined\addGT@ \xywarnifdefined\addLQ@ \xydef@\xymakeADD@#1#2 #3 {\ifnum\catcode#3=6 \def#1##1{##1#2#2}% \else \def#1##1{##1#2}\fi} \xydef@\xyrecat@{\xymakeADD@\addAT@} \xydef@\xyrecat{\xyrecat@} \xydef@\xyresetcatcodes{\def\xyrecat{\xyrecat@}\xyreuncatcodes \input xyrecat \relax \xyuncatcodes} \xyuncatcodes \xyresetcatcodes \xycatcodes \xydef@\testAND@{{\aftergroup\ifx \addAND@\ifx\next\addFalse@\else\addTrue@\fi}} \xydef@\addFalse@{\aftergroup\iffalse} \xydef@\addTrue@{\aftergroup\iftrue} \DOCMODE) \inputdoc!{xyrecat.doc} \DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The last block of the \Xy-pic header bootstraps the ``??c![DOCMODE] format'' used in |.doc| variants of \Xy-pic macro files in order to keep documentation and macros together in a literal programming style (this is redundant in the |xy.tex| macro file where all instances of |DOCMODE| have been eliminated (see chapter \S??g[:Makefile] for how this is accomplished) but it is included anyway since users may load options still in |DOCMODE| format). The details of |DOCMODE| are described in |xydoc.sty|, a special \LaTeX\ package used to typeset \Xy-pic documentation; please read it if you intend to write \Xy-pic options. \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph*{Integration with standard formats} ??w[formats] % This is handled by the |xyidioms.tex| file and the integration as a \LaTeX~\cite{L94:LaTeX} package by |xy.sty|. \DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% We input |xyidioms.tex| from the kernel: \DOCMODE( \input xyidioms \DOCMODE) \DOCMODE1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph*{xyidioms.tex:} ??c[xyidioms.tex]% \DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph*{xyidioms.doc:} ??c[xyidioms.doc]% \DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \inputdoc!{xyidioms.doc} \paragraph{xy.sty:} ??c[xy.sty]% %% If you use ??w![\LaTeX] then this file makes it possible to load??w[loading] \Xy-pic as a `??w![package]' using the ??w![\LaTeXe]~\cite{L94:LaTeX} ??c![\usepackage] command: % \begin{defs1} ??c![\usepackage] |[|