Back to Table of Contents | Next: Graphical objects

# Coloured text

List of color macros

## Introduction

Mom’s support for coloured text is straightforward. You begin by telling mom about the colours you want with NEWCOLOR or XCOLOR. Afterwards, any time you want text to be coloured, you either colour it with an inline escape that contains the colour name (e.g. `\*[red]` or `\*[blue]`) or invoke the macro COLOR with the name of the colour you want.

For example, say you want to have the name “Jack” in the sentence “All work and no play makes Jack a dull boy” appear in yellow. You’d begin by telling mom about the colour, yellow. There are two ways of doing this; see NEWCOLOR and XCOLOR for a full explanation of the difference between the two.

If you use XCOLOR, you’d enter this:
.XCOLOR yellow If you use NEWCOLOR, you might enter:
.NEWCOLOR yellow RGB #FFFF00

After defining or initializing the colour yellow you’d colourise the name, Jack, either with an inline escape
All work and no play makes \*[yellow]Jack\*[black] a dull boy. or with the COLOR macro
All work and no play makes .COLOR yellow Jack .COLOR black a dull boy. Notice, in both examples, that a) you have to set the colour back to black after “Jack,” and b) you don’t have to define or initialize the colour, black. Mom predefines it for you.

For information on using colour during document processing, see Colour support in document processing.

Note: Mom’s colour support is for text only. She doesn’t support “fill” (or “background”) colour for solid, enclosed graphical objects (polygons, ellipses) drawn with groff’s `\D` inline escapes, although you may give a colour as one of the arguments to mom’s “box” and “circle” macros, DBX and DCL when the first argument to these macros is `SOLID`.

Experts: If you’re accustomed to using groff’s `.defcolor` to define colours, and groff’s inline `\m[<colorname>]` to call them, you may continue to do so without confusing mom.

### Coloured text macros

- NEWCOLOR
- XCOLOR
- COLOR
- \*[<colourname>] (inline escape)

### Creating (initializing) a colour with NEWCOLOR

Macro: NEWCOLOR `<colour name> [<colour scheme>] <colour components>`

NEWCOLOR lets you create a colour, rather like an artist mixing paint on a palette. The colour isn’t used immediately; NEWCOLOR merely tells mom how to mix the colour when you need it. If you haven’t invoked `.NEWCOLOR` (or `.XCOLOR`), mom doesn’t have a clue what you mean when you reference a colour (with COLOR or `\*[<colour name>]`).

The first argument to NEWCOLOR is a name for your colour. It can be anything you like—provided it’s just one word long—and can be caps, lower case, or any combination of the two.

The second argument, which is entirely optional, is the “colour scheme” you want mom to use when mixing the colour. Valid arguments are
RGB (3 components: red green blue) CYM (3 components: cyan yellow magenta) CMYK (4 components: cyan magenta yellow black) GRAY (1 component) If you omit the second argument, mom assumes you want RGB.

The final argument is the components of your colour. This can be hexadecimal string starting with a pound sign (`#`) (for colour values in the 0-255 range) or two pound signs (`##`) (for colour values in the 0-65535 range), or it can be a series of decimal digits, separated by spaces, one digit per component, with the argument enclosed in double quotes. (If this is all gibberish to you, see Tips for newbies.)

Thus, to tell mom about a colour named “YELLOW”, you could enter one of the following:
.NEWCOLOR YELLOW #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0" .NEWCOLOR YELLOW RGB #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0" .NEWCOLOR YELLOW CMY #0000FF \"or ##0000FFFF0000 or "0 0 1" .NEWCOLOR YELLOW CMYK #0000FF00 \"or ##00000000FFFF0000 or "0 0 1 0" After you’ve told mom about a colour, you can then get her to set text in that colour either with the inline escape, `\*[<colourname>]`, or the macro COLOR. (See the example, above.)

Note: The colourname you give to NEWCOLOR may be used with groff’s `\m[<colourname>]` inline escape (the `\m` escape is used to set text and rule colours). Thus, assuming a colourname “blueblack” set with NEWCOLOR, `\*[blueblack]` and `\m[blueblack]` are equivalent. Furthermore, the colourname can be given as an argument to groff’s primitive request, `.gcolor` (which does the same thing as `\m[<colourname>]`).

Equally, the colourname may be used with `\M[<colourname>]` and `.fcolor`, which set the “fill” colour for solid graphical objects.

Tips for newbies: Colour manipulation can be tremendously confusing if you don’t have a background in graphic arts or computing. My advice, if colour intimidates you, is to stick to using mom’s default RGB colour scheme, and to fire up a colour chooser that gives you the RGB values you want for the colour you select. Plug those values into the components argument to NEWCOLOR, and you’ll get the colour you want. Both the KDE and gnome desktops have colour selectors that provide you with the shorter RGB hexadecimal string. If you’re not running KDE or gnome, the X utility, xcolorsel, provides you with a similar functionality, although it only provides RGB values for 256 pre-defined colours. If you use xcolorsel, be sure to click the button “Display format” and select “8 bit truncated rgb”.

