[Xy-pic] \POS

[Ross Moore]

Hi Steve,

On 25/08/2012, at 10:26, SteveBravy at aol.com wrote:

> Hi Ross:
>  
> Thanks for your response, which gave me information I couldn't find elsewhere. By the way, is there an on-line source I could look up for answers rather than bother you/others in the future?
>  
> I guess I'm about to look a gift horse in the mouth- I apologize. I'm enclosing some questions to help me apply the information you provided to some specific cases- what is being interpreted, what is (are) the \POS argument(s), and what does \POS do to/with these arguments.

\POS does not have arguments, the way TeX macros normally do.
Instead it examines each character in turn to decide what to do next.
The whole parsing structure is described in the BNF diagrams in the Xy-pic Reference manual.


>  
> Code
> Reference
> Comments
> Question(s)
> \def\ToPOS{\save\afterPOS{%
> \POS**{}?>*@2{>}**@{-}\restore};p,}
> XY-pic reference, page 16
> ─   I think I understand the head and shaft constructions
> ─   I believe {} refers to the current node (c)
> 1.       What is \POS interpreting here?
> 2.       Is the current state saved?
> 3.       What does \restore;p do? Why the terminating comma?
> …“\POS <stuff> \relax" thus <stuff>        should be of
> the form <pos> <décor>.
> XY-pic reference, page 38
> ─ This seems to imply that \POS takes both
> <pos> <décor> as inputs.
> ─  
> What does \POS do with the two arguments:
> ─  Only acts on <pos>?
> ─  interpret <pos> and then apply <décor> there?
> \POS (0,10) *\cir<2pt>{} ="a"
> , (20,-10)*\cir<2pt>{} ="b"
> \POS"a" \ar @/^1ex/ "b"|\uparrow
> \POS"a" \ar @/_1ex/ "b"|\downarrow
> XY-pic reference, page 42
>  
> What does \POS do here?
> \everyentry={{\the\Row,\the\Col}}
> \xymatrix @*[F]@*[o] {
> {} \POS[];[r]**\dir{..} & \\
> {} \POS[];[ur]**\dir{--} }
> XY-pic slides by Akagi, 1.20 page 11
> ─  Looks like [] represents the current matrix entry
> ─  Looks like {} because @*[F]@*[o] and \everyentry provides the shape and contents  
> 1.   Does \POS interpret [] and [r]?  Why is \POS required here?

In the first example, \POS  detects the * , then the ** .
With just a single * we would be detecting an object to drop into the diagram at the current position. But with ** we establish a connection between the current and previous point, using the object which follows to build a “line” or curve or whatever.

In the example, the object given by {} is the null object. Thus no ink is set, but all the calculations are done to parametrize points along the line, and establish what direction the line points.

Next,  ?> moves to the end of the line,  where  *  causes an object to be dropped.
The  @  ensures the object is chosen to match the current direction (as established by the earlier ** ).  The  2{>}  selects the object to be an arrowhead, appropriate for a double-shafted line.

Then comes  **{-}  which reestablishes the connection, this time drawing the line.
Since the previous position has not changed, the line is drawn from the boundary of whatever object was there.  Note that the current position has changed, from what it was before the  \save , having inherited size information from the dropped arrowhead. Thus the line is drawn to the boundary of the arrowhead, rather than to the exact position where it is dropped. Finally, the  \restore  resets to graphics state to what was \save'd. This allows Xy-pic to do further drawing, as if that arrow had never been drawn.

All the above actions are wrapped as the argument of \afterPOS , which is what happens when the \POS parsing gets to the end of valid input.
\afterPOS  stores it's argument, then calls \POS on the tokens which follow;
 that is, use of 
       \ToPOS ...more tokens...
results in
   \POS ;p, ...more tokens... ...afterPOS tokens ,
where  ...more tokens... is specifying where to draw the arrow to.

This means that the \save  is storing the graphics state as it will be at the end of  ...more tokens... and this state is \restore'd after the arrowhead has been drawn.

Answering your first set of questions.

     {}  is the null object, being used to do calculations without placing any ink.

    1. that depends upon which \POS  you actually mean.
         The one in the  ...afterPOS  tokens interprets what is needed to place the arrow.
         This happens after the implicit one that interprets user-supplied tokens to determine the target of the arrow, as described above.
          \save  also causes a \POS , but this immediately ceases with \afterPOS .
          \restore also causes a  \POS , so that further material can be added to the diagram.

    2.  The state is saved *after* the target of the arrow has been established.
          This is the position that needs to be returned to, so that further material can be added after the arrowhead and shaft have been placed.

    3.  the comma is frequently not vital. It is a kind of no-op that just ensures the \POS parsing macro code is really back at the top level of its hierarchical structure, ready for the user-supplied tokens which are to follow. 


2nd set.
      The usual action for  \afterPOS  is to check whether any  <decor>  follows.
       This decor is not an argument to be read, it is just an extension to the parsing, for material that is presented a bit differently.

3rd set
     The 2nd and 3rd instances of \POS are actually unnecessary; a single ‘,’ would suffice.
     I think the best answer is for “clarity” in presenting the example.
     Certainly this is one way to ensure that the parsing of one part of the diagram is fully complete before continuing with some more. This could be necessary in some circumstances.

4th set
    \POS  or some other Xy-pic macro is needed, to turn on parsing within each cell.
   Otherwise the material is just normal TeX content, within a tabular alignment.
   Ultimately \xymatrix  must use TeX’s alignment primitives, which have no inbuilt concept of what Xy-pic does. So in each cell, parsing must be turned on, to interpret information about objects, such as arrows, that need to be drawn outside, or crossing over, the cell structure.
parsing cannot survive the cell boundaries; ie. the & symbols.




I hope you'll see from this that Xy-pic is very intricate, as it really needs to be.
To construct extended objects such as arrows and curves, taking into account the correct sizes and margins, etc. requires taking the user-supplied input, and merging it with internally-generated bits of input supplied though macros. 
Everything has to work seamlessly, with much of if being transparent to the user.

The Xy-pic Reference manual is the definitive documentation, so far as describing the concepts and the language. Everything is in there, but it is packed more densely than most text books.
A fuller understanding may come from the xy***.doc  files themselves. These contain both the source coding, and the documentation, in a literate programming style.
These should be on your system under        texmf/doc/generic/xypic      or similar path.

>  
> Thanks and Cheers

Hope this helps,

     Ross

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://tug.org/pipermail/xy-pic/attachments/20120826/553fc0e3/attachment-0001.html>