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 (see 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 <<EOF
This is a \L'3v'test.
EOF
    ⇒ This is a
    ⇒           |
    ⇒           |
    ⇒           |test.

When writing text, the drawing position is at the text baseline; recall 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. See 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. See 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. ¹⁰⁵

\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.

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.