A polygonhshapeiis specified as [P:hposi,. . .,hposi]
where[P:p1,. . .,pn]denotes the shape obtained by tracking the edge with eachpi a position relative to the object reference point. hvectoris and hcorneris can be used directly; otherwise use-pto get the rel- ative position.
Note: Do not use{}or []in thehposiitions.
Bug: The algorithm assumes that the reference point is always inside the polygon.
It is possible to frame polygons is also possible.
Bug: This code should be merged with the
‘frame’ and ‘poly’ options.
The example at the end of §32 illustrates the ex- tensions.
21 LaTeX Picture extension
Vers. 3.6 by Kristoffer H. Rosehkrisrose@tug.orgi Load as: \xyoption{picture}
This extension provides replacement commands for the LATEX picture environment commandsline and vector. At the moment this option requires LATEX.
Part III
Features
This part documents the notation added by each standard feature option. For each is indicated the described version number, the author, and how it is loaded.
The first two, ‘all’ and ‘dummy’, described in§§22 and 23, are trivial features that nevertheless prove useful sometimes. The next two, ‘arrow’ and ‘2cell’, described in §24 and 25, provide special commands for objects that ‘point’. The following, ‘matrix’
in§26, ‘graph’ in§27, ‘poly’ in§28, and ‘knot’ in§31, areinput modes that support different overall struc- turing of (parts of) XY-pictures.
22 All features
Vers. 3.8 by Kristoffer H. Rosehkrisrose@tug.orgi Load as: \xyoption{all}
As a special convenience, this feature loads a subset of XY-pic,10 namely the extensions: curve (cf. §8), frame (§9), tips (§10), line (§11), rotate (§12), color (§13), and the following features: matrix (§26),arrow(§24), andgraph (§27).
23 Dummy option
Vers. 3.7 by Kristoffer H. Rosehkrisrose@tug.orgi Load as: \xyoption{dummy}
This option is provided as a template for new options, it provides neither features nor extensions but it does count how many times it is requested.
24 Arrow and Path feature
Vers. 3.9 by Kristoffer H. Rosehkrisrose@tug.orgi Load as: \xyoption{arrow}
This feature provides XY-pic with the arrow paradigm presented in [14].
Note: \PATHcommand incompatibly changed for version 3.3 (the\arcommand is unaffected).
The basic concept introduced is thepath: a con- nection thatstarts from c(the current object), ends at a specified object, and may be split into sev- eralsegmentsbetween intermediate specified objects that can be individually labelled, change style, have breaks, etc.
§24.1 is about the\PATHprimitive, including the syntax of paths, and§24.2 is about the\arcustomi- sation of paths to draw arrows using XY-pic directional objects.
24.1 Paths
The fundamental commands of this feature are\PATH and\afterPATHthat will parse thehpathiaccording to the grammar in figure 14 with notes below.
Notes
24a. Anhactionican be either of the characters =/.
The associatedhstuffiis saved and used to call
\PATHactionhactioni{hstuffi}
before and after each segment (including all hlabelsi) for=and/, respectively.
The default\PATHactionmacro just expands to
“\POS hstuffi \relax” thus hstuffi should be of the form hposi hdecori. The user can redefine this—in fact the\arcommand described in§24.2 below is little more than a special\PATHaction command and a clever defaulting mechanism.
24b. It is possible to include a number of de- fault hlabelsi before the hlabelsi of the actual hsegmenti are interpreted, using
~hwhichi{hlabelsi}. The specified hwhichideter- mines for which segments the indicated hlabelsi should be prefixed as follows:
hwhichi applied to. . .
< next segment only
> last segment only
= every segment
(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,e.g., the ‘map- sto’ example explained below can be changed into a ‘breakto’ example: typing
\xy*+{0}\PATH
~={**\dir{-}}
~>{|>*\dir{>}}
~+{|*\dir{/}}
’(10,1)*+{1} ’(20,-2)*+{2} (30,0)*+{3}
\endxy will typeset
0 1
2 3
10The name ‘all’ hints at the fact that these were all the available options at the time ‘all’ was added.
Syntax Action
\PATH hpathi interprethpathi
\afterPATH{hdecori}hpathi interprethpathiand then runhdecori hpathi −→ ~hactioni{hstuffi}hpathi sethactioni24ato hstuffi
| ~hwhichi{hlabelsi}hpathi addhlabelsiprefix for some segments24b
| ~ {hstuffi}hpathi set failure continuation24c tohstuffi
| ’hsegmenti hpathi make straight segment24d
| ‘hturni hsegmenti hpathi make turning segment24f
| hsegmenti make last segment24g
hturni −→ hdiagi hturnradiusi 1/4 turn24fstarting in hdiagi
| hciri hturnradiusi explicit turn24f hturnradiusi −→ hemptyi use default turn radius
| /hdimeni setturnradius tohdimeni
hsegmenti −→ hpath-posi hslidei hlabelsi segment24e withhslideiandhlabelsi
hslidei −→ hemptyi | <hdimeni> optional slide24h: hdimeniin the “above” direction hlabelsi −→ ^hanchori hiti haliasi hlabelsi label withhiti24iabove hanchori
| _hanchori hiti haliasi hlabelsi label withhiti24ibelow hanchori
| |hanchori hiti haliasi hlabelsi break withhiti24j athanchori
| hemptyi no more labels
hanchori −→ -hanchori | hplacei label/break placed relative to the hplacei where - is a synonym for<>(.5)
hiti −→ hdigiti | hletteri |{htexti}| hcsi hitiis a default label24k
| *hobjecti hitiis anhobjecti
| @hdiri hitiis ahdiriectional
| [hshapei]hiti use[hshapei]forhiti
haliasi −→ hemptyi | ="hidi" optional name for label object24l
Figure 14: hpathis Note, however, that what goes into ~+{. . .} is
hlabelsiand thus not ahposi– it is not an action in the sense explained above.
24c. Specifying~{hstuffi}will set the “failure contin- uation” tohstuffi. This will be inserted when the lasthsegmentiis expected—it can even replace it or add morehsegmentis,i.e.,
\xy *+{0} \PATH ~={**\dir{-}}
~{’(20,-2)*+{2} (30,0)*+{3}} ’(10,1)*+{1}
\endxy
is equivalent to
\xy *+{0} \PATH ~={**\dir{-}}
’(10,1)*+{1} ’(20,-2)*+{2} (30,0)*+{3}
\endxy
typesetting
0 1
2 3
because when \endxy is seen then the parser knows that the next symbol is neither of the char- acters~’‘and hence that the lasthsegmentiis to be expected. Instead, however, the failure con- tinuation is inserted and parsed, and thehpathi is finished by the inserted material.
Failure continuations can be nested:
\xy *+{0} \PATH ~={**\dir{-}}
~{~{(30,0)*+{3}}
’(20,-2)*+{2}} ’(10,1)*+{1}
\endxy
will also typeset the connected digits.
24d. A “straight segment” is interpreted as follows:
1. Firstpis set to the end object of the previ- ous segment (for the first segment this is c just before the path command) and cis set to thehposistarting thehsegmenti, and the currenthslideiis applied.
2. Then the = and < segment actions are ex- panded (in that sequence) and the<action is cleared. The resultingpandcbecome the start andend object of the segment.
3. Then allhlabelsi(starting with the ones de- fined as described in note 24b below).
24e. Asegment is a part of ahpathibetween a previ- ous and a new target given as ahpath-posi: nor- mally this is just a hposi as described in §3 but it can be changed to something else by changing the control sequence\PATHafterPOSto be some- thing other than\afterPOS.
24f. A turning segment is one that does not go all the way to the givenhposibut only as far as re- quired 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 seg- ment (which is always straight) can be used to finish a winding line.
What the turn looks like is determined by the hturniform:
hemptyi Nothing between the ‘ and the hposi is interpreted the same as giving just the hdiagilast used out of a turn.
hdiagi Specifying a singlehdiagidis the same as specifying either of thehciriclesd^ord_, de- pending on whether the specifiedhposihas its center ‘above’ or ‘below’ the line fromp in thehdiagional direction.
hciri When a full explicit hciricle is available then the corresponding hciricle object is placed such that its ingoing direction is a continuation of a straight connection fromp and the outgoing direction points such that a following straight (or last) segment will connect it toc (with the same slide).
Here is an example using all forms ofhturnis:
base
A
a
B
b
C
c d
e
was typeset by
\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
Bug: Turns are only really resonable for paths that use straight lines like the one above.
Note: Always write a validhposiafter ahturni, otherwise any following ^ or _ labels can con- fuse the parser. So if you intend the^r in ‘^r to be a label then write‘,^r, using a dummy, hposiition.
The default used forturnradius can be set by the operation
\turnradiushadd opi{hdimeni} that works like the kernel \objectmargin etc.
commands; it defaults to 10pt.
Exercise 23: Typeset A
usinghturnis. (p.74)
24g. The last segment is exactly as a straight one ex- cept that the > action (if any) is executed (and cleared) just after the<action.
24h. “Sliding” a segment means moving each of the p, cobjects in the direction perpendicular to the current direction at each.
24i. Labelling means thathitiis dropped relative to the current segment using a ? hposiition. This thus depends on the user setting up a connection with a **hposias one of the actions—typically the=action is used for this (see note 24d for the details). The only difference between^and _is that they shift the label in the ^ respectively_ direction; for straight segments it is placed in the
“superscript” or “subscript” position.
Labels will be separated from the connection by thelabel margin that you can set with the opera- tion
\labelmarginhadd opi{hdimeni} that works like the kernel \objectmargin com- mand; in factlabelmargin defaults to useobject- margin if not set.
24j. Breaking means to “slice a hole” in the connec- tion and insert hiti there. This is realized by typesetting the connection in question in subseg- ments, one leading to the break and one contin- uing after the break as described in notes 24a and 24d.
The special control sequence \hole is provided to make it easy to make an empty break.
24k. Unless hiti is a full-fledged hobjecti (by using the* form), it is typeset using a\labelbox ob- ject (initially similar to \objectbox of basic XY- pic but using\labelstylefor the style).
Remark: You can only omit the{}s around sin- gle letters, digits, and control sequences.
24l. A label is an object like any other in the XY- picture. Inserting an haliasi ="hidi" saves the label object as"hidi"for later reference.
Exercise 24: Typeset
A
label
(p.74)