diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/xypic/xygraph.doc')
-rw-r--r-- | Master/texmf-dist/source/generic/xypic/xygraph.doc | 710 |
1 files changed, 710 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/xypic/xygraph.doc b/Master/texmf-dist/source/generic/xypic/xygraph.doc new file mode 100644 index 00000000000..718d12a2182 --- /dev/null +++ b/Master/texmf-dist/source/generic/xypic/xygraph.doc @@ -0,0 +1,710 @@ +%% $Id: xygraph.doc,v 3.7 1999/02/16 15:12:50 krisrose Exp $ +%% +%% Xy-pic ``Graph Combinator feature'' option. +%% Copyright (c) 1994-1997 Kristoffer H. Rose <krisrose@brics.dk> +%% +%% This file is part of the Xy-pic package for graphs and diagrams in TeX. +%% See the companion README and INSTALL files for further information. +%% Copyright (c) 1991-1997 Kristoffer H. Rose <krisrose@brics.dk> +%% +%% 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 \input xy \fi + +\xyprovide{graph}{Graph feature}{\stripRCS$Revision: 3.7 $}% + {Kristoffer H.~Rose}{krisrose@brics.dk}% + {BRICS/Computer Science, University of Aarhus, Ny Munkegade, building 540, + DK--8000 Aarhus~C} + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + This option implements `\Xy-graph', a special "combinatoric drawing + language" suitable for diagrams like flow charts, directed graphs, + and various forms of trees. The base of the language is reminiscent + of the PIC~\cite{K82:PIC-LTG} language because it uses a notion of + the `current location' and is based on `moves'. But the central + construction is a `map' combinator that is borrowed from functional + programming. + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph*{Header:}\leavevmode +\DOCHEADER +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + \Xy-graph makes use of facilities of the `arrow' feature option of + \S??g[:arrow], which is therefore required. + +\DOCMODE( +\xyrequire{arrow}\xycatcodes +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + Figure~??[f.graph] summarises the syntax of a <graph> with notes + below. A <graph> can appear either in an \Xy-picture (as <decor>) or + ``stand-alone''.\footnote{In fact \LaTeX\ users can use a |graph| + environment.} \NOTE: If you use ??c![\xygraph]|{|\dots|}| inside + constructions where |&| is significant (like plain \TeX's + ??c![\halign] or \LaTeX's ??c![array] environment) then make sure to + add an extra level of braces around it. + +\begin{figure*}[tb] +\begin{syntax} +% + \multispan{3}{{\tt\string\xygraph\string{<graph>\string}}\hfil} + & typeset <graph> +\cr +\noalign{\nobreak\smallskip\nobreak\hrule\nobreak\smallskip\nobreak} +% + ??w![<graph>] + &\iss & <step>\star + & interpret <step>s in sequence +\cr +\noalign{\smallskip} + ??w![<step>] + &\iss & <node> + & ??!^[move] to the <node> +\cr + &\orr & |-|<arrow> <node> <labels> + & ??!^[draw] line to <node>, with <labels> +\cr + &\orr & |:|<arrow> <node> <labels> + & ??!^[draw] <arrow> to <node>, with <labels> +\cr + &\orr & |(| <list> |)| + & ??!^[map] current node over <list> +\cr +\noalign{\smallskip} +% + ??w![<node>] + &\iss & |[| <move> |]| + & new node <move>d relative to current +\cr + &\orr & |&| \orr\ |\\| + & new node in ??!^[next column/row] +\cr + &\orr & |"|<id>|"| + & previously ??!^[saved] node +\cr + &\orr & |?| + & currently ??!^[mapped] node +\cr + &\orr & <node> <it> + & <node> with <it> ??!^[typeset and saved] there +\cr + &\orr & <node> |=| |"|<id>|"| + & <node> ??!^[saved] as |"|<id>|"| +\cr + &\orr & <node> |!| <escape> + & augment node with material in another mode +\cr +\noalign{\smallskip} +% + ??w![<move>] + &\iss & <hop>\star\ + & ??!^[<hop>s] (|dulr|) from current node +\cr + &\orr & <hop>\star\ <place> <move> + & do ??!^[<hop>s] but use its <place> and <move> again +\cr +\noalign{\smallskip} +% + ??w![<list>] + &\iss & <graph> |,| <list> \orr\ <graph> + & ??!^[list of subgraphs] +\cr +\noalign{\smallskip} +% + ??w![<escape>] + &\iss & |{| <pos> <decor> |}| + & ??!^[perform <pos> <decor>] +\cr + &\orr & |M| <matrix> + & ??!^[insert <matrix>] +\cr + &\orr & |P| <polygon> + & ??!^[insert <polygon>] +\cr + &\orr & |E| <ellipse> + & ??!^[insert <ellipse>] +\cr + &\orr & |~| <setup> + & ??!^[setup parameters] +\cr +\end{syntax} +\caption{\protect<graph>s}??=[f.graph] +\end{figure*} + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\paragraph*{Parsing:} + + The parser does almost everything that this feature does because it + is all implemented directly on top of other constructions, notably + the kernel stack and the <arrow> construction. + + The graph state always has the current value of |?| both as the + stacktop and in the special <id> |"?NODE"|. + +\DOCMODE( +\xydef@\xygraph#1{\relax\graph#1\endgraph} + +\xydef@\graph{\if\inxy@ \DN@{\xy@@{\nter@{}}}% + \else \DN@{\xy \xy@\xy{\nter@\endxy}}\fi \next@ + \xy@\xygraph{\senter@ \idfromc@{?NODE}\spushc@ + \expandafter\let\expandafter\next@\csname Q@graphbase\endcsname + \ifx\next@\relax \setbase@\z@\z@{3pc}\z@ + \else \expandafter\next@ \fi}% + \GRAPH[]} + +\xydef@\endgraph{\ignorespaces} + +\xydef@\GRAPH{\xyFN@\GRAPH@} + +\xydef@\GRAPH@{% +% +%\W@{GRAPH: next=\meaning\next}% +% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\GRAPH@}% + \else\ifx :\next \DN@:{\xy@:{}\expandafter\GRAPHar@\GRAPHeveryarrow@@}% + \else\addDASH@\ifx\next + \addDASH@\DN@{\xy@-{}\expandafter\GRAPHar@\GRAPHeveryline@@}% + \else\ifx (\next + \DN@({\xy@({\spushid@{?NODE}\idfromc@{?NODE}}\xyFN@\GRAPH@}% + \else\ifx ,\next + \DN@,{\xy@,{\cfromid@{?NODE}}\xyFN@\GRAPH@}% + \else\ifx )\next + \DN@){\xy@){\cfromid@{?NODE}% + \tests@\z@{\idfroms@{?NODE}\z@ \spop@}{\xyerror@{) without (}{}}}% + \xyFN@\GRAPH@}% + % HACK: ONLY POP WHEN NONEMPTY...WHY EVER NONEMPTY? + \else\ifx \endgraph\next \DN@{\xy@@{\tests@\z@\spop@\sleave@\leave@}}% + \else\ifx \end\next \DN@{\xy@@{\tests@\z@\spop@\sleave@\leave@}}% + \else\ifx ~\next + \DN@~{\xy@@{\enter@\cfromthec@}\afterNODE{\leave@ \xyFN@\GRAPH@}!}% + \else \DN@{\afterNODE{\xyFN@\GRAPH@}}% + \fi\fi\fi\fi\fi\fi\fi\fi\fi \next@} + +\xylet@\GRAPHsaved@PATHafterPOS=\PATHafterPOS +\xylet@\GRAPHsaved@afterar@@=\afterar@@ + +\xydef@\GRAPHar@{% + \let\PATHafterPOS=\afterNODE \let\afterar@@=\GRAPHafterar@ \ar} + +\xydef@\GRAPHafterar@{% + \let\PATHafterPOS=\GRAPHsaved@PATHafterPOS + \let\afterar@@=\GRAPHsaved@afterar@@ + \xy@@{\cfromid@{}}\xyFN@\GRAPH@} + +\xylet@\afterNODE@@=\empty + +\xydef@\afterNODE#1{\xy@@{\enter@\pfromthep@}% + \DN@##1{\def\afterNODE@@{\xy@@\leave@ \def\afterNODE@@{##1}#1}}% + \expandafter\next@\expandafter{\afterNODE@@}% + \xyFN@\NODE@} + +\xylet@\theMOVE@@=\relax + +\xydef@\NODE@{% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\NODE@}% + \else\ifx [\next \DN@[##1]{\xy@{[##1]}{}% + \def\theMOVE@@{[##1]}\xyFN@\MOVE@##1]}% + \else\ifx "\next \DN@ "##1"{% + \xy@{"##1"}{\cfromid@{##1}}\def\theMOVE@@{"##1"}\xyFN@\NODE@i}% + \else\ifx ?\next \DN@ ?{% + \xy@?{\cfromid@{?NODE}}\def\theMOVE@@{?}\xyFN@\NODE@i}% + \else\ifx !\next \def\theMOVE@@{[]}\let\next@=\NODE@i + \else \testAND@\iffalse + \DN@##1{\xy@{}{\pfromc@ \advance\X@c\X@xbase \advance\Y@c\Y@xbase + \czeroEdge@}\jumpMOVE@ \xyFN@\NODE@i}% + \else\ifx \\\next + \DN@\\{\xy@\\{\pfromc@ \advance\X@c\X@xbase \advance\Y@c\Y@xbase + \R@c=\X@ybase \U@c=\Y@ybase \intersect@ + \advance\X@c-\X@ybase \advance\Y@c-\Y@ybase + \czeroEdge@}\def\theMOVE@@{\\}\xyFN@\NODE@i}% + \else \xyerror@{Illegal <node>: \string`\meaning\next\string' unexpected}{}% + \fi\fi\fi\fi\fi\fi\fi \next@} + +\xydef@\jumpMOVE@@{&} +\xydef@\jumpMOVE@{\let\theMOVE@@=\jumpMOVE@@} + +\xydef@\MOVE@{\xy@@{\count@=\z@ \count@@=\z@}% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\MOVE@}% + \else\ifcat A\noexpand\next \let\next@=\MOVE@letter + \else \let\next@=\MOVE@x \fi\fi \next@} + +\xydef@\MOVE@letter{% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\MOVE@letter}% + \else\ifx u\next \DN@ u{\xy@@{\advance\count@\@ne}\xyFN@\MOVE@letter}% + \else\ifx d\next \DN@ d{\xy@@{\advance\count@\m@ne}\xyFN@\MOVE@letter}% + \else\ifx l\next \DN@ l{\xy@@{\advance\count@@\m@ne}\xyFN@\MOVE@letter}% + \else\ifx r\next \DN@ r{\xy@@{\advance\count@@\@ne}\xyFN@\MOVE@letter}% + \else \let\next@=\MOVE@x \fi\fi\fi\fi\fi \next@} + +\xydef@\MOVE@x{%[[ + \ifx ]\next \DN@ ]{\MOVE@hop \xyFN@\NODE@i}% + \else\ifx (\next \DN@{\MOVE@hop \xyFN@\MOVE@place}%) + \else\ifx !\next \DN@{\MOVE@hop \xyFN@\MOVE@place}% + \else\ifx /\next \DN@{\MOVE@hop \xyFN@\MOVE@place}% + \else\addLT@\ifx\next \DN@{\MOVE@hop \xyFN@\MOVE@place}% + \else\addGT@\ifx\next \DN@{\MOVE@hop \xyFN@\MOVE@place}% + \else\addDASH@\ifx\next \addDASH@\DN@{\xyerror@{- not implemented yet}{}}% + \else \xyerror@{illegal <move>: \codeof\theMOVE@@}{}\let\next@=\NODE@i + \fi\fi\fi\fi\fi\fi\fi \next@} + +\xydef@\MOVE@hop{\xy@@{\pfromc@ \czeroEdge@ + \edef\next@{\the\count@@,\the\count@ @}\expandafter\vfromcartesian@@\next@ + \advance\X@c-\X@origin \advance\Y@c-\Y@origin + \advance\X@c\X@p \advance\Y@c\Y@p}} + +\xydef@\MOVE@place{\xy@@\no@@ \afterPLACE{\xyFN@\MOVE@}} + +\xydef@\NODE@i{\let\next@=\NODE@x +% +%\W@{NODE@i: next=\meaning\next}% +% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\NODE@i}% + \else\addEQ@\ifx \next + \addEQ@\DN@"##1"{\xy@{="##1"}{\idfromc@{##1}}\xyFN@\NODE@i}% + \else\ifx !\next \DN@!{\xyFN@\NODE@escape}% + \else\ifx :\next + \else\addDASH@\ifx\next + \else\ifx (\next + \else\ifx ,\next + \else\ifx )\next + \else\ifx ~\next + \else\ifx [\next + \else\ifx "\next + \else\ifx ?\next +% + \else\ifx ^\next + \else\ifx _\next + \else\ifx |\next + \else\addLQ@\ifx\next + \else\addRQ@\ifx\next +% + \else \testAND@ \iffalse + \else\ifx \\\next +% + \else\ifx \endgraph\next + \else\ifx \end\next +% + \else \let\next@=\NODE@it + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi \next@} + +\xydef@\NODE@x{\xy@@{\idfromc@{}}\afterNODE@@} + +\xydef@\NODE@it{\let\PATHlabelit@@=\NODEit@ \PATHit@} + +{\xyuncatcodes \gdef\next{+}} +\xylet@\GRAPHnodemodifiers@@=\next + +\xydef@\NODEit@#1{% + \DN@{#1}\ifx\next@\empty + \DN@{\expandafter\NODEit@i\expandafter{\GRAPHnodemodifiers@@}}% + \else \DN@{\NODEit@i{#1}}\fi \next@} + +\def\NODEit@i#1#2{\xy@{*#1{#2}}{\drop@{#1}{#2}}% + \DN@{\addEQ@\ifx\next\else \xy@@{\idfromc@{#2}}\fi \NODE@i}% + \xyFN@\next@} +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{notes} +% +\note??=[move] +% + A "move" is to establish a new "current node". + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[draw] +% + To "draw" something is simply to draw a line or the specified <arrow> + from the current node to the specified target node. The target then + becomes the current node. All the features of arrows as described + in~\S??g[:arrow] can be used, in particular arrows can be labelled and + segmented, but with the change that <path-pos> means <node> as + explained in note~\S??g[xyarrow.doc:segment]. + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[map]??=[mapped]??=[list of subgraphs] +% + To "map over a list" is simply to save the current node and then + interpret the <list> with the following convention: +% +\begin{itemize} +\item Start each element of the list with the current node as saved and $p$ + as the previous list element, and +\item let the |?| <node> refer to the saved current node explicitly. +\end{itemize} + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[next column/row] +% + The |&| and |\\| special moves are included to make it simple to enter + `matrix-like' things as graphs -- note that they will not be + automatically aligned, however, for that you should use the |!M| + escape. + + |&| is the same as |[r]| and |\\| is the same as + |[r]!{y+(0,-1)-(0,0)}| which uses a kernel escape to moves to the + first column in the next row (where the first column is on the + $y$-axis of the current coordinate system). + + \NOTE: If you use the form |*{|\dots|}| for nodes then you don't + have to change them if you decide to use an \Xy-matrix. + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[typeset and saved]??=[saved] +% + Typeset <it> and make it the current node. Also saves <it> for later + reference using |"|<id>|"|: if <it> is a simple letter, or digit, + then just as |"|<it>|"|; if <it> is of the form + |{|"text"|}| or |*|\dots|{|"text"|}| then as |"|"text"|"|. + + With the |=| addition it is possible to save explicitly in case + several nodes have the same text or a node has a text that it is + impractical to use for reference. In fact using the form + <it>|="|<id>|"| will "only" save the node as |"|<id>|"| and "not" as + |"|<it>|"|! As a special convenience |""| (thus the empty <id>) + always refers to the last completed node, so adding |=""| after a + node merely means it should "not" be saved under its proper name. + +\begin{exercise} + How did the author typeset this? +% +\begin{code} +\xygraph{ + []A="A1" :@/^/ [r]A + :@/^/ [r]A + :@/^/ "A1" } +\end{code} +$$\docode$$ +% +\answercode +\answertext{The first $A$ was named to allow reference from the last: + \displaycode} +\end{exercise} + +\note??=[<hop>s] +% + Moving by a series of "hops" is simply moving in a grid as the + sequence of |dulr| (for down/up/left/right) indicates. The grid is a + standard cartesian coordinate system with 3pc unit unless the current + base is redefined using |[]!{|\dots|}| with an appropriate <pos>ition + containing |:| and |::| as described in note~??g[xy.doc:base]. + + \TODO: Describe the use of <move>s with <place>s in detail \dots\ in + particular (1)~`until perpendicular to \dots' and (2)~`until + intercepts with \dots' can be coded\dots + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[perform <pos> <decor>] +% + This `escapes' into the \Xy-pic kernel language and interprets the + <pos> <decor>. The current node is then set to the resulting $c$ + object and the grid from the resulting "base". + + The effect of the <pos> <decor> can be completely hidden from + \Xy-graph by entering it as |{\save| <pos> <decor> |\restore}|. + +\DOCMODE( +\xydef@\NODE@escape{% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\NODE@escape}% + \else\ifcat A\noexpand\next \DN@##1{\rungraphescape@{##1}}% + \else\ifcat !\noexpand\next \DN@##1{\rungraphescape@{##1}}% + \else\ifx \bgroup\next \DN@##1{\xy@{!{##1}}{}\POS##1\relax \xyFN@\NODE@i}% + \else\ifx ~\next \let\next@=\graphsetup@ + \else \DN@{\xyerror@{Unknown graph <escape>}{}\xyFN@\NODE@i}% + \fi\fi\fi\fi\fi \next@} +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[insert <matrix>] +% + It is possible to insert a <matrix> in a graph provided the `matrix' + option described in~\S??g[:matrix] has been loaded: it overwrites the + node with the result of |\xymatrix|<matrix>. Afterwards the graph + grid is set as the top left `square' of the matrix, \ie, with |[d]| + and |[r]| adjusted as they work in the top left entry. + + \BUG: |[dr]| immediately after the matrix will work as expected, \eg, + make the center of |"2,2"| the current node, but others might not, \eg, + |[rr]| will not necessarily place the current node on top of |"1,3"|. + +\DOCMODE( +\xydefcsname@{graph !M}#1#{\NODE@matrix{#1}} + +\xydef@\NODE@matrix#1#2{\xyerror@{matrix feature not loaded}{}\xyFN@\GRAPH@} + +\xydef@\NODE@matrix@#1#2{\xy@{!M#1{#2}}{}% + \def\everyentry@{\GRAPHeveryentry}% + \xymatrix#1{#2}% + \let\everyentry@=\empty \insertmatrixingraph@ \xyFN@\NODE@i} + +\xydef@\GRAPHeveryentry{\def\:{\ar}\def\="##1"{\xy@@{\idfromc@{##1}}}} + +\xywithoption{matrix}{\let\NODE@matrix=\NODE@matrix@} + +\xydef@\insertmatrixingraph@{% + \xy@@{\enter@{\cfromthec@ \pfromthep@}% + \expandafter\let\expandafter\next@\csname Q@1,1\endcsname + \ifx\next@\relax\else + \next@ \swap@ + \expandafter\let\expandafter\next@\csname Q@1,2\endcsname + \ifx\next@\relax\else \next@ \setbase@\X@p\Y@p\X@c\Y@c + \expandafter\let\expandafter\next@\csname Q@2,1\endcsname + \ifx\next@\relax\else + \next@ \setbase@@{-\X@c}{-\Y@c}\fi\fi\fi + \leave@}} +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[insert <polygon>]??=[insert <ellipse>] +% + It is possible to insert a <polygon> or an <ellipse> in a graph + provided the |poly| option described in~\S??g[:poly] or the |arc| + option described in~\S??g[:arc] has been loaded, respectively: + it will have $c$ as the current node, $p$ as the previous one, and + the the current base has the <hop>s |[r]| and |[u]| as base vectors. + + \NOTE: lattices, knots, \etc, can also be used but no special syntax + is useful since the |!{|\dots|}| syntax is adequate. + +\DOCMODE( +\xydefcsname@{graph !P}#1#{\NODE@poly{#1}} +\xydef@\NODE@poly#1#2{\xyerror@{poly(gon) feature not loaded}{}\xyFN@\GRAPH@} +\xydef@\NODE@poly@#1#2{\xy@{!P#1{#2}}{}\xypoly@#1{#2}\xyFN@\NODE@i} +\xywithoption{poly}{\let\NODE@poly=\NODE@poly@} + +\xydefcsname@{graph !E}#1#{\NODE@arc{#1}!} +\xydef@\NODE@arc#1#2{\xyerror@{(ellipse+)arc feature not loaded}{}% + \xyFN@\GRAPH@} +\xydef@\NODE@arc@#1#2{\xy@{!E#1{#2}}{}\ellipse#1{#2}\xyFN@\NODE@i} +\xywithoption{arc}{\let\NODE@arc=\NODE@arc@} +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\note??=[setup parameters] +% + This allows setting of some parameters of the graph: |!~|<setup> + should be one of the following: +% +\begin{defs} +% + |!~:{| <arrow> |}| & include with every |:| arrow \cr + |!~-{| <arrow> |}| & include with every |-| line \cr + |!~*{| <modifiers> |}| & include with every non-|*| node \cr + |!~|<letter>|{| <graph> |}| & define new graph escape |!|<letter> +% +\end{defs} +\noindent\unskip +% + These are destructive: the previous value is lost; the default is + established by the sequence |!~:{}| |!~-{@{-}}| |!~*{+}| making |:| + create simple arrows, |-| plain lines, and formatting default nodes + in math mode with the default objectmargin. + +\DOCMODE( +\xylet@\GRAPHeveryarrow@@=\empty + +{\xyuncatcodes \gdef\next{@{-}}} +\xylet@\GRAPHeveryline@@=\next + +\xydef@\graphsetup@~{\xyFN@\graphsetup@i} + +\xydef@\graphsetup@i{% + \ifx :\next \DN@:##1{\def\GRAPHeveryarrow@@{##1}\xyFN@\NODE@i}% + \else\addDASH@\ifx\next + \addDASH@\DN@##1{\def\GRAPHeveryline@@{##1}\xyFN@\NODE@i}% + \else\ifx *\next \DN@*##1{\def\GRAPHnodemodifiers@@{##1}\xyFN@\NODE@i}% + \else\ifcat A\next \DN@##1##2{\newgraphescape{##1}{##2}\xyFN@\NODE@i}% + \else \DN@{\xyerror@{illegal graph setup \codeof\next@}{}\xyFN@\NODE@i}% + \fi\fi\fi\fi \next@} +\DOCMODE) + + The last possibility is also available as a command +% +\begin{defs1} +% + ??c![\newgraphescape]|{|<letter>|}{|<graph>|}| \cr +% +\end{defs1} +\noindent\unskip +% + that makes the specified escape generate the <graph> as a macro; with + it it is possible to pass arguments to the <graph> using the standard + \TeX\ |\def| method: The declaration code +% +\begin{code} +\newgraphescape{i}#1#2{ + []!{+0="o#2"*=<10pt>{};p!#1**{},"o#2" + -/4pt/*!E\cir<2pt>{} + +0;p-/:a(-30)24pt/**\dir{-}="X2" + ;p-/:a(-60)24pt/="X1"**\dir{-} + ;?(.5),="i#2", + p-/:a(-60)24pt/**\dir{-}, + "o#2"."i#2"."X1"."X2"}} +\end{code} +{\gdocode}% +\displaycode\noindent +% + is (rather complicated kernel code) that makes the node escape + |!i|$dn$ typeset an `inverter' oriented with the $d$ corner as the + output with input named |"i|$n$|"| and output named |"o|$n$|"| such + that the graph +% +\begin{code} +\xygraph{ []!iR1 ("i1"[l]x - "i1") - [r]z } +\end{code} +\displaycode\noindent +% + will typeset +$$ +\docode +$$ + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + The ??c![\newgraphescape]<letter> declaration defines a macro with + name |\graph !|<letter>. It is slightly complicated by the fact that + we accept \LaTeX-style |[n]| arguments (when using \LaTeX, that + is~\smiley). Thus an internal macro named |\G!|<letter> is defined + using the appropriate command definition primitve; this is in turn + invoked by |\graph !|<letter> after activating the <graph> parser. + +\DOCMODE( +\xydef@\newgraphescape#1{% + \expandafter\let\expandafter\next\csname graph !#1\endcsname + \ifx\next\relax\else \expandafter\let\csname G!#1\endcsname=\undefined + \xywarning@{Redefining graph <escape> !#1}\fi + \expandafter\gdef\csname graph !#1\endcsname{% + \expandafter\let\expandafter\next\csname G!#1\endcsname + \expandafter\xyFN@\expandafter\NODE@\next}% + \DN@{\newgraphescape@{#1}}\xyFN@\next@} + +\xydef@\newgraphescape@#1{% + \ifx [\next %] + \ifx\newcommand\undefined \xyerror@{[n] only with LaTeX}% + \else + \def\nextiv@{\expandafter\newcommand\expandafter{\csname G!#1\endcsname}}\fi + \else \def\nextiv@{\expandafter\gdef\csname G!#1\endcsname}\fi \nextiv@} + +\xydef@\rungraphescape@#1{% + \expandafter\let\expandafter\next\csname graph !#1\endcsname + \ifx\next\relax \xyerror@{Undefined graph <escape> !#1}\fi \next} +\DOCMODE) + +%\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +%\note??=[use <prefix>] +%% +% This will setup a <prefix> such that all the entries of the graph +% will get that prefix. + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\end{notes} + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + The final exercise illustrates much of the above. + +\begin{exercise} +% + Typeset +% +\begin{displaymath} +\begin{code} +\SelectTips{cm}{} +\objectmargin={1pt} +\xygraph{ !{0;(.77,-.77):0} + !~:{@{-}|@{>}} + w (:[r(.6)]{x_1} + ,:[d]z:[r]y:[u(.6)]{x_2}:"x_1":"z" + :@( {"w";"z"}, {"y";"z"})"z":"x_2") } +\end{code} +\docode +\end{displaymath} +% +\answercode +\answertext{The author did\displaycode It also shows that one \emph{can} use + |{}|s inside delimited arguments \emph{provided} one adds a space to + avoid the |{}|s being shaved off!} +\end{exercise} + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection*{End \& log} + +\DOCMODE( +\xyendinput + +% $Log: xygraph.doc,v $ +% Revision 3.7 1999/02/16 15:12:50 krisrose +% Interim release (Y&Y fonts now free). +% +% Revision 3.6 1998/03/06 01:28:05 krisrose +% Releasing (with Y&Y fonts). +% +% Revision 3.4 1997/05/18 01:14:25 krisrose +% Essential bugfixes. +% +% Revision 3.3 1996/12/19 03:31:56 krisrose +% Maintenance release +% +% Revision 3.2 1995/09/19 18:22:27 kris +% Bug fix release. +% +% Revision 3.1 1995/09/05 20:31:32 kris +% Releasing! +% +% Revision 3.0 1995/07/07 20:14:21 kris +% Major release w/new User's Guide! +% +% Revision 2.13 1995/07/04 15:11:17 kris +% Ready to release v3? +% +% Revision 2.12 1994/10/25 11:34:25 kris +% Interim release just before v3 [works with AMS-LaTeX 1.2]... +% +% Revision 2.11 1994/07/05 10:37:32 kris +% Third 3beta release [bug fixes]. +% Experimental graph feature included (for ECCT-94 presentation). +% +% New for v3... +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% Tell Emacs how we are formatted: +% Local Variables: +% mode:latex +% fill-prefix:"\t" +% fill-column:77 +% paragraph-separate:"^[ \t\f]*$\\|^[^\t]\\|\\\\\\\\\\|\\$\\$\\|[^\n\\\\][%&]" +% paragraph-start:"^[ \t\f]*$\\|^[^\t]\\|\\\\\\\\\\|\\$\\$\\|[^\n\\\\][%&]" +% LaTeX-indent-level:1 +% TeX-brace-indent-level:1 +% End: |