Pikchr

A path-attribute is used to provide the origin and direction of a line object, that being an arc, arrow, line, move, or spline. It is an error to use a path-attribute on a block object, that being a box, circle, cylinder, diamond, dot, ellipse, file, oval, or text.

There are seven forms:

• from position
• then? to position
• then? go? direction distance?
• then? go? direction until? even with place
• (then|go) distance? heading compass-angle
• (then|go) distance? compass-direction
• close

The "from" attribute is used to assign the starting location of the line object (its ".start" value). The other six forms (collectively called "to" forms) assign intermediate vertexes or the end point (.end). If the "from" is omitted, then "from previous.end" is assumed, or if there is no previous object, "from (0,0)". If no "to" forms are provided then a single movement in the current layout direction by either the "linewid" or "lineht" (depending on layout direction) is used.

The "from" can occur either before or after the various "to" subclauses. That does not matter. But the order is important for the various "to" subclauses.

If there are two consecutive direction clauses (direction is always one of "up", "down", "left", or "right") then the two will be combined to specify a single line segment. Hence, the following are equivalent:

• ... right 4cm up 3cm ...
• ... go 5cm heading 53.13010235 ...

leftmargin = 1cm
A1: arrow thick right 4cm up 3cm
dot at A1.start
X1: line thin color gray from (0,-3mm) down 0.4cm
X2: line same from (4cm,-3mm) down 0.4cm
arrow thin color gray from X1 to X2 "4cm" above
X3: line same from (4cm+3mm,0) right 0.4cm
X4: line same from (4cm+3mm,3cm) right .4cm
arrow thin color gray from X3 to X4 "3cm" aligned above
X5: line same from A1.start go 4mm heading 90+53.13010235
X6: line same from A1.end go 4mm heading 90+53.13010235
arrow thin color gray from X5 to X6 "5cm" below aligned
line same from (0,1cm) up 1cm
spline -> from 1.5cm heading 0 from A1.start \
   to 1.5cm heading 10 from A1.start \
   to 1.5cm heading 20 from A1.start \
   to 1.5cm heading 30 from A1.start \
   to 1.5cm heading 40 from A1.start \
   to 1.5cm heading 53.13 from A1.start \
   thin color gray "53.13°" aligned center small

If two separate movements are desired, one 4cm right and another 3cm up, then the "right" and "up" subphrases must be separated by the "then" keyword:

• ... right 4cm then up 3cm ...

leftmargin = 1cm
A1: arrow thick right 4cm then up 3cm
dot at A1.start
X1: line thin color gray from (0,-3mm) down 0.4cm
X2: line same from (4cm,-3mm) down 0.4cm
arrow thin color gray from X1 to X2 "4cm" above
X3: line same from (4cm+3mm,0) right 0.4cm
X4: line same from (4cm+3mm,3cm) right .4cm
arrow thin color gray from X3 to X4 "3cm" aligned above

The "until even with" subclause

The "until even with" clause is a Pikchr extension (it does not exist in PIC) that makes it easier to specify paths that follow a "Manhattan geometry" (lines are axis-aligned) or that negotiate around obstacles. The phrase:

go direction until even with position

Means to continue the line in the specified direction until the coordinate being changed matches the corresponding coordinate in position. If the line is going up or down, then it continues until the Y coordinate matches the Y coordinate of position. If the line is going left or right, then it continues until the X coordinate matches the X coordinate of position.

For example, suppose in the diagram below that we want to draw an arrow that begins on Origin.s and ends on Destination.s but goes around the Obstacle oval, clearing it by at least one centimeter.

box "Origin"
Obstacle: oval ht 300% wid 30% with .n at linewid right of Origin.ne;
box "Destination" with .nw at linewid right of Obstacle.n
line invis from 1st oval.s to 1st oval.n "Obstacle" aligned

The arrow might look like this:

   arrow from Origin.s \
      down until even with 1cm below Obstacle.s \
      then right until even with Destination.s \
      then to Destination.s

And we have (annotations added):

box "Origin"
Obstacle: oval ht 300% wid 30% with .n at linewid right of Origin.ne;
box "Destination" with .nw at linewid right of Obstacle.n
line invis from 1st oval.s to 1st oval.n "Obstacle" aligned
X: \
   arrow from Origin.s \
      down until even with 1cm below Obstacle.s \
      then right until even with Destination.s \
      then to Destination.s

line invis color gray from X.start to 2nd vertex of X \
    "down until even with" aligned small \
    "1cm below Obstacle.s" aligned small
line invis color gray from 2nd vertex of X to 3rd vertex of X \
    "right until even with Destination.s" aligned small above
line invis color gray from 3rd vertex of X to 4th vertex of X \
    "to Destination.s" aligned small above

# Evidence that the alternative arrow is equivalent:
assert( 2nd vertex of X == (Origin.s, 1cm below Obstacle.s) )
assert( 3rd vertex of X == (Destination.s, 1cm below Obstacle.s) )

The "( position , position )" syntax can be used in a similar way. The "( position , position )" syntax means a point whose X coordinate is taken from the first position and whose Y coordinate is taken from the second position. So the line around the obstacle could have been written like this:

   arrow from Origin.s \
     to (Origin.s, 1cm below Obstacle.s) \
     then to (Destination.s, 1cm below Obstacle.s) \
     then to Destination.s

However, we believe the "until even with" notation is easier.

The "close" subclause

The "close" attribute closes a multi-segment path so that it forms a polygon. When "close" is used, the ".end" point of the object is no longer the last vertex in the path but is instead one of ".e", ".s", ".w", or ".n" according to the current layout direction, as it would be for a block object.

The following diagram illustrates this behavior. The ".end" of each line is tagged with a red dot. The line that uses "close" has its end at the ".e" point of the bounding box since the layout direction is "right". The line without "close" has its ".end" at the last vertex of the line.

line right 2cm then down .5cm then up 1cm right 1cm \
   then up 1cm left 1cm then down .5cm then left 2cm \
   close "with 'close'"
dot color red at last line.end

move to 2.5cm south of last line.start
line right 2cm then down .5cm then up 1cm right 1cm \
   then up 1cm left 1cm then down .5cm then left 2cm \
   then down 1cm "without 'close'"
dot color red at last line.end