Alternatively, you can use mom’s simpler `XCOLOR` macro to initialize one of the 256 pre-defined X colours by supplying the name of the colour as an argument.

### Initializing a colour with XCOLOR

Macro: XCOLOR `<X colourname> [<alias>]`

`<X colourname>` must be all one word, all lower case.
(See Finding X colour names for how to get a list of valid colour names.)

XCOLOR is similar to NEWCOLOR in that it tells mom to initialize a colour, but it’s easier to use. All you have to do is pass it, as an argument, the valid name of one of the 256 pre-defined X colours. The name must be all one word, and, breaking with mom policy, it must be entered in lower case.

For example, if you want to initialize the X colour, coral, all you have to do is enter
.XCOLOR coral Afterwards
.COLOR coral will colourise subsequent text coral until you instruct mom to return to black, or some other pre-defined, initialized colour. (The inline escape `\*[coral]` will equally colourise text coral after you’ve initialized the colour with XCOLOR.)

The downside of XCOLOR is that you can’t create custom colours. This restriction, however, is mitigated by the fact that for many users, 256 colours is more than enough to play around with.

While some X colours have fanciful names (peachpuff, papayawhip, thistle, snow), many are self-explanatory and self-descriptive in ordinary colour terms. “blue” is pure (rgb) blue, “green” is pure (rgb) green, and so on. Furthermore, for many X colours, there exist four variants, each representing increasingly darker shades of the same colour. For example, “blue1” is a relatively bright blue; “blue2”, “blue3” and “blue4” are increasingly darker shades. For that reason, you may find XCOLOR is a better choice than NEWCOLOR when it comes to initializing common colours.

The whimsical nature of X colour names sometimes makes for names that are long to type in, e.g. “mediumspringgreen”. The optional second argument to XCOLOR allows you to come up with more convenient name by which to reference the colour. For example, you could enter
.XCOLOR mediumspringgreen mygreen or .XCOLOR mediumspringgreen MYGREEN so that whenever you want text mediumspringgreen-ed, you can use either `.COLOR mygreen` (or `.COLOR MYGREEN`) or the inline escape `\*[mygreen]` (or `\*[MYGREEN]`.)

### Finding X colour names

There are two ways of finding the names of the pre-defined X colours. One is to consult the file, rgb.txt, included with all X11 installations. The location of the file on a Debian GNU/Linux distribution is typically /etc/X11/rgb.txt. Other distributions and other X installations may have the file in another location. The file lists the colour names, but doesn’t show you what the colours actually look like.

A better way to get the colour names, as well as to see what the colours look like, is to fire up a colour chooser (like xcolorsel) that both lists the colour names and shows a swatch of the colour as well.

Whichever method you use to find X colour names, remember that the names, passed as arguments to XCOLOR, must be all one word, all in lower case.

Note: Both the colourname and the alias you give to XCOLOR may be used with groff’s `\m[<colourname>]` inline escape (the `\m` escape is used to set text and rule colours). Thus, assuming an X-colourname “mediumspringgreen” set with XCOLOR, and an alias, “mygreen”, `\*[mediumspringgreen]`, `\m[mediumspringgreen]`, `\*[mygreen]` and `\m[mygreen]` are all equivalent. Furthermore, both the colourname and the alias can be given as an argument to groff’s primitive request, `.gcolor` (which does the same thing as `\m[<colourname>]`).

The colourname initialized with XCOLOR but not the alias may also be used with groff’s inline escape, `\M[<colorname>]`, and the corresponding primitive, `.fcolor`, both of which set the “fill” colour for solid graphical objects. If you need a colour initialized with XCOLOR for `\M` or `.fcolor`, you MUST give the full colourname; the alias won’t work.

### Invoking a colour

Macro: COLOR `<colourname>`

Inline: `\*[<colourname>]`

Once you’ve told mom about a colour (via NEWCOLOR or XCOLOR, you use either the macro COLOR or the inline escape, `\*[<colourname>]`, to cause mom to set subsequent text in that colour. See the example, above, which shows both in action.

Note: You can use the `\*[<colourname>]` inline escape in any document processing macro that takes a string argument. However, you must remember to reset the colour at the end of the argument (typically with `\*[black]`) unless you want all subsequent invocations of that particular macro to be colourised.

Furthermore, if you use `\*[<colourname>]` in the string argument passed to HEADING <n> and you’ve requested that the heading level be numbered, the numbers themselves will not be colourised, only the text you pass to the macro. If you wish the numbers to be colourised along with the text, you must explicitly tell mom with HEADING_STYLE <n>.

For colourising underscored text, see Colourising underscored text in the notes at the end of UNDERSCORE.

Back to Table of Contents | Top | Next: Graphical objects