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.¹³⁸

Request: .gcolor [col]

Escape sequence: \mc

Escape sequence: \m(co

Escape sequence: \m[col]

Register: \n[.m]

Select col as the stroke color for glyphs, rules, and objects drawn with \D'…' escape sequences. 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 current environment’s stroke color selection is available in the read-only string-valued register ‘.m’ (see Environments). The default strike color is named ‘default’.

GNU troff does not tokenize \m when reading it; the escape sequence updates the environment. It thus can be used in requests that expect a single-character argument. We can assign a stroke color to 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]

Select col as 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.

GNU troff does not tokenize \F when reading it; the escape sequence updates the environment. It thus can be used in requests that expect a single-character argument. We can assign a fill color to 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 current environment’s fill color selection is available in the read-only string-valued register ‘.M’ (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[]