File: groff.info,  Node: Drawing Geometric Objects,  Next: Traps,  Prev: Page Motions,  Up: GNU troff Reference

5.26 Drawing Geometric Objects
==============================

A few of the formatter's escape sequences draw lines and other geometric
objects.  Combined with each other and with page motion commands (*note
Page Motions::), a wide variety of figures is possible.  For complex
drawings, these operations can be cumbersome; the preprocessors 'gpic'
or 'ggrn' are typically used instead.

   The '\l' and '\L' escape sequences draw horizontal and vertical
sequences of glyphs, respectively.  Even the simplest of output devices
supports them.

 -- Escape sequence: \l'l'
 -- Escape sequence: \l'lc'
     Draw a horizontal line of length L from the drawing position.
     Rightward motion is positive.  Afterward, the drawing position is
     at the right end of the line.  The default scaling unit is 'm'.

     The optional second parameter C is a character with which to draw
     the line.  The default is the baseline rule special character,
     '\[ru]'.

     If C is a valid scaling unit, put '\&' after L to disambiguate the
     input.

          .de textbox
          \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
          ..

     The foregoing outputs a box rule (a vertical line), the text
     argument(s), and another box rule.  We employ the boundary-relative
     motion operator '|'.  Finally, the line-drawing escape sequences
     draw a radical extender (a form of overline) and an underline from
     the drawing position to the position coresponding to beginning of
     the _input_ line.  The drawing position returns to just after the
     right-hand box rule because the lengths of the drawn lines are
     negative, as noted above.

 -- Escape sequence: \L'l'
 -- Escape sequence: \L'lc'
     Draw a vertical line of length L from the drawing position.
     Downward motion is positive.  The default scaling unit is 'v'.  The
     default character is the box rule, '\[br]'.  As with vertical
     motion escape sequences, text processing continues where the line
     ends.  '\L' is otherwise similar to '\l'.

          $ nroff < This is a
              =>           |
              =>           |
              =>           |test.

     When writing text, the drawing position is at the text baseline;
     recall *note Page Geometry::.

   The '\D' escape sequence provides "drawing commands" that direct the
output device to render geometrical objects rather than glyphs.
Specific devices may support only a subset, or may feature additional
ones; consult the man page for the output driver in use.  Terminal
devices in particular implement almost none.  *Note Graphics Commands::.

   Rendering starts at the drawing position; when finished, the drawing
position is left at the rightmost point of the object, even for closed
figures, except where noted.  GNU 'troff' draws stroked (outlined)
objects with the stroke color, and shades filled ones with the fill
color.  *Note Colors::.  Coordinates H and V are horizontal and vertical
motions relative to the drawing position or previous point in the
command.  The default scaling unit for horizontal measurements (and
diameters of circles) is 'm'; for vertical ones, 'v'.

   Circles, ellipses, and polygons can be drawn filled or stroked.
