[Groff] polygon drawing compatibility

[Bernd Warken]

Werner asked me to raise another discussion on the positioning after
the drawing of a closed polygon.  This is done by the groff-escapes
`\Dp' and `\DP', and the intermediate output commands `Dp' and `DP'.

He sent me an old ditroff(1) man-page of unknown origin.  The
polygons are documented there as

       \D'p n dh1 dv1 dh2 dv2 ...'
                 draw polygon using stipple n from current stipple font
                 starting at current position by dh1 dv1 then by dh2, dv2,
                 then by dh3, dv3, then ...
       \D'P n dh1 dv1 dh2 dv2 ...'
                 same as \D'p n dh1 ...' except no border is printed.

       The position after a graphical object has been drawn is at
       its ``end'', where for circles and ellipses, the end is at
       the right side.  As with other commands, default units are
       ems horizontally and line spaces vertically.

       Realistically,  these commands are not intended for direct
       use, but for preprocessors like PIC, IDEAL, and GRN.

This is different from groff by the following facts:
- Both commands take an extra argument `stipple n' that is not found
  in groff.
- `DP' draws a polygon without border, while groff draws a filled
  polygon.

But - both commands use the classical positioning after drawing, _not_
the stupid argument sum positioning mentioned in old groff_out(5).

Thus
- there exist different incompatible roff extensions implementing
  polygon drawing (at least the ditroff above and groff), so there is no
  single standard that should or could be followed.
- at least one of these implementations uses the classical positioning
  rule for its polygons (the ditroff above).
- both in groff_out and in the ditroff above, the polygons are
  documented as being only used by preprocessors; groff_out documents
  pic to circumvent the positioning.

So we are absolutely free to stick to the classical rule for the
positioning of the groff polygons.

#####################

Werner asked me to provide an example.  Let's take an outlined
rectangle as an example for a closed polygon.  Drawing starts at A,
then a line is drawn to B, another one to C, then to D, and from there
the polygon is closed by drawing a line to the starting point A.
So the "end of drawing" is identical to the starting point, i.e. no
position changes necessary.

A           B
 +---------+
 |         |
 |         |
 +---------+
D           C

The groff escape and the intermediate output command to perform this
drawing are resp.

\D'p h1 v1 h2 v2 h3 v3'

Dp h1 v1 h2 v2 h3 v3

where
(h1, v1) is the offset of B (relative to A)
(h2, v2) is the offset of C (relative to B)
(h3, v3) is the offset of D (relative to C)

Now let's analyze what the "stupid positioning" calculation would make
in the example case.  You must be quite intelligent to fiddle this out
from the documentation in old groff_out(5),

       A difficulty arises in how the current position should  be
       changed  after  the  execution of these commands.  This is
       not of great importance since the code  generated  by  GNU
       pic  does  not depend on this.  Given a drawing command of
       the form

              \D'c x1 y1 x2 y2 ... xn yn'

       where c is not one of c, e, l, a or  ~,  Unix  troff  will
       treat each of the xi as a horizontal quantity, and each of
       the yi as a vertical quantity and  will  assume  that  the
       width of the drawn object is i>1xi, and that the height is
       i>1yi.  (The assumption about the height can  be  seen  by
       examining  the  st  and  sb registers after using such a D
       command in a \w escape sequence.)  This  rule  also  holds
       for  all  the original drawing commands with the exception
       of De.  For the sake of compatibility GNU troff also  fol­
       lows  this rule, even though it produces an ugly result in
       the case of the Df, Dt, and, to a lesser extent,  DE  com­
       mands.  Thus after executing a D command of the form

              Dc x1 y1 x2 y2 ... xn yn\n

       the current position should be increased by (i>1xi,i>1yi).

In short, the horizontal offset for the postioning is calculated as
the sum of all arguments with odd index, vertical by the sum of the
even arguments.  This would position to point D in our example, while
the end of drawing is point A.

Moreover, if you draw the same figure in the opposite direction (ADCB)
the alternate argument sum positioning would go to point B; again,
this is not the end of drawing.

Now suppose you want to draw another figure.  But, oops, where are we
actually?  With the classical rule, the position did not change, so we
know where we are.  But with the ingenious positioning method, we were
sent to somewhere in the desert.  It's quite hard to calculate the
position where we landed from within groff, and this position is
neither natural nor useful.  I bet that no one ever used this except
for testing.

Ingeniously stupid, isn't it ;-)

I strongly suggest to restore reason by sticking to the classical
rule, just as other roffs do, e.g. the ditroff above.

In mathematics and music, I met the same golden rule,

    "Stick to the ancient masters".

Maybe that's a good idea for groffing, too.

Tho - Microsoft proved that stupid things are more successful.

Bernd Warken