Drawing Geometric Objects (The GNU Troff Manual)

+Next: Traps, Previous: Page Motions, Up: GNU troff Reference [Contents][Index]

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

+ + + +