1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009 Free Software Foundation, Inc.
Written by Peter Schaffter.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being this comment section, with no Front-Cover
Texts, and with no Back-Cover Texts.
A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"/>
<title>Mom -- Colour</title>
</head>
<body bgcolor="#dfdfdf">
<!-- ==================================================================== -->
<a name="TOP"></a>
<p>
<a href="docprocessing.html#TOP">Next</a>
<a href="inlines.html#TOP">Prev</a>
<a href="toc.html">Back to Table of Contents</a>
</p>
<h1 align="center"><a name="COLOR_INTRO"><u>Coloured text</u></a></h1>
<p>
<a href="#INTRO_COLOR">Introduction to coloured text</a>
<br/>
<a href="#MACROS_COLOR">Index of colour macros</a>
</p>
<a name="INTRO_COLOR"><h2><u>Introduction to coloured text</u></h2></a>
<p>
<strong>Mom</strong>'s support for coloured text is straightforward.
You begin by telling <strong>mom</strong> about the colours you want
with
<a href="#NEWCOLOR">NEWCOLOR</a>
or
<a href="#XCOLOR">XCOLOR</a>.
Afterward, any time you want text to be coloured, you either colour
it with an
<a href="definitions.html#TERMS_INLINES">inline escape</a>
that contains the colour name (e.g. <kbd>\*[red]</kbd> or
<kbd>\*[blue]</kbd>) or invoke the macro,
<a href="#COLOR">COLOR</a>,
with the name of the colour you want.
</p>
<a name="COLOR_EXAMPLE"></a>
<p>
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 <strong>mom</strong> about
the colour, yellow. There are two ways of doing this; see
<a href="#NEWCOLOR">NEWCOLOR</a>
and
<a href="#XCOLOR">XCOLOR</a>
for a full explanation of the difference between the two.
</p>
<p>
If you use <strong>XCOLOR</strong>, you'd enter this:
<pre>
.XCOLOR yellow
</pre>
</p>
<p>
If you use <strong>NEWCOLOR</strong>, you might enter
<pre>
.NEWCOLOR yellow RGB #FFFF00
</pre>
</p>
<a name="COLOR_EXAMPLE2"></a>
<p>
After "defining" (or "initializing") the colour
"yellow", you'd colourize the name, Jack, either with an
inline escape
<pre>
All work and no play makes \*[yellow]Jack\*[black] a dull boy.
</pre>
or with the
<a href="#COLOR">COLOR</a>
macro
<pre>
All work and no play makes
.COLOR yellow
Jack
.COLOR black
a dull boy.
</pre>
</p>
<p>
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 intialize the colour, black. <strong>Mom</strong> predefines
it for you.
</p>
<p>
For information on using colour during
<a href="docprocessing.html#INTRO_MACROS_DOCPROCESSING">document processing</a>,
see
<a href="docprocessing.html#COLOR">Colour support in document processing</a>.
</p>
<p>
<strong>Please note: Mom</strong>'s colour support is for text only.
She doesn't support "fill" (or "background")
colour for solid, enclosed graphical objects (polygons, ellipses)
drawn with <strong>groff</strong>'s <kbd>\D</kbd>
<a href="definitions.html#TERMS_INLINES">inline escapes</a>,
although you may give a colour as one of the arguments to
<strong>mom</strong>'s "box" and "circle"
macros,
<a href="graphical.html#DBX">DBX</a>
and
<a href="graphical.html#DCL">DCL</a>
when the first argument to these macros is <kbd>SOLID</kbd>.
</p>
<p>
Please also note that if you're accustomed to using groff's
<kbd>.defcolor</kbd> to define colours, and groff's inline
<kbd>\m[<colorname>]</kbd> to call them, you may continue to
do so without confusing <strong>mom</strong>.
</p>
<a name="MACROS_COLOR"><h3><u>Index of colour macros</u></h3></a>
<ul>
<li><a href="#NEWCOLOR">NEWCOLOR</a></li>
<li><a href="#XCOLOR">XCOLOR</a></li>
<li><a href="#COLOR">COLOR</a></li>
<li><a href="#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a> inline escape</li>
</ul>
<!-- -NEWCOLOR- -->
<hr width="66%" align="left"/>
<a name="NEWCOLOR"><h3><u>Creating (initializing) a colour with NEWCOLOR</u></h3></a>
<p>
<nobr>Macro: <strong>NEWCOLOR</strong> <kbd><colour name> [<colour scheme>] <colour components></kbd></nobr>
</p>
<p>
<strong>NEWCOLOR</strong> lets you create a colour, rather
like an artist mixing paint on a palette. The colour isn't
used immediately; <strong>NEWCOLOR</strong> merely tells
<strong>mom</strong> how to mix the colour when you need it. If you
haven't invoked <kbd>.NEWCOLOR</kbd> (or
<a href="#XCOLOR">XCOLOR</a>),
<strong>mom</strong> doesn't have a clue what you mean when you
reference a colour (with
<a href="#COLOR">COLOR</a>
or
<a href="#COLOR_INLINE"><kbd>\*[<color name>]</kbd></a>).
</p>
<p>
The first argument to <strong>NEWCOLOR</strong> 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.
</p>
<p>
The second argument, which is entirely optional, is the "colour
scheme" you want <strong>mom</strong> to use when mixing the
colour. Valid arguments are
<pre>
RBG (3 components: red green blue)
CYM (3 components: cyan yellow magenta)
CMYK (4 components: cyan magenta yellow black)
GRAY (1 component)
</pre>
If you omit the second argument, <strong>mom</strong> assumes you
want <strong>RGB</strong>.
</p>
<p>
The final argument is the components of your colour. This can be
hexadecimal string starting with a pound sign (<kbd>#</kbd>) (for
colour values in the 0-255 range) or two pound signs (<kbd>##</kbd>)
(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
<a href="#COLOR_TIP">Tips for newbies</a>.)
</p>
<p>
Thus, to tell <strong>mom</strong> about a colour named
"YELLOW", you could enter one of the following:
<pre>
.NEWCOLOR YELLOW #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0"
.NEWCOLOR YELLOW RGB #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0"
.NEWCOLOR YELLOW CYM #00FF00 \"or ##0000FFFF0000 or "0 1 0"
.NEWCOLOR YELLOW CYMK #00FF0000 \"or ##0000FFFF00000000 or "1 1 0"
</pre>
</p>
<p>
After you've told <strong>mom</strong> about a colour, you can then
get her to set text in that colour either with the
<a href="definitions.html#TERMS_INLINES">inline escape</a>,
<a href="#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a>,
or the macro,
<a href="#COLOR">COLOR</a>.
(See the
<a href="#COLOR_EXAMPLE">example</a>,
above.)
</p>
<p>
<strong>Please note:</strong> the colorname you give to
<strong>NEWCOLOR</strong> may be used with <strong>groff</strong>'s
<kbd>\m[<colorname>]</kbd> inline escape (the <kbd>\m</kbd>
escape is used to set text and rule colours). Thus, assuming a
colorname "blueblack" set with <strong>NEWCOLOR</strong>,
<kbd>\*[blueblack]</kbd> and <kbd>\m[blueblack]</kbd> are
equivalent. Furthermore, the colorname can be given as an argument
to <strong>groff</strong>'s
<a href="definitions.html#TERMS_PRIMITIVES">primitive</a>
request, <kbd>.gcolor</kbd> (which does the same thing as
<kbd>\m[<colorname>]</kbd>).
</p>
<p>
Equally, the colorname may be used with
<kbd>\M[<colorname>]</kbd> and <kbd>.fcolor</kbd>, which set
the "fill" colour for solid graphical objects.
</p>
<a name="COLOR_TIP"></a>
<h3><u>Tips for newbies</u></h3>
<p>
Colour manipulation can be tremendously confusing if you don't have
a background in graphic arts or computing. My advice, if color
intimidates you, is to stick to using <strong>mom</strong>'s default
RGB colour scheme, and to fire up a color chooser that gives you
the RGB values you want for the colour you select. Plug those
values into the components argument to <strong>NEWCOLOR</strong>,
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".
</p>
<p>
Alternatively, you can use <strong>mom</strong>'s simpler
<a href="#XCOLOR">XCOLOR</a>
macro to initialize one of the 256 pre-defined X colours by
supplying the name of the color as an argument.
</p>
<!-- -XCOLOR- -->
<hr width="33%" align="left"/>
<a name="XCOLOR"><h3><u>Initializing a colour with XCOLOR</u></h3></a>
<p>
<nobr>Macro: <strong>XCOLOR</strong> <kbd><X colorname> [<alias>]</kbd></nobr>
<br/>
<kbd>*<X colorname></kbd> <em>must be all one word, all lower case.</em>
<br/>
<em>(See</em>
<a href="#XCOLOR_NAMES">Finding X color names</a>
<em>for how to get a list of valid colour names.)</em>
</p>
<p>
<strong>XCOLOR</strong> is similar to <strong>NEWCOLOR</strong> in
that it tells <strong>mom</strong> 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 <strong>mom</strong> policy, it
must be entered in lower case.
</p>
<p>
For example, if you want to intialize the X colour, coral, all you
have to do is enter
<pre>
.XCOLOR coral
</pre>
</p>
<p>
Afterwards
<pre>
.COLOR coral
</pre>
will colourize subsequent text coral until you instruct
<strong>mom</strong> to return to black, or some other pre-defined,
initialized colour. (The
<a href="definitions.html#TERMS_INLINES">inline escape</a>
<kbd>\*[coral]</kbd> will equally colourize text coral after you've
initialized the colour with <strong>XCOLOR</strong>.)
</p>
<p>
The downside of <strong>XCOLOR</strong> 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.
</p>
<p>
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 colors, 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 <strong>XCOLOR</strong> is
a better choice than <strong>NEWCOLOR</strong> when it comes to
initializing common colors.
</p>
<p>
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 <strong>XCOLOR</strong> allows you
to come up with more convenient name by which to reference the
colour. For example, you could enter
<pre>
.XCOLOR mediumspringgreen mygreen
or
.XCOLOR mediumspringgreen MYGREEN
</pre>
so that whenever you want text mediumspringgreen-ed, you can use
either <kbd>.COLOR mygreen</kbd> (or <kbd>.COLOR MYGREEN</kbd>) or
the inline escape <kbd>\*[mygreen]</kbd> (or
<kbd>\*[MYGREEN]</kbd>.)
</p>
<p>
<strong>Please note:</strong> both the colorname and the
alias you give to <strong>XCOLOR</strong> may be used with
<strong>groff</strong>'s <kbd>\m[<colorname>]</kbd>
inline escape (the <kbd>\m</kbd> escape is used to set
text and rule colours). Thus, assuming an X-colorname
"mediumspringgreen" set with <strong>XCOLOR</strong>, and
an alias, "mygreen", <kbd>\*[mediumspringgreen]</kbd>,
<kbd>\m[mediumspringgreen]</kbd>, <kbd>\*[mygreen]</kbd> and
<kbd>\m[mygreen]</kbd> are all equivalent. Furthermore, both
the colorname and the alias can be given as an argument to
<strong>groff</strong>'s
<a href="definitions.html#TERMS_PRIMITIVES">primitive</a>
request, <kbd>.gcolor</kbd> (which does the same thing as
<kbd>\m[<colorname>]</kbd>).
</p>
<p>
The colorname initialized with <strong>XCOLOR</strong>
<em><strong><u>but not the alias</u></strong></em> may also
be used with <strong>groff</strong>'s inline escape,
<kbd>\M[<colorname>]</kbd>, and the corresponding primitive,
<kbd>.fcolor</kbd>, both of which set the "fill" colour
for solid graphical objects. If you need a colour initialized with
<strong>XCOLOR</strong> for <kbd>\M</kbd> or <kbd>.fcolor</kbd>, you
<strong>MUST</strong> give the full colorname; the alias won't work.
</p>
<a name="XCOLOR_NAMES"><h4><u>Finding X color names</u></h4></a>
<p>
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.
</p>
<p>
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.
</p>
<p>
Whichever method you use to find X color names, remember that the
names, passed as arguments to <strong>XCOLOR</strong>, <em>must</em>
be all one word, all in lower case.
</p>
<!-- -COLOR- -->
<hr width="33%" align="left"/>
<a name="COLOR"><h3><u>Invoking a color</u></h3></a>
<p>
<nobr>Macro: <strong>COLOR</strong> <kbd><colorname></kbd></nobr>
<br/>
<a name="COLOR_INLINE"><nobr>Inline: <kbd>\*[<colorname>]</kbd></nobr></a>
</p>
<a name="COLOR_INLINE"></a>
<p>
Once you've told <strong>mom</strong> about a colour (via
<a href="#NEWCOLOR">NEWCOLOR</a>
or
<a href="#XCOLOR">XCOLOR</a>,
you use either the macro, <strong>COLOR</strong>, or the
<a href="definitions.html#TERMS_INLINES">inline escape</a>,
<kbd>\*[<colorname>]</kbd>, to cause <strong>mom</strong> to
set subsequent text in that colour. See the
<a href="#COLOR_EXAMPLE2">example</a>,
above, which shows both in action.
</p>
<p>
<strong>NOTE:</strong> You can use the
<kbd>\*[<colorname>]</kbd> inline escape in any
<a href="docprocessing.html#TOP">document processing</a>
macro that takes a
<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>.
However, you must remember to reset the colour at the end of the
argument (typically with <kbd>\*[black]</kbd>) unless you want all
subsequent invocations of that particular macro to be colourized.
</p>
<p>
Furthermore, if you use <kbd>\*[<colorname>]</kbd> in the
string argument passed to
<a href="docelement.html#HEAD">HEAD</a>,
<a href="docelement.html#SUBHEAD">SUBHEAD</a>
or
<a href="docelement.html#PARAHEAD">PARAHEAD</a>,
and you've requested that any of these types of heads be numbered,
the numbers themselves will not be coloured, only the text you
passed the macro. If you wish the numbers to be colourized as
well, you must explicitly tell <strong>mom</strong> that you wish
all of the head(s), subhead(s) or parahead(s), including the
numbers, colourized by invoking the appropriate
<a href="docelement.html#DOCELEMENT_CONTROL">control macro</a>.
</p>
<p>
For colorizing underscored text, see
<a href="goodies.html#UNDERSCORE_COLOR">Colorizing underscored text</a>
in the notes at the end of
<a href="goodies.html#UNDERSCORE">UNDERSCORE</a>.
</p>
<hr/>
<p>
<a href="docprocessing.html#TOP">Next</a>
<a href="inlines.html#TOP">Prev</a>
<a href="#TOP">Top</a>
<a href="toc.html">Back to Table of Contents</a>
</p>
</body>
</html>
<!-- vim: fileencoding=latin1: nomodified:
-->
|
