summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/xypic/xyarrow.doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/generic/xypic/xyarrow.doc')
-rw-r--r--Master/texmf-dist/source/generic/xypic/xyarrow.doc1881
1 files changed, 1881 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/xypic/xyarrow.doc b/Master/texmf-dist/source/generic/xypic/xyarrow.doc
new file mode 100644
index 00000000000..203c877c451
--- /dev/null
+++ b/Master/texmf-dist/source/generic/xypic/xyarrow.doc
@@ -0,0 +1,1881 @@
+%% $Id: xyarrow.doc,v 3.5 1997/05/28 13:05:01 krisrose Exp $
+%%
+%% Xy-pic ``Arrows and Paths'' feature.
+%% Copyright (c) 1991-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{arrow}{Arrow and Path feature}{\stripRCS$Revision: 3.5 $}%
+ {Kristoffer H.~Rose}{krisrose@brics.dk}%
+ {BRICS/Computer Science, University of Aarhus, Ny Munkegade, building 540,
+ DK--8000 Aarhus~C}
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ This feature provides \Xy-pic with the arrow paradigm presented
+ in~\cite{R92:HowTPDAT}.
+
+ \NOTE: |\PATH| command incompatibly changed for version 3.3 (the
+ |\ar| command is unaffected).
+
+ The basic concept introduced is the "path": a connection that
+ "starts" from $c$ (the current object), "ends" at a specified object,
+ and may be split into several "segments" between intermediate
+ specified objects that can be individually labelled, change style,
+ have breaks, etc.
+
+ \S??[path] is about the |\PATH| primitive, including the syntax of
+ paths, and \S??[arrow] is about the |\ar| customisation of paths to
+ draw arrows using \Xy-pic directional objects.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph*{Header:}\leavevmode
+\DOCHEADER
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\subsection{Paths}
+??=[path]
+
+\DOCMODE(
+\message{path,}
+\DOCMODE)
+
+ The fundamental commands of this feature are ??c![\PATH] and
+ ??c![\afterPATH] that will parse the <path> according to the grammar
+ in figure~??[f.path] with notes below.
+
+\begin{figure*}[tb]
+\begin{syntax}
+%
+ \multispan{3}{{\tt\string\PATH} <path>\hfil}
+ & interpret <path>
+\cr
+%
+ \multispan{3}{{\tt\string\afterPATH\string{<decor>\string}} <path>\hfil}
+ & interpret <path> and then run <decor>
+\cr
+\noalign{\nobreak\smallskip\nobreak\hrule\nobreak\smallskip\nobreak}
+%
+ <path>
+ &\iss & ??c![~] <action> |{| <stuff> |}| <path>
+ & set ??!^[<action>] to <stuff>
+\cr
+ &\orr & ??c![~] <which> |{| <labels> |}| <path>
+ & add ??!^[<labels> prefix for some segments]
+\cr
+ &\orr & ??c![~] |{| <stuff> |}| <path>
+ & set ??!^[failure continuation] to <stuff>
+\cr
+ &\orr & ??c!['] <segment> <path>
+ & make ??!^[straight segment]
+\cr
+ &\orr & ??c![`] <turn> <segment> <path>
+ & make ??!^[turning segment]
+\cr
+ &\orr & <segment>
+ & make ??!^[last segment]
+\cr
+\noalign{\smallskip}
+%
+ <turn>
+ &\iss & <diag> <turnradius>
+ & ??!^[1/4 turn] starting in <diag>
+\cr
+ &\orr & <cir> <turnradius>
+ & ??!^[explicit turn]
+\cr
+%
+ <turnradius>
+ &\iss & <empty>
+ & use default turn radius
+\cr
+ &\orr & ??c![/] <dimen>
+ & set "turnradius" to <dimen>
+\cr
+\noalign{\smallskip}
+%
+ <segment>
+ &\iss & <path-pos> <slide> <labels>
+ & ??!^[segment] with <slide> and <labels>
+\cr
+\noalign{\smallskip}
+%
+ <slide>
+ &\iss & <empty> \orr\ ??c![<] <dimen> ??c![>]
+ & optional ??!^[slide]: <dimen> in the ``above'' direction
+\cr
+\noalign{\smallskip}
+%
+ <labels>
+ &\iss & ??c![^] <anchor> <it> <alias> <labels>
+ & ??!^[label with <it>] "above" <anchor>
+\cr
+ &\orr & ??c![_] <anchor> <it> <alias> <labels>
+ & ??!^[label with <it>] "below" <anchor>
+\cr
+ &\orr & ??c![|] <anchor> <it> <alias> <labels>
+ & ??!^[break with <it>] at <anchor>
+\cr
+ &\orr & <empty>
+ & no more labels
+\cr
+\noalign{\smallskip}
+%
+ <anchor>
+ &\iss & ??c![-] <anchor> \orr\ <place>
+ & label/break placed relative to the <place> where ??c![-] is a synonym
+ for ??c![<>(.5)]
+\cr
+\noalign{\smallskip}
+%
+ <it>
+ &\iss & <digit>\orr<letter>\orr|{|<text>|}|\orr<cs>
+ & <it> is a ??!^[default label]
+\cr
+ &\orr & ??c![*] <object>
+ & <it> is an <object>
+\cr
+ &\orr & ??c![@] <dir>
+ & <it> is a <dir>ectional
+\cr
+ &\orr & |[| <shape> |]| <it>
+ & use |[|<shape>|]| for <it>
+\cr
+\noalign{\smallskip}
+%
+ <alias>
+ &\iss & <empty> \orr\ ??c![=]|"|<id>|"|
+ & optional ??!^[name for label object]
+\cr
+\end{syntax}
+\caption{\protect<path>s}
+??=[f.path]
+\end{figure*}
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\paragraph*{Parsing:}
+
+ |\afterPATH| sets up |\afterPATH@| and initialise all the actions
+ (see note~??[<action>] below) before invoking the actual <path>
+ parser. |\PATH| is just a dummy interface.
+
+\DOCMODE(
+\xydef@\PATH{\afterPATH{}}
+
+\xylet@\afterPATH@=\empty
+
+\xydef@\afterPATH#1{\save
+ \DN@##1{\def\afterPATH@{\restore \def\afterPATH@{##1}#1}}%
+ \expandafter\next@\expandafter{\afterPATH@}%
+ \let\PATHfail@@=\empty
+ \let\PATHbefore@@=\empty
+ \let\PATHafter@@=\empty
+ \let\PATHlabelsevery@@=\empty
+ \let\PATHlabelsnext@@=\empty
+ \let\PATHlabelslast@@=\empty
+ \xy@{\afterPATH{#1}}{\def\PATHslide@@{\z@}}%
+ \def\PATHcontinue@@{\xyFN@\PATH@}%
+ \xyFN@\PATH@}
+\DOCMODE)
+
+ |\PATH@| is the parser for <path>: it eats the <path> until it fails
+ and then calls the `failure continuation' which will eventually
+ become |\empty| which ends the parsing. \HACK: The
+ `|\ifPATHsingle@|' switch switches the <segment> parsing "off"; this
+ is used by the graph feature to parse stand-alone <slide> <labels>
+ sequences.
+
+\DOCMODE(
+\xynew@{if}\ifPATHsingle@
+
+\xydef@\PATH@{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\PATH@}%
+ \else\ifPATHsingle@ \let\next@=\PATH@single
+ \else \let\next@=\PATH@normal \fi\fi \next@}
+
+\xydef@\PATH@normal{%
+ \ifx ~\next \DN@ ~{\xyFN@\PATHsetting@}%
+ \else \addRQ@\ifx \next \addRQ@\DN@{\xy@'{}\xyFN@\PATHstraight@}%
+ \else \addLQ@\ifx \next \addLQ@\DN@{\xy@`{}\xyFN@\PATHturn@}%
+ \else\ifx \PATHfail@@\PATH@x \DN@{\xyFN@\PATHfinal@}%
+ \else
+ \DNii@{\let\PATHfail@@=\PATH@x \xyFN@\PATH@}%
+ \DN@{\expandafter\nextii@\PATHfail@@}%
+ \fi\fi\fi\fi \next@}
+\DOCMODE)
+
+ |\PATHsetting@| just reads an <action> or <which> determining which
+ action stuff to set and then does it---we treat the failure
+ continuation as an action here even though it is not, strictly
+ speaking. The four actions are explained in the appropriate notes
+ below.
+
+\DOCMODE(
+\xylet@\PATHfail@@=\empty
+
+\xylet@\PATHbefore@@=\empty
+\xylet@\PATHafter@@=\empty
+
+\xylet@\PATHlabelsevery@@=\empty
+\xylet@\PATHlabelsnext@@=\empty
+\xylet@\PATHlabelslast@@=\empty
+
+\xydef@\PATHsetting@{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\PATHsetting@}%
+ \else\ifx \bgroup\next
+ \DN@##1{\xy@{~{##1}}{}\def\PATHfail@@{##1}\xyFN@\PATH@}%
+ \else \addEQ@\ifx \next
+ \addEQ@\DN@##1{\xy@{~={##1}}{}\def\PATHbefore@@{##1}\xyFN@\PATH@}%
+ \else \addLT@\ifx \next
+ \addLT@\DN@##1{\xy@{~<{##1}}{}\def\PATHlabelsnext@@{##1}\xyFN@\PATH@}%
+ \else \addGT@\ifx \next
+ \addGT@\DN@##1{\xy@{~>{##1}}{}\def\PATHlabelslast@@{##1}\xyFN@\PATH@}%
+ \else \addPLUS@\ifx \next
+ \addPLUS@\DN@##1{\xy@{~+{##1}}{}\def\PATHlabelsevery@@{##1}\xyFN@\PATH@}%
+ \else \ifx /\next
+ \DN@/##1{\xy@{~/{##1}}{}\def\PATHafter@@{##1}\xyFN@\PATH@}%
+ \else \addDASH@\ifx \next
+ \xywarning@{Obsolete `-' PATH <action> translated to `='.}%
+ \addDASH@\DN@##1{\xy@{~-{##1}}{}\def\PATHbefore@@{##1}\xyFN@\PATH@}%
+ \else
+ \xyerror@{Unknown \string~ setting: \meaning\next}%
+ {See the Xy-pic arrow feature documentation for help.}%
+ \fi\fi\fi\fi\fi\fi\fi\fi \next@}
+\DOCMODE)
+
+ Next the setup for straight segments including the last: they set
+ |\PATHinit@@| to initialise, \ie, slide, |\PATHextra@@| to do what is
+ needed after the ??c![=] action, and finally |\PATHpost@@| is set to
+ any operations to be done after the entire segment is typeset but
+ before the next is read. |\PATHcontinue@@| is used internally to
+ distinguish the ordinary segments from the last.
+
+\DOCMODE(
+\xylet@\PATHinit@@=\empty
+
+\xylet@\PATHextra@@=\empty
+\xylet@\PATHpost@@=\empty
+\xylet@\PATHcontinue@@=\empty
+
+\xydef@\PATHstraight@{%
+ \def\PATHinit@@{\PATHinitstraight@}%
+ \let\PATHextra@@=\empty
+ \let\PATHpost@@=\empty
+ \let\PATHlabelsextra@@=\relax
+ \xy@@\pfromc@ \PATHafterPOS{\xyFN@\PATHsegment@}}
+
+\xydef@\PATHfinal@{%
+ \def\PATHinit@@{\PATHinitstraight@}%
+ \def\PATHextra@@{\let\PATHcontinue@@=\afterPATH@}%
+ \let\PATHpost@@=\empty
+ \let\PATHlabelsextra@@=\PATHlabelsextralast@
+ \xy@@\pfromc@ \PATHafterPOS{\xyFN@\PATHsegment@}}
+
+\xydef@\PATHlabelsextralast@{\let\PATHlabelsextra@@=\relax
+ \expandafter\xyFN@\expandafter\PATHlabels@\PATHlabelslast@@}
+
+\xydef@\PATHinitstraight@{\xy@@{\setupDirection@ \dimen@=\PATHslide@@
+ \dimen@ii=-\sinDirection\dimen@
+ \ifPATHomitslide@@\else\advance\X@p\dimen@ii\fi \advance\X@c\dimen@ii
+ \dimen@ii= \cosDirection\dimen@
+ \ifPATHomitslide@@\else\advance\Y@p\dimen@ii\fi \advance\Y@c\dimen@ii
+ \PATHomitslide@@false \resetupDirection@}}
+\DOCMODE)
+
+ Setup for turning segments is in note~??[turning segment].
+
+ A <segment> is interpreted as follows after $p$ has been set to the
+ previous end object, $c$ to the <pos> given at the start of the
+ segment, and |\PATHslide@@| to the slide:
+
+\DOCMODE(
+\xydef@\PATHslide@@{\z@}
+\xynew@{if}\ifPATHomitslide@@
+
+\xydef@\PATHsegment@{%
+ \addLT@\ifx\next
+ \addGT@{\addLT@\DN@##1}{%
+ \xy@{<##1>}{\dimen@=##1\relax \edef\PATHslide@@{\the\dimen@}}%
+ \xyFN@\PATHsegment@@}%
+ \else \let\next@=\PATHsegment@@
+ \fi \next@}
+\DOCMODE)
+
+\begin{enumerate}
+\item
+ Expand |\PATHinit@@| (for straight segments this just sets up the
+ direction and applies the <slide>).
+\item
+ Expand |\PATHaction={|<stuff>|}| as set using |~={|<stuff>|}|.
+\item
+ Sets |\PATHcontinue@@| to any continuation set with |~{|<stuff>|}|).
+\item
+ Construct list of <labels> specified by the user through |~|<which>
+ setup. Those applicable to the present segment are inserted before
+ the user's <labels> in the sequence |<>=|.
+\item
+ Store $p,c$ as "start","end" of segment.
+\item
+ Interpret <labels> (see below), including the ones added by the
+ |~|<when>\dots\ <setup>.
+\end{enumerate}
+%
+ |\PATHsegment@@| performs this except the last two points:
+
+\DOCMODE(
+\xydef@\PATHsegment@@{\PATHinit@@ \addEQ@\PATHaction@\PATHbefore@@ \PATHextra@@
+ \expandafter\toks@\expandafter{\PATHlabelsnext@@}\let\PATHlabelsnext@@=\empty
+ \expandafter\addtotoks@\expandafter{\PATHlabelsevery@@}%
+ \expandafter\def\expandafter\PATHlabels@@\expandafter{\the\toks@}%
+ \toks@={}\expandafter\xyFN@\expandafter\PATHlabels@\PATHlabels@@}
+\DOCMODE)
+
+ |\PATHlabels@| parses all <labels> of a <segment>. This sets
+ |\PATHlabelit@@| to the operation building the label in question.
+ Then some parsing stores the tokens ??c![<>(.5)] for each ??c![-] in
+ the <anchor> and finally passes control to the kernel <place> parser
+ with these tokens as the head. This then in turn calls |\PATHit@|
+ that parses <it> and applies the chosen operation. After the last we
+ continue with the accumulated subsegment actions.
+
+\DOCMODE(
+\xylet@\PATHlabelit@@=\empty
+
+\xydef@\PATHlabels@{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\PATHlabels@}%
+ \else \ifx ^\next
+ \DN@##1{\xy@^{}\let\PATHlabelit@@=\PATHlabelabove@@
+ \DNii@{}\xyFN@\PATHanchor@}%
+ \else \ifx _\next
+ \DN@##1{\xy@_{}\let\PATHlabelit@@=\PATHlabelbelow@@
+ \DNii@{}\xyFN@\PATHanchor@}%
+ \else \ifx |\next
+ \DN@##1{\xy@|{}\let\PATHlabelit@@=\PATHlabelbreak@
+ \DNii@{}\xyFN@\PATHanchor@}%
+ \else \let\next@=\PATHfinishsegments@ \fi\fi\fi\fi \next@}
+
+\xydef@\PATHanchor@{\begingroup \toks@={}\PATHanchor@i}
+
+\xydef@\PATHanchor@i{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\PATHanchor@i}%
+ \else\addDASH@\ifx \next
+ \addDASH@\DN@{\expandafter\addtotoks@\expandafter{\PATHanchor@toks}%
+ \xyFN@\PATHanchor@i}%
+ \else
+ \DNii@##1{\endgroup\afterPLACE{\xyFN@\PATHit@}##1}%
+ \DN@{\expandafter\nextii@\expandafter{\the\toks@}}%
+ \fi\fi \next@}
+
+{\xyuncatcodes \gdef\next{<>(.5)}}
+\xylet@\PATHanchor@toks=\next
+
+\xylet@\PATHitshapes@@=\empty
+
+\xydef@\PATHit@{\let\PATHitshape@@=\empty \xyFN@\PATHit@i}
+
+\xydef@\PATHit@i{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\PATHit@i}%
+ \else \ifx *\next \DN@*##1##{\PATHlabelit@@{!C##1}}%
+ \else \addAT@\ifx\next \addAT@\DN@##1##{\PATHlabelit@@{\dir##1}}%
+ \else \ifx [\next \DN@[##1]{%
+ \expandafter\def\expandafter\PATHitshape@@\expandafter{\PATHitshape@@[##1]}%
+ \xyFN@\PATHit@i}%
+ \else \DN@{\PATHlabelit@@{}}%
+ \fi\fi\fi\fi \next@}
+\DOCMODE)
+
+ The individual operations bound to |\PATHlabelit@@| are discussed as
+ appropriate in the notes.
+
+ After the last break and label we typeset the last piece of the
+ connection.
+
+\DOCMODE(
+\xydef@\PATHfinishsegments@{%
+ \ifx\PATHlabelsextra@@\relax \expandafter\PATHfinishsegments@i
+ \else
+ \expandafter\PATHlabelsextra@@ \fi}
+
+\xydef@\PATHfinishsegments@i{%
+ \xy@@{\Clast@@}\the\toks@ \toks@={}%
+ \xy@@\setupDirection@
+ \PATHpost@@ \PATHaction@/\PATHafter@@
+ \PATHcontinue@@}
+\DOCMODE)
+
+ \BUG: The order of the breaks determines the order of the
+ subsegments. This is maybe a feature.
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{notes}
+
+\note??=[<action>]
+%
+ An <action> can be either of the characters |=/|. The associated
+ <stuff> is saved and used to call
+$$
+ ??c![\PATHaction]<action>|{|<stuff>|}|
+$$
+ "before" and "after" each segment (including all <labels>) for
+ ??c![=] and ??c![/], respectively.
+
+ The default ??c![\PATHaction] macro just expands to ``??c![\POS]
+ <stuff> |\relax|'' thus <stuff> should be of the form <pos> <decor>.
+ The user can redefine this---in fact the ??c![\ar] command described
+ in \S??[arrow] below is little more than a special ??c![\PATHaction]
+ command and a clever defaulting mechanism.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ Here is the default ??c![\PATHaction]:
+
+\DOCMODE(
+\xydef@\PATHaction@default#1#2{\xy@{PATHaction#1{#2}}{}\POS#2\relax}
+\xylet@\PATHaction=\PATHaction@default
+\DOCMODE)
+
+ It is called using |\PATHaction@| to expand the action control
+ sequences back to their <stuff> first:
+
+\DOCMODE(
+\xydef@\PATHaction@#1#2{\expandafter\PATHaction\expandafter#1\expandafter{#2}}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[<labels> prefix for some segments]
+%
+ It is possible to include a number of default <labels> "before" the
+ <labels> of the actual <segment> are interpreted, using
+ |~|<which>|{|<labels>|}|. The specified <which> determines for which
+ segments the indicated <labels> should be prefixed as follows:
+$$
+\begin{tabular}{\otherbar c\otherbar l\otherbar}
+\hline
+ <which> & applied to\dots \\
+\hline
+ ??c![<] & next segment only \\
+ ??c![>] & last segment only \\
+ ??c![=] & every segment \\
+\hline
+\end{tabular}
+$$
+ (when several apply to the same segment they are inserted in the
+ sequence |<>+|).
+
+ This is useful to draw connections with a `center marker' in
+ particular with arrows, \eg, the `mapsto' example explained below can
+ be changed into a `breakto' example: typing
+%
+\begin{code}
+\xy*+{0}\PATH
+ ~={**\dir{-}}
+ ~>{|>*\dir{>}}
+ ~+{|*\dir{/}}
+ '(10,1)*+{1} '(20,-2)*+{2} (30,0)*+{3}
+\endxy
+\end{code}
+\displaycode
+\noindent\unskip
+%
+ will typeset
+$$
+ \docode
+$$
+ Note, however, that what goes into |~+{|\dots|}| is <labels> and thus
+ not a <pos> -- it is not an action in the sense explained above.
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[failure continuation]
+%
+ Specifying |~{|<stuff>|}| will set the ``failure continuation'' to
+ <stuff>. This will be inserted when the last <segment> is
+ expected---it can even replace it or add more <segment>s, \ie,
+%
+\begin{code}
+\xy *+{0} \PATH ~={**\dir{-}}
+ ~{'(20,-2)*+{2} (30,0)*+{3}} '(10,1)*+{1}
+\endxy
+\end{code}
+\displaycode
+%
+ is equivalent to
+%
+\begin{code}
+\xy *+{0} \PATH ~={**\dir{-}}
+ '(10,1)*+{1} '(20,-2)*+{2} (30,0)*+{3}
+\endxy
+\end{code}
+\displaycode
+%
+ typesetting
+$$
+ \docode
+$$
+ because when |\endxy| is seen then the parser knows that the next
+ symbol is neither of the characters |~'`| and hence that the last
+ <segment> is to be expected. Instead, however, the failure
+ continuation is inserted and parsed, and the <path> is finished by
+ the inserted material.
+
+ Failure continuations can be nested:
+%
+\begin{code}
+\xy *+{0} \PATH ~={**\dir{-}}
+ ~{~{(30,0)*+{3}}
+ '(20,-2)*+{2}} '(10,1)*+{1}
+\endxy
+\end{code}
+\displaycode
+%
+ will also typeset the connected digits.
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[straight segment]
+%
+ A ``straight segment'' is interpreted as follows:
+%
+\begin{enumerate}
+\item
+ First $p$ is set to the end object of the previous segment (for the
+ first segment this is $c$ just before the path command) and $c$ is
+ set to the <pos> starting the <segment>, and the current <slide> is
+ applied.
+\item
+ Then the |=| and |<| "segment actions" are expanded (in that
+ sequence) and the |<| action is cleared. The resulting $p$ and $c$
+ become the "start" and "end" object of the segment.
+\item
+ Then all <labels> (starting with the ones defined as described in
+ note~??[<labels> prefix for some segments] below).
+\end{enumerate}
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ The code expanding the actions is part of the parsing above.
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[segment]
+%
+ A "segment" is a part of a <path> between a previous and a new
+ "target" given as a <path-pos>: normally this is just a <pos> as
+ described in~\S??g[xy.doc:pos] but it can be changed to something
+ else by changing the control sequence ??c![\PATHafterPOS] to be
+ something other than ??c![\afterPOS].
+
+\DOCMODE(
+\xylet@\PATHafterPOS@default=\afterPOS
+\xylet@\PATHafterPOS=\PATHafterPOS@default
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[turning segment]??=[1/4 turn]??=[explicit turn]
+%
+ A "turning" segment is one that does not go all the way to the given
+ <pos> but only as far as required to make a turn towards it. The $c$
+ is set to the actual turn object after a turning segment such that
+ subsequent turning or other segments will start from there, in
+ particular the last segment (which is always straight) can be used to
+ finish a winding line.
+
+ What the turn looks like is determined by the <turn> form:
+%
+\begin{description}
+
+\item[<empty>]
+ Nothing between the ??c![`] and the <pos> is interpreted the same as
+ giving just the <diag> last used "out" of a turn.
+
+\item[<diag>]
+ Specifying a single <diag> $d$ is the same as specifying either of
+ the <cir>cles $d$??c![^] or $d$??c![_], depending on whether the specified
+ <pos> has its center `above' or `below' the line from $p$ in the
+ <diag>onal direction.
+
+\item[<cir>]
+ When a full explicit <cir>cle is available then the corresponding
+ <cir>cle object is placed such that its ingoing direction is a
+ continuation of a straight connection from $p$ and the outgoing
+ direction points such that a following straight (or last) segment
+ will connect it to $c$ (with the same slide).
+
+\end{description}
+%
+ Here is an example using all forms of <turn>s:
+%
+\begin{code}
+\xy <4pc,0pc>:(0,0)
+ *+\txt{base}="base"
+ \PATH ~={**\dir{-}?>*\dir{>}}
+ `l (-1,-1)*{A} ^a
+ ` (1,-1)*{B} ^b
+ `_ul (1, 0)*{C} ^c
+ `ul^l "base" ^d
+ "base" ^e
+\endxy
+\end{code}
+$$
+\docode
+$$
+ was typeset by
+%
+\displaycode
+
+ \BUG: Turns are only really resonable for paths that use straight
+ lines like the one above.
+
+ \NOTE: Always write a valid <pos> after a <turn>, otherwise any
+ following ??c![^] or ??c![_] labels can confuse the parser. So if
+ you intend the |^r| in |`^r| to be a label then write |`,^r|, using a
+ dummy ??c![,] <pos>ition.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ We need to keep track of the current "in" and "out" <diag>
+ directions as well as the current radius.
+
+\DOCMODE(
+\xydef@\PATHlastout@@{3}
+\DOCMODE)
+
+ The startup routine is just a selection of the two kinds of <turn>:
+
+\DOCMODE(
+\xydef@\PATHturn@{\afterCIRorDIAG\PATHturn@cir\PATHturn@diag}
+\DOCMODE)
+
+ In both cases the trick is to set up a |\PATHinit@@| method that
+ typesets the right circle segment at the right location. The
+ simplest one is when there is a full <cir> available because that
+ should just be used directly. The only complication is that we
+ forbid $180^\circ$ turns:
+
+\DOCMODE(
+\xydef@\PATHturn@cir{\toks@={\xy@@{%
+ \count@=\CIRin@@ \ifnum\count@<4\else\advance\count@-4\fi
+ \count@@=\CIRout@@ \ifnum\count@@<4\else\advance\count@@-4\fi
+ \ifnum\count@=\count@@ \xyerror@{<turn> cannot be half or full}{%
+You asked for a <turn>ed segment with parallel in- and out-direction.^^J%
+This is not allowed because it is not possible to position it uniquely.}\fi}}%
+ \edef\next@{{\CIRin@@}{\expandafter\noexpand\CIRorient@@}{\CIRout@@}}%
+ \expandafter\PATHturn@i\next@}
+\DOCMODE)
+
+ "Procedure for <diag> turns": Builds initial part of |\PATHinit@@|
+ that computes the missing "orient" and "out" from "in" and the $c$
+ passed through the segment. This initial segment should set
+ "orient" as follows:
+$$
+ \xy <9mm,0mm>: <0mm,4mm>::
+ ,(1,1) *+\dir{*}!D *!LU{p}
+ ,(0,0);(4,4)**\dir{-}
+ ?< *!/+\jot/\composite{{.}*!/+\jot/{.}*!/+2\jot/{.}}
+ ?> *!/-\jot/\composite{{.}*!/-\jot/{.}*!/-2\jot/{.}}
+ ?(.6)*!/1ex/\dir{>} *^!/-1ex/{|^|} *_!/-1ex/{|_|}
+ \endxy
+$$
+ \ie, as the sign of the inner product $\vec{pc} \cdot \hat{"in"}$,
+ and set "out" as for the <cir>cle "in" "orient".
+
+\DOCMODE(
+\xydef@\PATHturn@diag{\toks@={\xy@@{%
+ \setupDirection@ \count@=\CIRin@@ \dimen@=\xydashl@ \ABfromdiag@
+ \ifdim \sinDirection\A@>\cosDirection\B@ \def\CIRorient@@{\CIRacw@}%
+ \advance\count@\ifnum\count@<6 \tw@ \else -6\fi
+ \else \def\CIRorient@@{\CIRcw@}%
+ \advance\count@\ifnum\count@>\@ne -\tw@ \else 6\fi
+ \fi
+ \edef\CIRout@@{\the\count@}}}%
+ \edef\next@{{\CIRin@@}{}{}}%
+ \expandafter\PATHturn@i\next@}
+\DOCMODE)
+
+ |\PATHturn@i| is where |\PATHinit@@| is defined to do the following:
+%
+\begin{itemize}
+
+\item[{??_[turni1]}]
+ Setup the default "in", "orient", and "out" as defined by the call
+ from the above macros. Set "radius" parameter to the current
+ "turnradius" value. The commands in |\toks@| are run to do any
+ last-minute fixing of the defaults.
+
+\item[{??_[turni2]}]
+ The segment will leave $p$ in direction "in" and pretend to be
+ meeting $c$ in direction "out". Thus the center of the <cir>cle
+ object to be used for the actual <turn> object is located at the
+ intersection of the line through $p+"radius"\hat{v}_"in"$ in
+ direction $\vec{v}_"in"$ and the line through
+ $c+"radius"\hat{v}_"out"$ in direction $\vec{v}_"out"$. Here we
+ compute $p+R\hat{v}_"in"$ using $R="radius"$ if this is the initial
+ turn and $R="radius"\pm"slide"$ if it is a continuation turn.
+
+\item[{??_[turni2b]}]
+ Save $p$ and "base" for later.
+
+\item[{??_[turni3]}]
+ Compute $c+"radius"\hat{v}_"out"$ and use the kernel |\intersect@|
+ primitive to compute the turn circle segment center.
+
+\item[{??_[turni3b]}]
+ However, if the intersection point lies on the `wrong side' of $p$,
+ \ie, if $\vec{pc} \cdot "in"$ is negative, then we should not use the
+ intersection point but the point as close to $p$ as possible because
+ the connection from $p$ to the turn should at least have zero
+ length---in fact we set it to have 8sp length to make sure that a
+ sugsegment is typeset!
+
+\item[{??_[turni4]}]
+ Modify "radius" to use for the actual circle segment by the "slide":
+ either positively (for "orient" ??c![_]) or negatively (for "orient"
+ ??c![^]), and drop the circle segment (bypassing |\cir| to use the
+ internal settings from above).
+
+\item[{??_[turni5]}]
+ Store in |\PATHpostpos@@| the true end of the circle segment and code
+ to prevent the application of the "slide" for the start of the next
+ <segment>.
+
+\item[{??_[turni6]}]
+ Move $c$ to true beginning of the circle segment.
+
+\item[{??_[turni7]}]
+ Restore saved $p$ and "base", and slide $p$ finally.
+
+\end{itemize}
+
+\DOCMODE(
+\xylet@\PATHpostpos@@=\empty
+
+\xydef@\PATHturn@i#1#2#3{%
+ \DN@##1{\def\PATHinit@@{\xy@@{%
+ \def\CIRin@@{#1}\def\CIRorient@@{#2}\def\CIRout@@{#3}%?*[turni1]
+ \ifnum\CIRin@@=8 \let\CIRin@@=\PATHlastout@@ \fi
+ \R@=\turnradius@
+ ##1\relax}%
+ \xy@@{\count@=\CIRin@@ %?*[turni2]
+ \ifPATHomitslide@@ \dimen@=-\PATHslide@@
+ \ABfromdiag@ \advance\X@p-\B@ \advance\Y@p\A@ \fi
+ \enter@{\pfromthep@ \basefromthebase@}}%?*[turni2b]
+ \xy@@{\dimen@=\expandafter\ifx\CIRorient@@\CIRcw@-\fi\R@
+ \ABfromdiag@ \advance\X@p-\B@ \advance\Y@p\A@
+ \X@origin=\X@p \Y@origin=\Y@p}%?*[turni3]
+ \xy@@{\dimen@=\xydashl@ \ABfromdiag@ \R@c=\A@ \U@c=\B@
+ \count@=\CIRout@@
+ \dimen@=\expandafter\ifx\CIRorient@@\CIRcw@-\fi\R@
+ \ABfromdiag@ \advance\X@c-\B@ \advance\Y@c\A@
+ \dimen@=\xydashl@ \X@p=\X@c \Y@p=\Y@c
+ \ABfromdiag@ \advance\X@p-\A@ \advance\Y@p-\B@
+ \intersect@
+ \count@=\CIRin@@ \dimen@=\p@ \ABfromdiag@}%?*[turni3b]
+ \xy@@{\edef\next@{\expandafter\removePT@\the\A@}%
+ \edef\nextii@{\expandafter\removePT@\the\B@}%
+ \A@=\X@c \advance\A@-\X@origin \B@=\Y@c \advance\B@-\Y@origin
+ \ifdim \next@\A@<-\nextii@\B@
+ \dontleave@ \cfromp@
+ \count@=\CIRin@@ \advance\count@\ifnum\count@<4 +4\else -4\fi
+ \dimen@=\xydashl@ \Directionfromdiag@
+ \the\Edge@c\z@
+ \count@=\CIRin@@ \dimen@=\expandafter\ifx\CIRorient@@\CIRcw@-\fi\R@
+ \ABfromdiag@ \advance\X@c-\B@ \advance\Y@c\A@
+ \dimen@=5sp \ABfromdiag@ \advance\X@c\A@ \advance\Y@c\B@
+ \fi
+ \dimen@ii=\expandafter\ifx\CIRorient@@\CIRacw@-\fi\PATHslide@@ %?*[turni4]
+ \advance\R@\dimen@ii
+ \drop@\literal@{\hbox\bgroup\cir@i}}%
+ \xy@@{\X@p=\X@c \Y@p=\Y@c %?*[turni5]
+ \count@=\CIRout@@
+ \dimen@=\expandafter\ifx\CIRorient@@\CIRacw@-\fi\R@c
+ \ABfromdiag@ \advance\X@p-\B@ \advance\Y@p\A@
+ \edef\PATHpostpos@@{\X@c=\the\X@p \Y@c=\the\Y@p \noexpand\czeroEdge@
+ \noexpand\PATHomitslide@@true}}%
+ \xy@@{\count@=\CIRin@@ %?*[turni6]
+ \dimen@=\expandafter\ifx\CIRorient@@\CIRacw@-\fi\R@c
+ \ABfromdiag@ \advance\X@c-\B@ \advance\Y@c\A@ \czeroEdge@}%
+ \xy@@{\leave@ %?*[turni7]
+ \count@=\CIRin@@ \dimen@=\PATHslide@@
+ \ABfromdiag@ \advance\X@p-\B@ \advance\Y@p\A@
+ \edef\PATHlastout@@{\CIRout@@}%
+ \count@=\CIRout@@ \dimen@=\xydashl@ \Directionfromdiag@}}}%
+ \expandafter\next@\expandafter{\the\toks@}\toks@={}%
+ \let\PATHextra@@=\empty
+ \def\PATHpost@@{\xy@@\PATHpostpos@@}%
+ \let\PATHlabelsextra@@=\relax
+ \xyFN@\PATHturn@ii}
+\DOCMODE)
+
+ The final macro takes care of the v2.6 format for changing
+ "turnradius": using ??c![/]<dimen> right after the <turn>.
+
+\DOCMODE(
+\xydef@\PATHturn@ii{%
+ \ifx /\next
+ \DN@ /{\afterassignment\nextii@\dimen@=}%
+ \DNii@{%
+ \edef\next@{\noexpand\xy@@{\edef\noexpand\turnradius@{\the\dimen@}}}\next@
+ \xy@@\pfromc@ \PATHafterPOS{\xyFN@\PATHsegment@}}%
+ \else \DN@{\xy@@\pfromc@ \PATHafterPOS{\xyFN@\PATHsegment@}}\fi
+ \next@}
+\DOCMODE)
+
+ This just stores a <diag> vector of the specified lenght in
+ $|<|A|,|B|>|$ thus acting as an optimised version of
+ |\Directionfromdiag@|:
+
+\DOCMODE(
+\xydef@\ABfromdiag@{\ifcase\count@\relax
+ \A@=-.7071\dimen@ \B@=-.7071\dimen@ \or \A@=\z@ \B@=-\dimen@
+ \or \A@=+.7071\dimen@ \B@=-.7071\dimen@ \or \A@=\dimen@ \B@=\z@
+ \or \A@=+.7071\dimen@ \B@=+.7071\dimen@ \or \A@=\z@ \B@=+\dimen@
+ \or \A@=-.7071\dimen@ \B@=+.7071\dimen@ \or \A@=-\dimen@ \B@=\z@
+ \else\xybug@{impossible <diag>?}\fi}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ The default used for "turnradius" can be set by the operation
+%
+\begin{defs1}
+ ??c![\turnradius] <add op> |{|<dimen>|}|\cr
+\end{defs1}
+\noindent\unskip
+%
+ that works like the kernel ??c![\objectmargin] etc. commands; it defaults
+ to 10pt.
+
+\DOCMODE(
+\xydef@\turnradius@{10pt}
+
+\xydef@\turnradius{\afterADDOP{\Addop@@\turnradius@}}
+\DOCMODE)
+
+\begin{exercise}
+ Typeset
+\begin{code}
+\xy *+{A}*\cir<10pt>{}="me"
+ \PATH `ul^ur,"me" "me" |>*:(1,-.25)\dir{>}
+\endxy
+\end{code}
+$$\docode$$
+%
+ using <turn>s.
+%
+\answertext{Here is what the author did:??c[\cir]}
+\answercode
+\answertext\displaycode
+\answertext{The trick is getting the arrow head right: the |:| modifier to
+ the explicit {\tt\string\dir} <object> does that.}
+\end{exercise}
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[last segment]
+%
+ The last segment is exactly as a straight one except that the ??c![>]
+ action (if any) is executed (and cleared) just after the ??c![<]
+ action.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ (The code implementing this is merged with the parsing.)
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[slide]
+%
+ ``Sliding'' a segment means moving each of the $p,c$ objects in the
+ direction perpendicular to the current direction at each.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ (The code implementing this is merged with the parsing, using the
+ |\PATHslide@@| control sequence to hold the current slide.)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[label with <it>]
+%
+ Labelling means that <it> is dropped relative to the current segment
+ using a ??c![?] <pos>ition. This thus depends on the user setting up
+ a connection with a ??c![**] <pos> as one of the actions---typically
+ the~??c![=] action is used for this (see note~??[straight segment]
+ for the details). The only difference between ??c![^] and ??c![_] is
+ that they shift the label in the ??c![^] respectively ??c![_]
+ direction; for straight segments it is placed in the ``superscript''
+ or ``subscript'' position.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ The operations used by |\PATHlabels@| to put labels above and below
+ (with ??c![^] and ??c![_]) are trivial, taking two arguments and
+ placing the label immediately; for convenience the |\drop| head are
+ named separately such that they may be redefined:
+
+\DOCMODE(
+\xydef@\PATHlabelabove@#1#2{\droplabel@\belowDirection@{#1}{#2}%
+ \let\afteraliases@@=\empty \xyFN@\PATHlabelalias@}
+
+\xydef@\PATHlabelbelow@#1#2{\droplabel@\aboveDirection@{#1}{#2}%
+ \let\afteraliases@@=\empty \xyFN@\PATHlabelalias@}
+
+\xylet@\PATHlabelabove@@=\PATHlabelabove@
+\xylet@\PATHlabelbelow@@=\PATHlabelbelow@
+
+\xydef@\droplabel@#1#2#3{\xy@@{\enter@\DirectionfromtheDirection@}%
+ \DN@{#2}\ifx\next@\empty
+ \expandafter\xy@@ix@\expandafter{\PATHitshape@@\labelbox{#3}}%
+ \else \expandafter\xy@@ix@\expandafter{\PATHitshape@@#2{#3}}\fi
+ \xy@@{\setbox\z@=\expandafter\object\the\toks9 %
+ \advance\L@c\labelmargin@ \advance\R@c\labelmargin@
+ \advance\D@c\labelmargin@ \advance\U@c\labelmargin@
+ \setboxz@h{\kern\labelmargin@\boxz@\kern\labelmargin@}%
+ \A@=\X@c \B@=\Y@c #1\xydashl@ \the\Edge@c\thr@@
+ \advance\A@-\X@c \advance\B@-\Y@c \advance\X@c 2\A@ \advance\Y@c 2\B@
+ \ht\z@=\U@c \dp\z@=\D@c \dimen@=\L@c \advance\dimen@\R@c \wd\z@=\dimen@
+ \setbox\lastobjectbox@=\hbox{\X@c=\L@c \Y@c=\z@ \Drop@@}%
+ \drop@{\box\lastobjectbox@}{}%
+ \leave@}}
+
+\xydef@\PATHlabelbreak@#1#2{%
+ \DN@{#1}\ifx\next@\empty \drop\labelbox{#2}\else \drop#1{#2}\fi
+ \def\afteraliases@@{\xy@@\Cbreak@@}\xyFN@\PATHlabelalias@}
+\DOCMODE)
+
+ These emulate the effect of the <modifier>s |!C|
+ |+<|2"labelmargin"|>| <perp> |!P| <unperp> where <perp>,<unperp> are
+ |^|,|_| for |^|-labels and |_|,|^| for |_|-labels. The last hack
+ using |\lastobjectbox@| aims at both setting that right and setting
+ the label as an object (such that modifiers take effect) even though
+ its placement is peculiar.
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ Labels will be separated from the connection by the "label"\-"margin"
+ that you can set with the operation
+%
+\begin{defs1}
+ ??c![\labelmargin] <add op> |{|<dimen>|}|
+\end{defs1}
+\noindent\unskip
+%
+ that works like the kernel ??c![\objectmargin] command; in fact
+ "labelmargin" defaults to use "objectmargin" if not set.
+
+\DOCMODE(
+\xylet@\labelmargin@=\objectmargin@
+
+\xydef@\labelmargin{\afterADDOP{\Addop@@\labelmargin@}}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[break with <it>]??=[piece]
+%
+ Breaking means to ``slice a hole'' in the connection and insert <it>
+ there. This is realized by typesetting the connection in question in
+ "subsegments", one leading to the break and one continuing after the
+ break as described in notes~??[<action>] and~??[straight segment].
+
+ The special control sequence ??c![\hole] is provided to make it easy to
+ make an empty break.
+
+\DOCMODE(
+\xydef@\hole{\hbox{\dimen@=\objectmargin@ \kern2\dimen@
+ \vrule height\dimen@ depth\dimen@ width\z@}}
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ Subsegments are typeset using the `|\Cbreak@@|' method.
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[default label]
+%
+ Unless <it> is a full-fledged <object> (by using the ??c![*] form),
+ it is typeset using a ??c![\labelbox] object (initially similar to
+ ??c![\objectbox] of basic \Xy-pic but using ??c![\labelstyle] for the
+ style).
+
+ \REMARK: You can only omit the |{}|s around single letters, digits,
+ and control sequences.
+
+\DOCMODE(
+\xylet@\labelstyle=\scriptstyle
+\xydef@\labelbox#1{\hbox{$\m@th\labelstyle{#1}$}}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[name for label object]
+%
+ A label is an object like any other in the \Xy-picture. Inserting an
+ <alias> ??c![=]|"|<id>|"| saves the label object as |"|<id>|"| for
+ later reference.
+
+\begin{exercise}
+ Typeset
+%
+\begin{code}
+\xy(0,0)
+ \ar @{-->} (30,7) ^A="a"
+ \POS(10,12)*+\txt{label} \ar "a"
+\endxy
+\end{code}
+$$\docode$$
+%
+\answercode
+\answertext{The author did \displaycode}
+\end{exercise}
+
+\DOCMODE(
+\xydef@\PATHlabelalias@{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\PATHlabelalias@}%
+ \else \addEQ@\ifx \next
+ \addEQ@\DN@"##1"{\savealias@{##1}\xyFN@\PATHlabelalias@}%
+ \else \DN@{\afteraliases@@\PATHlabels@}\fi\fi \next@}
+
+\xylet@\afteraliases@@=\empty
+
+%{\xyuncatcodes \gdef\next#1{\POS!C="#1"\relax}}
+\xydef@\savealias@#1{\xy@@{\enter@\cfromthec@
+ \advance\X@c-\L@c \advance\L@c\R@c \L@c=.5\L@c \R@c=\L@c \advance\X@c\L@c
+ \advance\Y@c-\D@c \advance\D@c\U@c \D@c=.5\D@c \U@c=\D@c \advance\Y@c\D@c
+ \idfromc@{#1}\leave@}}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\end{notes}
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\subsection{Arrows}
+??=[arrow]
+
+\begin{figure*}[tb]
+\vfil
+\begin{syntax}
+%
+ \multispan{3}{{\tt\string\ar} <arrow> <path>\hfil}
+ & make <arrow> along <path>
+\cr
+\noalign{\nobreak\smallskip\nobreak\hrule\nobreak\smallskip\nobreak}
+%
+ <arrow>
+ &\iss & <form>\star
+ & <arrow> has the <form>s
+\cr
+\noalign{\smallskip}
+%
+ <form>
+ &\iss & ??c![@] <variant>
+ & use <variant> of arrow
+\cr
+ &\orr & ??c![@] <variant> |{| <tip> |}|
+ & ??!^[build arrow] using <variant> of a standard stem and <tip> for
+ the head
+\cr
+ &\orr & ??c![@] <variant> |{| <tip> <conn> <tip> |}|
+ & ??!^[build arrow] using <variant> of <tip>, <conn>, <tip>
+ as arrow tail, stem, and head (in that order)
+\cr
+ &\orr & ??c![@] <connchar>
+ & change stem to the indicated <connchar>
+\cr
+ &\orr & ??c![@!]
+ & dash the arrow stem by doubling it
+\cr
+ &\orr & ??c![@/] <direction> <dist> |/|
+ & ??!^[curve] arrow the <dist>ance towards <direction>
+\cr
+ &\orr & ??c![@(] <direction> |,| <direction> |)|
+ & curve to fit with ??!^[in-out directions]
+\cr
+ &\orr & ??c![@`] |{| <control point list> |}|
+ & ??!^[curve setup] with explicit control points
+\cr
+ &\orr & |@[| <shape> |]|
+ & add |[|<shape>|]| to ??!^[object <modifier>s] for all objects
+\cr
+ &\orr & ??c![@*] |{| <modifier>\star\ |}|
+ & add ??!^[object <modifier>s] for all objects
+\cr
+ &\orr & ??c![@<] <dimen> |>|
+ & ??!^[slide arrow] the <dimen>
+\cr
+ &\orr & ??c![|] <anchor> <it>
+ & break each segment at <anchor> with <it>
+\cr
+ &\orr & ??c![^] <anchor> <it> \orr\ ??c![_] <anchor> <it>
+ & label each segment at <anchor> with <it>
+\cr
+ &\orr & ??c![@?]
+ & ??!^[reverse meaning of above and below]
+\cr
+\noalign{\smallskip}
+%
+ <variant>
+ &\iss & <empty> \orr\ ??c![^] \orr\ ??c![_] & \cr
+ & & \orr\ ??c![0] \orr\ ??c![1] \orr\ ??c![2] \orr\ ??c![3]
+ & <variant>: plain, above, below, double, or triple
+\cr
+\noalign{\smallskip}
+%
+ <tip>
+ &\iss & <tipchar>\star
+ & directional named as the sequence of <tipchar>s
+\cr
+ &\orr & <dir>
+ & ??!^[any <dir>ectional]
+\cr
+\noalign{\smallskip}
+%
+ <tipchar>
+ &\iss & |<|\orr|>|\orr|(|\orr|)|\orr||||\orr|'|\orr|`|\orr|+|\orr|/|
+ & recognised tip characters
+\cr
+ &\orr & <letter> \orr\ <space>
+ & more tip characters
+\cr
+\noalign{\smallskip}
+%
+ <conn>
+ &\iss & <connchar>\star
+ & directional named as the sequence of <connchar>s
+\cr
+ &\orr & <dir>
+ & ??!^[any <dir>ectional]
+\cr
+\noalign{\smallskip}
+%
+ <connchar>
+ &\iss & |-|\orr|.|\orr|~|\orr|=|\orr|:|
+ & recognised connector characters
+\cr
+\end{syntax}
+\caption{\protect<arrow>s.}??=[f.arrow]
+\vfil
+\end{figure*}
+
+\DOCMODE(
+\message{\string\ar,}
+\DOCMODE)
+
+ Arrows are paths with a particularly easy syntax for setting up
+ arrows with "tail", "stem", and "head" in the style
+ of~\cite{R92:HowTPDAT}. This is provided by a single <decor>ation
+ the syntax of which is described in figure~??[f.arrow] (with the
+ added convention that a raised `\star' means 0 or more repetitions of
+ the preceeding nonterminal).
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\paragraph*{Parsing:}
+
+ The ??c![\ar] command effectively translates the <arrow> into a
+ ??c![\PATH] command that initialises the tail, stem, and head of it as
+ required to get the desired <arrow>.
+
+ The translation of the <arrow> is saved in the following variables:
+
+\DOCMODE(
+\xylet@\arvariant@@=\empty
+\xylet@\arstemprefix@@=\empty
+\xylet@\artail@@=\empty
+\xylet@\arstem@@=\empty
+\xylet@\arhead@@=\empty
+\xylet@\armodifiers@@=\empty
+\xylet@\arlabels@@=\empty
+\xylet@\arafterPOS@@=\empty
+\xylet@\arinit@@=\empty
+\xylet@\arexit@@=\empty
+
+\xylet@\arcomponent@@=\relax
+\xylet@\arcomponenttype@@=\relax
+
+\xylet@\afterar@@=\relax
+\DOCMODE)
+
+ ??c![\ar] stores the defaults; it loads an intermediate command to
+ avoid problems when used as first command in compiled matrix
+ entry\dots
+
+\DOCMODE(
+\xydef@\ar{\relax\arSAFE}
+
+\xydef@\arSAFE{%
+ \let\arvariant@@=\empty
+ \def\arstemprefix@@{\dir}%
+ \edef\artail@@{\arvariant@@{}}%
+ \edef\arstem@@{\arvariant@@{-}}%
+ \edef\arhead@@{\arvariant@@{>}}%
+ \def\armodifiers@@{}%
+ \def\arafterPOS@@{}%
+ \def\arlabels@@{}%
+ \def\arinit@@{}%
+ \def\arexit@@{}%
+ \let\PATHlabelabove@@=\PATHlabelabove@
+ \let\PATHlabelbelow@@=\PATHlabelbelow@
+ \xyFN@\ar@}
+\DOCMODE)
+
+ |\ar@| is where we parse the sequence of <form>s and continue with
+ typesetting the arrow afterwards.
+
+\DOCMODE(
+\xydef@\ar@{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\ar@}%
+ \else \addAT@\ifx\next \addAT@\DN@{\xyFN@\ar@form}%
+ \else\ifx |\next
+ \DN@ |{\ar@anchor|}%
+ \else\ifx ^\next
+ \DN@ ^{\ar@anchor^}%
+ \else\ifx _\next
+ \DN@ _{\ar@anchor_}%
+ \else \let\next@=\ar@x \fi\fi\fi\fi\fi \next@}
+\DOCMODE)
+
+ \NOTE: Makes use of the "new compilation principle" to parse a
+ <place> vacuously\dots
+
+\DOCMODE(
+\xydef@\addtoarinit@#1{%
+ \expandafter\def\expandafter\arinit@@\expandafter{\arinit@@ #1}}
+
+\xydef@\addtoarlabels@#1{%
+ \expandafter\def\expandafter\arlabels@@\expandafter{\arlabels@@ #1}}
+
+\xydef@\ar@anchor#1{\begingroup
+ \def\PATHlabelit@@##1##2{%
+ \DN@{##1}\ifx\next@\empty
+ \DN@####1{\expandafter\endgroup\expandafter\addtoarlabels@
+ \expandafter{\the\toks@####1{##2}}\xyFN@\ar@}%
+ \else
+ \DN@####1{\expandafter\endgroup\expandafter\addtoarlabels@
+ \expandafter{\the\toks@*!C####1##1{##2}}\xyFN@\ar@}\fi
+ \expandafter\next@\expandafter{\PATHitshape@@}}%
+ \toks@={#1}%
+ \def\xy@##1##2{\addtotoks@{##1}}\change@oxy@\xy@ \let\xy@@ix@=\eat@
+ \DNii@{}\xyFN@\PATHanchor@}
+\DOCMODE)
+
+ |\ar@form| handles one <form>:
+
+\DOCMODE(
+\xydef@\ar@form{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\ar@form}%
+ \else\ifx ^\next \DN@ ^{\xyFN@\ar@style}\edef\arvariant@@{\string^}%
+ \else\ifx _\next \DN@ _{\xyFN@\ar@style}\edef\arvariant@@{\string_}%
+ \else\ifx 0\next \DN@ 0{\xyFN@\ar@style}\def\arvariant@@{0}%
+ \else\ifx 1\next \DN@ 1{\xyFN@\ar@style}\def\arvariant@@{1}%
+ \else\ifx 2\next \DN@ 2{\xyFN@\ar@style}\def\arvariant@@{2}%
+ \else\ifx 3\next \DN@ 3{\xyFN@\ar@style}\def\arvariant@@{3}%
+ \else\ifx \bgroup\next \let\next@=\ar@style
+ \else\ifx [\next \DN@[##1]{\ar@modifiers{[##1]}}%]
+ \else\ifx *\next \DN@ *{\ar@modifiers}%
+ \else\addLT@\ifx\next \let\next@=\ar@slide
+ \else\ifx /\next \let\next@=\ar@curveslash
+ \else\ifx (\next \let\next@=\ar@curveinout %)
+ \else\addRQ@\ifx\next \addRQ@\DN@{\ar@curve@}%
+ \else\addLQ@\ifx\next \addLQ@\DN@{\xyFN@\ar@curve}%
+ \else\addDASH@\ifx\next \addDASH@\DN@{\defarstem@-\xyFN@\ar@}%
+ \else\addEQ@\ifx\next \addEQ@\DN@{\def\arvariant@@{2}\defarstem@-\xyFN@\ar@}%
+ \else\addDOT@\ifx\next \addDOT@\DN@{\defarstem@.\xyFN@\ar@}%
+ \else\ifx :\next \DN@:{\def\arvariant@@{2}\defarstem@.\xyFN@\ar@}%
+ \else\ifx ~\next \DN@~{\defarstem@~\xyFN@\ar@}%
+ \else\ifx !\next \DN@!{\dasharstem@\xyFN@\ar@}%
+ \else\ifx ?\next \DN@?{\ar@upsidedown\xyFN@\ar@}%
+ \else \let\next@=\ar@error
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi \next@}
+
+\xydef@\defarstem@#1{\edef\arstem@@{\arvariant@@{\string#1}}%
+ \DNii@##1##{\next@}%
+ \edef\next@##1{\def\noexpand\artail@@{\arvariant@@{##1}}}%
+ \expandafter\nextii@\artail@@
+ \edef\next@##1{\def\noexpand\arhead@@{\arvariant@@{##1}}}%
+ \expandafter\nextii@\arhead@@}
+
+\xydef@\dasharstem@{%
+ \DN@##1##{\nextii@{##1}}\DNii@##1##2{\def\arstem@@{##1{##2##2}}}%
+ \expandafter\next@\arstem@@}
+
+\xydef@\ar@error#1{\xyerror@{Illegal <form>ation (\meaning\next)}{}%
+ \xyFN@\ar@}
+\DOCMODE)
+
+ |\ar@i| sets the remaining defaults and then allows |\ar@ii|-|iv| to
+ pick up any tail, stem, and head using a {|$|} as terminator.%$
+
+\DOCMODE(
+\xydef@\ar@style{%
+ \ifx \bgroup\next \def\artail@@{{}}%
+ \edef\arstem@@{\arvariant@@{-}}\edef\arhead@@{\arvariant@@{>}}%
+ \expandafter\ar@i
+ \else \resetvariant@\artail@@ \resetvariant@\arstem@@ \resetvariant@\arhead@@
+ \expandafter\xyFN@\expandafter\ar@ \fi}
+
+\xydef@\resetvariant@#1{%
+ \DN@##1##{\DN@{##1}\ifx\next@\empty
+ \DN@{\expandafter\nextii@\expandafter{\arvariant@@}}%
+ \else \DN@{\nextii@{##1}}\fi \next@}%
+ \DNii@##1##2{\def#1{##1{##2}}}%
+ \expandafter\next@#1}
+
+\xydef@\ar@i#1{\DN@{#1}%
+ \ifx\next@\empty \edef\arstem@@{\arvariant@@{}}\edef\arhead@@{\arvariant@@{}}%
+ \DN@{\xyFN@\ar@}%
+ \else
+ \let\arcomponent@@=\ar@ii \let\arcomponenttype@@=\artip@
+ \DN@{\xyFN@\arcomponent@#1$}%
+ \fi \next@}
+
+\xydef@\ar@ii{\ifx $\next \let\next@=\ar@iv
+ \else \expandafter\def\expandafter\artail@@\expandafter{\the\toks@}%
+ \let\arcomponent@@=\ar@iii \let\arcomponenttype@@=\arconn@
+ \DN@{\xyFN@\arcomponent@}\fi \next@}
+
+\xydef@\ar@iii{%
+ \expandafter\def\expandafter\arstem@@\expandafter{\the\toks@}%
+ \resetvariant@\artail@@
+ \let\arcomponent@@=\ar@iv \let\arcomponenttype@@=\artip@
+ \xyFN@\arcomponent@}
+
+\xydef@\ar@iv{%
+ \expandafter\def\expandafter\arhead@@\expandafter{\the\toks@}%
+ \ifx $\next \DN@ ${\xyFN@\ar@}%
+ \else \xyerror@{illegal <arrow>: \meaning\next\space not valid}{}\fi \next@}
+\DOCMODE)
+
+ |\ar@x| is the final macro that passes control to the <path>
+ interpreter. It is a bit clumsy because we must pass the right
+ character tokens; it could definitely be more efficient by calling
+ <path> internals directly\dots
+
+\DOCMODE(
+\xydef@\ar@x{%
+ \let\arsavedPATHafterPOS@@=\PATHafterPOS \let\PATHafterPOS=\arafterPOS@
+ \toks@={\ar@PATH}%
+ \expandafter\addtotoks@\expandafter{\expandafter{\artail@@}}%#1
+ \expandafter\addtotoks@\expandafter{\expandafter{\arstem@@}}%#2
+ \expandafter\addtotoks@\expandafter{\expandafter{\arstemprefix@@}}%#3
+ \expandafter\addtotoks@\expandafter{\expandafter{\arhead@@}}%#4
+ \expandafter\addtotoks@\expandafter{\expandafter{\armodifiers@@}}%#5
+ \expandafter\addtotoks@\expandafter{\expandafter{\arinit@@}}%#6
+ \expandafter\addtotoks@\expandafter{\expandafter{\arexit@@}}%#7
+ \expandafter\addtotoks@\expandafter{\expandafter{\arlabels@@}}%#8
+ \addtotoks@{\afterar@@}%#9
+ \expandafter\DNii@\expandafter{\the\toks@}\toks@={}%
+%
+%{\let\x=\expandafter \x\x\x\DNii@\x\x\x{\nextii@}\W@{RUN: \codeof\nextii@}}%
+%
+ \nextii@}
+
+{\xyuncatcodes \gdef\next#1#2#3#4#5#6#7#8#9{%
+ \def\next{%
+ \afterPATH{#9}%
+ ~={#6\preconnect#5#3#2}%
+ ~/{#7}%
+ ~<{|<*h#5\dir#1}%
+ ~>{|>*h#5\dir#4}%
+ ~+{#8}%
+ }%
+ \next}}
+
+\xylet@\ar@PATH=\next
+
+\xydef@\arafterPOS@#1{%
+ \arsavedPATHafterPOS@@{\let\PATHafterPOS=\arsavedPATHafterPOS@@
+ \DN@{#1}\expandafter\next@\arafterPOS@@}}%
+
+\xylet@\arsavedPATHafterPOS@@=\relax
+\DOCMODE)
+
+ <tip>s and <conn>ectors are interpreted by these that leave any
+ <variant> in |\toks@ii| and the sequence of <tipchar>s or <connchar>s
+ characters in |\toks@|:
+
+ The work is really done in |\arcomponent@| that builds |\toks@|
+ with something conforming to the |\arcomponenttype@@| and then
+ passes control to |\arcomponent@@|:
+
+\DOCMODE(
+\xydef@\arcomponent@{%
+ \ifx ^\next \toks@ii={^}\DN@ ^{\xyFN@\arcomponent@i}%
+ \else\ifx _\next \toks@ii={_}\DN@ _{\xyFN@\arcomponent@i}%
+ \else\ifx 1\next \toks@ii={1}\DN@ 1{\xyFN@\arcomponent@i}%
+ \else\ifx 2\next \toks@ii={2}\DN@ 2{\xyFN@\arcomponent@i}%
+ \else\ifx 3\next \toks@ii={3}\DN@ 3{\xyFN@\arcomponent@i}%
+ \else\ifx \bgroup\next \expandafter\toks@ii\expandafter{\arvariant@@}%
+ \let\next@=\arcomponent@i
+ \else\ifx *\next \DN@*##1##{\arcomponent@ii{##1}}%
+ \else \expandafter\toks@ii\expandafter{\arvariant@@}\toks@={}%
+ \let\next@=\arcomponenttype@@
+ \fi\fi\fi\fi\fi\fi\fi
+ \next@}
+
+\xydef@\arcomponent@i#1{\toks@={#1}\arcomponent@x}
+
+\xydef@\arcomponent@ii#1#2{\toks@={*#1{#2}}\xyFN@\arcomponent@@}
+
+\xydef@\artip@{%
+ \addGT@\ifx\next \addGT@\addtotoks@ \addGT@\DN@{\xyFN@\artip@}%
+ \else\addLT@\ifx\next \addLT@\addtotoks@ \addLT@\DN@{\xyFN@\artip@}%
+ \else\ifx (\next \addtotoks@(\DN@({\xyFN@\artip@}%
+ \else\ifx )\next \addtotoks@)\DN@){\xyFN@\artip@}%
+ \else\ifx |\next \addtotoks@|\DN@|{\xyFN@\artip@}%
+ \else\addLQ@\ifx\next \addLQ@\addtotoks@ \addLQ@\DN@{\xyFN@\artip@}%
+ \else\addRQ@\ifx\next \addRQ@\addtotoks@ \addRQ@\DN@{\xyFN@\artip@}%
+ \else\addPLUS@\ifx \next \addPLUS@\addtotoks@ \addPLUS@\DN@{\xyFN@\artip@}%
+ \else\ifx /\next \addtotoks@/\DN@/{\xyFN@\artip@}%
+ \else\ifcat A\noexpand\next \DN@##1{\addtotoks@{##1}\xyFN@\artip@}%
+ \else\ifx\space@\next \addtotoks@{ }\expandafter\DN@\space{\xyFN@\artip@}%
+ \else \let\next@=\arcomponent@x
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi \next@}
+
+\xydef@\arconn@{%
+ \addDASH@\ifx\next \addDASH@\addtotoks@ \addDASH@\DN@{\xyFN@\arconn@}%
+ \else\addEQ@\ifx\next \addEQ@\addtotoks@ \addEQ@\DN@{\xyFN@\arconn@}%
+ \ifx\arvariant@@\empty \def\arvariant@@{2}\fi
+ \else\addDOT@\ifx\next \addDOT@\addtotoks@ \addDOT@\DN@{\xyFN@\arconn@}%
+ \else\ifx :\next \addtotoks@:\DN@:{\xyFN@\arconn@}%
+ \ifx\arvariant@@\empty \def\arvariant@@{2}\fi
+ \else\ifx ~\next \addtotoks@~\DN@~{\xyFN@\arconn@}%
+ \else \let\next@=\arcomponent@x
+ \fi\fi\fi\fi\fi \next@}
+
+\xydef@\arcomponent@x{%
+ \DN@##1{\toks@=\expandafter{\the\toks@ii{##1}}}%
+ \expandafter\next@\expandafter{\the\toks@}%
+ \xyFN@\arcomponent@@}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{notescontd}
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[build arrow]
+
+ Building an <arrow> is simply using the specified directionals (using
+ ??c![\dir] of~\S??g[xy.doc:objectlib.directionals]) to build a path:
+ the first <tip> becomes the "??w![arrow tail]" of the arrow, the
+ <conn>ection in the middle becomes the "??w![arrow stem]", and the
+ second <tip> becomes the "??w![arrow head]". If a <variant> is given
+ before the |{| then that variant ??c![\dir] is used for all three.
+ For example,
+%
+\begin{code}
+\xy\ar @^{(->} (20,7)\endxy
+\end{code}
+\displaycode
+%
+ typesets
+%
+$$\docode$$
+
+\begin{exercise}
+ Typeset these arrows:
+%
+\begin{code}
+\xy ;<1pc,0pc>:
+ \POS(0,0)*+{A}
+ \ar +(-2,3)*+{A'}*\cir{}
+ \ar @2 +( 0,3)*+{A''}*\cir{}
+ \ar @3 +( 2,3)*+{A'''}*\cir{}
+ \POS(6,0)*+{B}
+ \ar @1{||.>>} +(-2,3)*+{B'}*\cir{}
+ \ar @2{||.>>} +( 0,3)*+{B''}*\cir{}
+ \ar @3{||.>>} +( 2,3)*+{B'''}*\cir{}
+\endxy
+\end{code}
+$$\docode$$
+%
+\answertext{Here is the entire \Xy-picture of the exercise:}
+\answercode
+\answertext\displaycode
+\answertext{The first batch use the default |{->}| specification.}
+\end{exercise}
+
+ The above is a flexible scheme when used in conjunction with the
+ kernel ??c![\newdir] to define all sorts of arrowheads and -tails. For
+ example,
+%
+\begin{code}
+\newdir{|>}{!/4.5pt/\dir{|}
+ *:(1,-.2)\dir^{>}
+ *:(1,+.2)\dir_{>}}
+\end{code}
+\displaycode
+\gdocode
+%
+ defines a new arrow tip that makes
+%
+\begin{code}
+\xy (0,0)*+{A}
+ \ar @{=|>} (20,3)*+{B}
+\endxy
+\end{code}
+\displaycode
+%
+ typeset
+%
+$$\docode$$
+%
+ Notice that the fact that the directional uses only <tipchar>
+ characters means that it blends naturally with the existing tips.
+
+\begin{exercise}
+ Often tips used as `tails' have their ink on the wrong side of the
+ point where they are placed. Fortunately space is also a <tipchar>
+ so we can define |\dir{ >}| to generate a `tail' arrow. Do this such
+ that
+%
+\begin{code}
+\xy (0,0)*+{A}="a", (20,3)*+{B}="b"
+ \ar @{>->} "a";"b" < 2pt>
+ \ar @{ >->} "a";"b" <-2pt>
+\endxy
+\end{code}
+\displaycode
+%
+ typesets
+%
+$$
+ \newdir{ >}{{}*!/-5pt/\dir{>}}
+ \docode
+$$
+%
+\begin{code}
+\newdir{ >}{{}*!/-5pt/\dir{>}}
+\end{code}
+\answercode
+\answertext{The author used \displaycode}
+\end{exercise}
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[any <dir>ectional]
+
+ Specifying a <dir> as a <tip> or <conn> means that ??c![\dir]<dir> is
+ used for that <tip> or <conn>. For example,
+%
+\begin{code}
+\xy\ar @{<^{|}>} (20,7)\endxy
+\end{code}
+\displaycode
+%
+ typesets
+%
+$$\docode$$
+%
+ When using this you must specify a |{}| dummy <dir>ectional in order
+ to ignore one of the tail, stem, or tip components, \eg,
+%
+\begin{code}
+\xy\ar @{{}{+}>} (20,7)\endxy
+\end{code}
+\displaycode
+%
+ typesets
+%
+$$\docode$$
+%
+ In particular ??c![*]<object> is a <dir> so any <object> can be used
+ for either of the tail, stem, or head component:
+%
+\begin{code}
+\xy\ar @{*{x}*{y}*{z}} (20,7)\endxy
+\end{code}
+\displaycode
+%
+ typesets
+%
+$$\docode$$
+%
+ \NOTE: A |*| introduces an <object> whereas the directional
+ `$\xy*+!<0pt,-\jot>\dir{*}\endxy$' is typeset by the <dir> |{*}|.
+
+\begin{exercise}
+ Typeset
+\begin{code}
+\xy
+ \ar @{>>*\composite{\dir{x}*\dir{+}}<<}
+ (20,7)
+\endxy
+\end{code}
+$$\docode$$
+ using only one |\ar| command.
+%
+\answertext{The author used}
+\answercode
+\answertext\displaycode
+\end{exercise}
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[curve]
+%
+ "Curving" the arrow using $??c![/]d\ell|/|$, where $d$ is a
+ <direction> and $\ell$ a <dimen>sion, makes the stem a curve which is
+ similar to a straight line but has had it's center point `dragged'
+ the distance~$\ell$ in~$d$:
+%
+\begin{code}
+\xy
+ \POS (0,10) *\cir<2pt>{} ="a"
+ , (20,-10)*\cir<2pt>{} ="b"
+ \POS"a" \ar @/^1ex/ "b"|\uparrow
+ \POS"a" \ar @/_1ex/ "b"|\downarrow
+%
+ \POS (20,10) *\cir<2pt>{} ="a"
+ , (40,-10)*\cir<2pt>{} ="b"
+ \POS"a" \ar @/u1ex/ "b"|u
+ \POS"a" \ar @/d1ex/ "b"|d
+\endxy
+\end{code}
+$$\docode$$
+%
+ was typeset by
+%
+\displaycode
+%
+ $\ell$ defaults to |.5pc| if omitted.
+
+ This is really just a shorthand for curving using the more general
+ form described next: $??c![@/]d\ell|/|$ is the same as |@`{{**{}
+ ?+/|$d~2\ell~$|/}}| which makes the (quadratic) curve pass through
+ the point defined by the <pos> |**{} ?+/|$d\ell$|/|.
+
+\DOCMODE(
+\xydef@\ar@curveslash/#1/{\expandafter\ar@curve@\ar@slashing{#1}}
+
+\xydef@\ar@slashing#1{{\xy@{**{} ?+/#1/+/#1/ @+c}{\setupDirection@
+ \vfromslide@{#1}%
+ \X@c=2\X@c \advance\X@c\X@p \advance\X@c.5\d@X
+ \Y@c=2\Y@c \advance\Y@c\Y@p \advance\Y@c.5\d@Y
+ \czeroEdge@
+ \spushc@}}}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[in-out directions]
+%
+ Using ??c![@(]$d_2$|,|$d_2$|)| where $d_1,d_2$ are simple
+ <direction>s (as described in note~??g[xy.doc:<direction>] except it
+ is not possible to use |()|s) will typeset the arrow curved such that
+ it leaves the source in direction $d_1$ and enters the target from
+ direction~$d_2$.
+
+\begin{exercise}
+ Typeset
+%
+\begin{code}
+\xy *{\circ}="b" \ar@(ur,ul) c
+ \ar@{.>}@(dr,ul) (20,0)*{\bullet}
+\endxy
+\end{code}
+$$\docode$$
+\answercode
+\answertext{The author used \displaycode\noindent Note that it is essential
+ that the curving specification comes after the arrow style.}
+\end{exercise}
+
+\DOCMODE(
+{\xyuncatcodes \catcode`\#=6 %
+ \gdef\next(#1,#2){{+/#1 3pc/,p+/#2 3pc/}}}
+\xylet@\ar@curveinout@=\next
+
+\xydef@\ar@curveinout{\expandafter\ar@curve@load\ar@curveinout@}
+\DOCMODE)
+
+ \TODO: implement this efficiently and properly get rid of the no-|()|
+ restriction!
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[curve setup]
+%
+ The final curve form is the most general one: |@`{|<control point
+ lists>|}| sets the control points explicitly to the ones in the
+ <control point lists> (where they should be separated by~|,|). See
+ the curve extension described in~\S??g[:curve] for the way the
+ control points are used; when the control points list is parsed $p$
+ is the source and $c$ the target of the arrow.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+ Curving simply uses ??c![\crvi] instead of ??c![\dir]. The
+ only tricky bit is to put the control points on the stack
+ right.
+
+\DOCMODE(
+\xydef@\ar@curve{%
+ \ifx \space@\next \expandafter\DN@\space{\xyFN@\ar@curve}%gobble spaces
+ \else\ifx \bgroup\next \let\next@=\ar@curve@load
+ \else\ifx "\next \DN@"##1"{\ar@curve@{"##1"}}%
+ \else \xyerror@{@= <form> must be followed by \string"<id>\string" or
+ {<control point list>}}{}%
+ \fi\fi\fi \next@}
+
+{\xyuncatcodes \gdef\next#1#2{\def#1##1{#2{;@={##1}}}}}
+\next\ar@curve@load\ar@curve@
+
+\xydef@\ar@curve@#1{\curve@check
+ \setcurvearinit@{#1}\setcurvearexit@\arexit@@
+ \def\arstemprefix@@{\crvi}\xyFN@\ar@}
+
+{\xyuncatcodes \gdef\next#1{\save @(,#1\restore}}
+\xylet@\setcurvearinit@i=\next
+\xydef@\setcurvearinit@#1{%
+ \expandafter\addtoarinit@\expandafter{\setcurvearinit@i{#1}}}
+
+{\xyuncatcodes \gdef\next#1{\def#1{\POS @i @) }}}
+\xylet@\setcurvearexit@=\next
+
+\xydef@\curve@check{%
+ \xyerror@{Forms @/.../, @(...), and @`{...}, only available when curve
+ extension loaded}{}}
+\xywithoption{curve}{\let\curve@check=\relax}
+\DOCMODE)
+
+ \TODO: The parsing is trivial and should be extended to include more
+ exotic control point forms.
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[object <modifier>s]
+%
+ |@[|\dots|]| and |@*{|\dots|}| formations define what object
+ <modifier>s should be used when building objects that are part of the
+ arrow. This is mostly useful in conjunction with extensions that
+ define additional |[|<shape>|]| modifiers, \eg, if a |[red]|
+ <modifier> changes the colour of an object to red then |@[red]|
+ will make the entire arrow red; similarly if it is desired to make
+ and entire arrow invisible then |@*{i}| can be used.
+
+\DOCMODE(
+\xydef@\ar@modifiers#1{%
+ \expandafter\def\expandafter\armodifiers@@\expandafter{\armodifiers@@#1}%
+ \xyFN@\ar@}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[slide arrow]
+%
+ ??c![@<]$D$|>| will slide (each segment of) the arrow the dimension $D$
+ as explained in note~??[slide].
+
+\DOCMODE(
+{\xyuncatcodes \catcode`\#=6 \catcode`\@=11 %
+ \gdef\next<#1>{\def\arafterPOS@@{<#1>}\xyFN@\ar@}}
+\xylet@\ar@slide=\next
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\note??=[reverse meaning of above and below]
+%
+ ??c![@?] reverse the meaning of `above' and `below' for this particular
+ arrow.
+
+\DOCMODE(
+\xydef@\ar@upsidedown{\let\next=\PATHlabelabove@@
+ \let\PATHlabelabove@@=\PATHlabelbelow@@ \let\PATHlabelbelow@@=\next}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\end{notescontd}
+
+ All the features of <path>s described above are available for arrows.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\subsection*{End \& log}
+
+\DOCMODE(
+\xyendinput
+
+% $Log: xyarrow.doc,v $
+% Revision 3.5 1997/05/28 13:05:01 krisrose
+% Fixed missing breaks bug.
+%
+% 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).
+%
+% Revision 2.10 1994/06/15 12:55:07 kris
+% Second 3beta release: bug fixes.
+%
+% Revision 2.9 1994/06/09 14:59:19 kris
+% Release 3beta.
+%
+% Revision 2.8 1994/04/08 04:30:00 kris
+% Second (bug fix) 3alpha release.
+%
+% Revision 2.7 1994/03/08 10:25:18 kris
+% Release 3alpha.
+%
+% Revision 2.6.9.1 1994/03/07 04:22:46 kris
+% Last internal 3alpha and pre-2.7 release.
+%
+% NEW for version 2.7 based of path and arrow code in xypic.doc 2.6.1.1.
+\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\\\\][%&]"
+% End: