contrib/mom/momdoc/color.html

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