5.21 Colors

GNU troff supports color output with a variety of color spaces and up to 16 bits per channel. Some devices, particularly terminals, may be more limited. When color support is enabled, two colors are current at any given time: the stroke color, with which glyphs, rules (lines), and geometric objects like circles and polygons are drawn, and the fill color, which can be used to paint the interior of a closed geometric figure.

Request: .color [b]
Register: \n[.color]

Enable or disable output of color-related device-independent output commands per Boolean expression b. It is enabled by default, and if b is omitted.

The read-only register .color interpolates 1 if color support is enabled, 0 otherwise.

Color can also be disabled with the -c command-line option.

Request: .defcolor ident scheme color-component …

Define a color named ident. scheme selects a color space and determines the quantity of required color-components; it must be one of ‘rgb’ (three components), ‘cmy’ (three), ‘cmyk’ (four), or ‘gray’ (one). ‘grey’ is accepted as a synonym of ‘gray’. The color components can be encoded as a single hexadecimal value starting with ‘#’ or ‘##’. The former indicates that each component is in the range 0–255 (0–FF), the latter the range 0–65,535 (0–FFFF).

.defcolor half gray #7f
.defcolor pink rgb #FFC0CB
.defcolor magenta rgb  ##ffff0000ffff

Alternatively, each color component can be specified as a decimal fraction in the range 0–1, interpreted using a default scaling unit of f, which multiplies its value by 65,536 (but clamps it at 65,535).

.defcolor gray50 rgb 0.5 0.5 0.5
.defcolor darkgreen rgb 0.1f 0.5f 0.2f

You can obtain a report of colors defined by defcolor on the standard error stream with the pcolor request. See Debugging.

Each output device has a color named ‘default’, which cannot be redefined. A device’s default stroke and fill colors are not necessarily the same. For the dvi, html, pdf, ps, and xhtml output devices, GNU troff automatically loads a macro file defining many color names at startup. By the same mechanism, the devices supported by grotty recognize the eight standard ISO 6429/ECMA-48 color names.104

Request: .gcolor [col]
Escape sequence: \mc
Escape sequence: \m(co
Escape sequence: \m[col]
Register: \n[.m]

Set the stroke color. The escape sequence \m[] restores the previous stroke color, or the default if there is none, as does a gcolor request without an argument.

.gcolor red
The next words
.gcolor
\m[red]are in red\m[]
and these words are in the previous color.

The name of the current stroke color is available in the read-only string-valued register ‘.m’; it is associated with the environment (see Environments). The default stroke color is named ‘default’.

\m is not tokenized when GNU troff reads its input; it instead updates the environment. It thus can be used in requests that expect a single-character argument. We can thus alter the stroke color when writing a margin character as follows (see Miscellaneous).

.mc \m[red]x\m[]
Request: .fcolor [col]
Escape sequence: \Mc
Escape sequence: \M(co
Escape sequence: \M[col]
Register: \n[.M]

Set the fill color for objects drawn with \D'…' escape sequences. The escape sequence \M[] restores the previous fill color, or the default if there is none, as does an fcolor request without an argument.

\M is not tokenized when GNU troff reads its input; it instead updates the environment. It thus can be used in requests that expect a single-character argument. We can thus alter the fill color when writing a margin character as follows (see Miscellaneous); grotty interprets the fill color as a character cell background color.

.mc \m[black]\M[green]x\M[]\m[]

The name of the current fill color is available in the read-only string-valued register ‘.M’; it is associated with the environment (see Environments). The default fill color is named ‘default’.

Create an ellipse with a red interior as follows.

\M[red]\h'0.5i'\D'E 2i 1i'\M[]