These are independent properties; if you want a filled, stroked figure,
you must draw the same figure twice using each drawing command.  A
filled figure is always smaller than an outlined one because the former
is drawn only within its defined area, whereas strokes have a line
thickness (set with '\D't'').

     \h'1i'\v'1i'\
     \# increase line thickness
     \Z'\D't 5p''\
     \# draw stroked (unfilled) polygon
     \Z'\D'p 3 3 -6 0''\
     \# draw filled (solid) polygon
     \Z'\D'P 3 3 -6 0''

 -- Escape sequence: \D'command argument ...'
     Drawing command escape sequence parameters begin with an ordinary
     character, COMMAND, selecting the type of object to be drawn,
     followed by ARGUMENTs whose meaning is determined by COMMAND.

     '\D'~ H1 V1 ... HN VN''
          Draw a B-spline to each point in sequence, leaving the drawing
          position at (HN, VN).

     '\D'a HC VC H V''
          Draw a circular arc centered at (HC, VC) counterclockwise from
          the drawing position to a point (H, V) relative to the center.
          (1)  (*note Drawing Geometric Objects-Footnote-1::)

     '\D'c D''
          Draw a circle of diameter D with its leftmost point at the
          drawing position.

     '\D'C D''
          As '\D'C ...'', but the circle is filled.

     '\D'e H V''
          Draw an ellipse of width H and height V with its leftmost
          point at the drawing position.

     '\D'E X Y''
          As '\D'e ...'', but the ellipse is filled.

     '\D'l DX DY''
          Draw line from the drawing position to (H, V).

          The following is a macro for drawing a box around a text
          argument; for simplicity, the box margin is a fixed at 0.2m.

               .de TEXTBOX
               .  nr @wd \w'\\$1'
               \h'.2m'\
               \h'-.2m'\v'(.2m - \\n[rsb]u)'\
               \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
               \D'l (\\n[@wd]u + .4m) 0'\
               \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
               \D'l -(\\n[@wd]u + .4m) 0'\
               \h'.2m'\v'-(.2m - \\n[rsb]u)'\
               \\$1\
               \h'.2m'
               ..

          The argument is measured with the '\w' escape sequence.  Its
          width is stored in register '@wd'.  '\w' also sets the
          registers 'rst' and 'rsb'; these contain its maximum vertical
          extents of the argument.  Then, four lines are drawn to form a
          box, offset by the box margin.

     '\D'p H1 V1 ... HN VN''
          Draw polygon with vertices at drawing position and each point
          in sequence.  GNU 'troff' closes the polygon by drawing a line
          from (HN, VN) back to the initial drawing position.
          Afterward, the drawing position is left at (HN, VN).

     '\D'P DX1 DY1 DX2 DY2 ...''
          As '\D'P ...'', but the polygon is filled.

          The following macro is like the '\D'l'' example, but shades
          the box.  We draw the box before writing the text because
          colors in GNU 'troff' have no transparency; in othe opposite
          order, the filled polygon would occlude the text.

               .de TEXTBOX
               .  nr @wd \w'\\$1'
               \h'.2m'\
               \h'-.2m'\v'(.2m - \\n[rsb]u)'\
               \M[lightcyan]\
               \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
                    (\\n[@wd]u + .4m) 0 \
                    0 (\\n[rst]u - \\n[rsb]u + .4m) \
                    -(\\n[@wd]u + .4m) 0'\
               \h'.2m'\v'-(.2m - \\n[rsb]u)'\
               \M[]\
               \\$1\
               \h'.2m'
               ..

     '\D't N''
          Set the stroke thickness of geometric objects to N basic
          units.  A zero N selects the minimal supported thickness.  A
          negative N selects a thickness proportional to the type size;
          this is the default.

   In a hazy penumbra between text rendering and drawing commands we
locate the bracket-building escape sequence, '\b'.  It can assemble
apparently large glyphs by vertically stacking ordinary ones.

 -- Escape sequence: \b'contents'
     Pile and center a sequence of glyphs vertically on the output line.
     "Piling" stacks glyphs corresponding to each character in CONTENTS,
     read from left to right, and placed from top to bottom.  GNU
     'troff' separates the glyphs vertically by 1m, and the pile itself
     is centered 0.5m above the text baseline.  The horizontal drawing
     position is then advanced by the width of the widest glyph in the
     pile.

     This rather inflexible positioning algorithm doesn't work with the
     'dvi' output device since its bracket pieces vary in height.
     Instead, use the 'geqn' preprocessor.

     *note Manipulating Spacing:: describes how to adjust the vertical
     spacing of the output line with the '\x' escape sequence.

     The application of '\b' that lends its name is construction of
     brackets, braces, and parentheses when typesetting mathematics.  We
     might construct a large opening (left) brace as follows.

          \b'\[lt]\[bv]\[lk]\[bv]\[lb]'

     See 'groff_char(7)' for a list of special character identifiers.