contrib/groff/contrib/mom/momdoc/color.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   5 <title>Mom -- Colour</title>
   6 </head>
   7 <body bgcolor="#dfdfdf">
   8
   9 <!====================================================================>
  10
  11 <a href="docprocessing.html#TOP">Next</a>&nbsp;&nbsp;
  12 <a href="inlines.html#TOP">Prev</a>&nbsp;&nbsp;
  13 <a href="toc.html">Back to Table of Contents</a>
  14
  15 <a name="TOP"></a>
  16 <h1 align="center">
  17     <a name="COLOR_INTRO"><u>Coloured text</u></a>
  18 </h1>
  19 <p>
  20 <a href="#INTRO_COLOR">Introduction to coloured text</a>
  21 <br>
  22 <a href="#MACROS_COLOR">Index of colour macros</a>
  23 <p>
  24
  25 <a name="INTRO_COLOR">
  26         <h2><u>Introduction to coloured text</u></h2>
  27 </a>
  28
  29 <strong>Mom</strong>'s support for coloured text is straightforward.
  30 You begin by telling <strong>mom</strong> about the colours you want
  31 with
  32 <a href="#NEWCOLOR">NEWCOLOR</a>
  33 or
  34 <a href="#XCOLOR">XCOLOR</a>.
  35 Afterward, any time you want text to be coloured, you either colour
  36 it with an
  37 <a href="definitions.html#TERMS_INLINES">inline escape</a>
  38 that contains the colour name (e.g. <kbd>\*[red]</kbd> or
  39 <kbd>\*[blue]</kbd>) or invoke the macro,
  40 <a href="#COLOR">COLOR</a>,
  41 with the name of the colour you want.
  42 <a name="COLOR_EXAMPLE"></a>
  43 <p>
  44 For example, say you want to have the name &quot;Jack&quot; in the
  45 sentence &quot;All work and no play makes Jack a dull boy&quot;
  46 appear in yellow.  You'd begin by telling <strong>mom</strong> about
  47 the colour, yellow.  There are two ways of doing this; see
  48 <a href="#NEWCOLOR">NEWCOLOR</a>
  49 and
  50 <a href="#XCOLOR">XCOLOR</a>
  51 for a full explanation of the difference between the two.  If you
  52 use <strong>XCOLOR</strong>, you'd enter this:
  53 <p>
  54 <pre>
  55         .XCOLOR yellow
  56 </pre>
  57
  58 If you use <strong>NEWCOLOR</strong>, you might enter
  59 <p>
  60 <pre>
  61         .NEWCOLOR yellow RGB #FFFF00
  62 </pre>
  63
  64 <a name="COLOR_EXAMPLE2"></a>
  65 After &quot;defining&quot; (or &quot;initializing&quot;) the colour
  66 &quot;yellow&quot;, you'd colourize the name, Jack, either with an
  67 inline escape
  68 <p>
  69 <pre>
  70         All work and no play makes \*[yellow]Jack\*[black] a dull boy.
  71 </pre>
  72
  73 or with the <strong>COLOR</strong> macro
  74 <p>
  75 <pre>
  76         All work and no play makes
  77         .COLOR yellow
  78         Jack
  79         .COLOR black
  80         a dull boy.
  81 </pre>
  82
  83 Notice, in both examples, that a) you have to set the colour back to
  84 black after &quot;Jack&quot;, and b) you don't have to define or
  85 intialize the colour, black.  <strong>Mom</strong> predefines
  86 &quot;black&quot;, &quot;BLACK&quot;, &quot;white&quot; and
  87 &quot;WHITE&quot; for you.
  88 <p>
  89 For information on using colour during
  90 <a href="docprocessing.html#INTRO_MACROS_DOCPROCESSING">document processing</a>,
  91 see
  92 <a href="docprocessing.html#COLOR">Colour support in document processing</a>.
  93 <p>
  94 <strong>Please note: Mom</strong>'s colour support is for text only.
  95 She doesn't support &quot;fill&quot; (or &quot;background&quot;)
  96 colour for drawn objects.  Please also note that if you're
  97 accustomed to using groff's <kbd>.defcolor</kbd> to define colours,
  98 and groff's inline <kbd>\m[&lt;colorname&gt;]</kbd> to call them, you may
  99 continue to do so without confusing <strong>mom</strong>.
 100
 101 <p>
 102 <a name="MACROS_COLOR"><h3><u>Index of colour macros</u></h3></a>
 103 <ul>
 104     <li><a href="#NEWCOLOR">NEWCOLOR</a>
 105     <li><a href="#XCOLOR">XCOLOR</a>
 106     <li><a href="#COLOR">COLOR</a>
 107     <li><a href="#COLOR_INLINE">\*[&lt;colorname&gt;]</a> inline escape
 108 </ul>
 109 <p>
 110
 111 <!---NEWCOLOR--->
 112
 113 <hr width="66%" align="left">
 114 <a name="NEWCOLOR"><h3><u>Creating (initializing) a colour with NEWCOLOR</u></h3></a>
 115 <br>
 116 <nobr>Macro: <strong>NEWCOLOR</strong> &lt;colour name&gt; [&lt;colour scheme&gt;] &lt;colour components&gt;</nobr>
 117
 118 <p>
 119 <strong>NEWCOLOR</strong> lets you create a colour, rather like an
 120 artist mixing paint on a palette.  The colour isn't used
 121 immediately; <strong>NEWCOLOR</strong> merely tells
 122 <strong>mom</strong> how to mix the colour when you need it.  If
 123 you haven't invoked <strong>NEWCOLOR</strong> (or
 124 <a href="#XCOLOR">XCOLOR</a>),
 125 <strong>mom</strong> doesn't have a clue what you mean when you
 126 reference a colour (with
 127 <a href="#COLOR">COLOR</a>
 128 or
 129 <a href="#COLOR_INLINE">\*[&lt;color name&gt;]</a>).
 130 <p>
 131 The first argument to <strong>NEWCOLOR</strong> is a name for your
 132 colour.  It can be anything you like--provided it's just one word
 133 long--and can be caps, lower case, or any combination of the two.
 134 <p>
 135 The second argument, which is entirely optional, is the &quot;colour
 136 scheme&quot; you want <strong>mom</strong> to use when mixing the
 137 colour.  Valid arguments are <strong>RGB</strong> (3 components,
 138 red green blue), <strong>CYM</strong> (3 components cyan yellow
 139 magenta), <strong>CMYK</strong> (4 components cyan magenta yellow
 140 black) or <strong>GRAY</strong> (1 component).  If you omit the
 141 second argument, <strong>mom</strong> assumes you want RGB.
 142 <p>
 143 The final argument is the components of your colour.  This can be
 144 hexadecimal string starting with a pound sign (#) (for colour values
 145 in the 0-255 range) or two pound signs (##) (for colour values
 146 in the 0-65535 range), or it can be a series of decimal digits,
 147 separated by spaces, one digit per component, with the argument
 148 enclosed in double quotes.  (If this is all gibberish to you, see
 149 <a href="#COLOR_TIP">Tips for newbies</a>.)
 150 <p>
 151 Thus, to tell <strong>mom</strong> about a colour named
 152 &quot;YELLOW&quot;, you could enter one of the following:
 153 <p>
 154 <pre>
 155         .NEWCOLOR YELLOW #FFFF00         \"or ##FFFFFFFF0000 or "1 1 0"
 156         .NEWCOLOR YELLOW RGB #FFFF00     \"or ##FFFFFFFF0000 or "1 1 0"
 157         .NEWCOLOR YELLOW CYM #00FF00     \"or ##0000FFFF0000 or "0 1 0"
 158         .NEWCOLOR YELLOW CYMK #00FF0000  \"or ##0000FFFF00000000 or "1 1 0"
 159 </pre>
 160
 161 After you've told <strong>mom</strong> about a colour, you can then get
 162 her to set text in that colour either with the inline escape
 163 <a href="#COLOR_INLINE">\*[&lt;colorname&gt;]</a>
 164 or the macro
 165 <a href="#COLOR">COLOR</a>.
 166 (See the
 167 <a href="#COLOR_EXAMPLE">example</a>,
 168 above.)
 169 <br>
 170 <h3><u>Tips for newbies</u></h3>
 171 Colour manipulation can be tremendously confusing if you don't have
 172 a background in graphic arts or computing.  My advice, if color
 173 intimidates you, is to stick to using <strong>mom</strong>'s
 174 default RGB colour scheme, and to fire up a color chooser that
 175 gives you the RGB values you want for the colour you select.  Plug
 176 those values into the components argument to
 177 <strong>NEWCOLOR</strong>, and you'll get the colour you want.
 178 Both the KDE and gnome desktops have colour selectors that provide
 179 you with the shorter RGB hexadecimal string.  If you're not running
 180 KDE or gnome, the X utility, xcolorsel, provides you with a similar
 181 functionality, although it only provides RGB values for 256
 182 pre-defined colours.  If you use xcolorsel, be sure to click the
 183 button &quot;Display format&quot; and select &quot;8 bit truncated
 184 rgb&quot;.
 185 <p>
 186 Alternatively, you can use <strong>mom</strong>'s simpler
 187 <a href="#XCOLOR">XCOLOR</a>
 188 macro to initialize one of the 256 pre-defined X colours by
 189 supplying the name of the color as an argument.
 190 <br>
 191
 192 <!---XCOLOR--->
 193
 194 <hr width="33%" align="left">
 195 <a name="XCOLOR"><h3><u>Initializing a colour with XCOLOR</u></h3>
 196 <br>
 197 <nobr>Macro: <strong>XCOLOR</strong> &lt;X color name&gt; [&lt;alias&gt;]</nobr>
 198 <br>
 199 <em>*&lt;X color name&gt; must be all one word, all lower case.
 200 <br>
 201 (See
 202 <a href="#XCOLOR_NAMES">Finding X color names</a>
 203 for how to get a list of valid colour names.)
 204 </em>
 205 <p>
 206 <strong>XCOLOR</strong> is similar to <strong>NEWCOLOR</strong> in
 207 that it tells <strong>mom</strong> to initialize a colour, but it's
 208 easier to use.  All you have to do is pass it, as an argument, the
 209 legal name of one of the 256 pre-defined X colours.  The name must
 210 be all one word, and, breaking with <strong>mom</strong> policy, it
 211 must be entered in lower case.
 212 <p>
 213 For example, if you want to intialize the X colour, coral, all you
 214 have to do is enter
 215 <br>
 216 <pre>
 217         .XCOLOR coral
 218 </pre>
 219
 220 Afterwards
 221 <p>
 222 <pre>
 223         .COLOR coral
 224 </pre>
 225
 226 will colourize subsequent text coral until you instruct
 227 <strong>mom</strong> to return to black, or some other pre-defined
 228 initialized colour.  (The
 229 <a href="definitions.html#TERMS_INLINES">inline escape</a>
 230 <kbd>\*[coral]</kbd> will equally colourize text coral after you've
 231 initialized the colour with <strong>XCOLOR</strong>.)
 232 <p>
 233 The downside of <strong>XCOLOR</strong> is that you can't create
 234 custom colours.  This restriction, however, is mitigated by the
 235 fact that for many users, 256 colours is more than enough to play
 236 around with.
 237 <p>
 238 While some X colours have fanciful names (peachpuff, papayawhip,
 239 thistle, snow), many are self-explanatory and self-descriptive in
 240 ordinary colour terms.  &quot;blue&quot; is pure (rgb) blue,
 241 &quot;green&quot; is pure (rgb) green, and so on.  Furthermore, for
 242 many X colors, there exist four variants, each representing
 243 increasingly darker shades of the same colour.  For example,
 244 &quot;blue&quot; (and &quot;blue1&quot;) are the brightest forms of
 245 (rgb) blue; &quot;blue2&quot;, &quot;blue3&quot; and &quot;blue4&quot;
 246 are increasingly darker shades of the same blue.  For that reason,
 247 you may find <strong>XCOLOR</strong> is a better choice than
 248 <strong>NEWCOLOR</strong> when it comes to initializing common
 249 colors.
 250 <p>
 251 The whimsical nature of X colour names sometimes makes for names
 252 that are long to type in, e.g. &quot;mediumspringgreen&quot;.
 253 The optional second argument to <strong>XCOLOR</strong> allows you
 254 to come up with more convenient name by which to reference the
 255 colour.  For example, you could enter
 256 <p>
 257 <pre>
 258         .XCOLOR mediumspringgreen mygreen
 259             or
 260         .XCOLOR mediumspringgreen MYGREEN
 261 </pre>
 262
 263 so that whenever you want text mediumspringgreen-ed, you can use
 264 either <kbd>.COLOR mygreen</kbd> (or <kbd>.COLOR MYGREEN</kbd>) or
 265 the inline escape <kbd>\*[mygreen]</kbd> (or
 266 <kbd>\*[MYGREEN]</kbd>.)
 267 <p>
 268 <a name="XCOLOR_NAMES"><h3><u>Finding X color names</u></h3></a>
 269 <br>
 270 There are two ways of finding the names of the pre-defined X
 271 colours.  One is to consult the file, rgb.txt, included with
 272 all X11 installations.  The location of the file on a Debian
 273 GNU/Linux distribution is typically /etc/X11/rgb.txt.  Other
 274 distributions and other X installations may have the file in
 275 another location.  The file lists the colour names, but doesn't
 276 show you what the colours actually look like.
 277 <p>
 278 A better way to get the colour names, as well as to see what the
 279 colours look like, is to fire up a colour chooser (like xcolorsel)
 280 that both lists the colour names and shows a swatch of the colour
 281 as well.
 282 <p>
 283 Whichever method you use to find X color names, remember that the
 284 names, passed as arguments to <strong>XCOLOR</strong>, <em>must</em>
 285 be all one word, all in lower case.
 286 <br>
 287
 288 <!---COLOR--->
 289
 290 <hr width="33%" align="left">
 291 <a name="COLOR"><h3><u>Invoking a color</u></h3>
 292 <br>
 293 <nobr>Macro: <strong>COLOR</strong> &lt;colorname&gt;</nobr>
 294 <br>
 295 <a name="COLOR_INLINE">Inline: <strong>\*[&lt;colorname&gt;]</strong></a>
 296 <p>
 297 <a name="COLOR_INLINE"></a>
 298 Once you've told <strong>mom</strong> about a colour (via
 299 <strong>NEWCOLOR</strong> or <strong>XCOLOR</strong>), you use either
 300 the macro, <strong>COLOR</strong>, or the
 301 <a href="definitions.html#TERMS_INLINES">inline escape</a>,
 302 <kbd>\*[&lt;colorname&gt;]</kbd>, to cause <strong>mom</strong> to
 303 set subsequent text in that colour.  See the
 304 <a href="#COLOR_EXAMPLE2">example</a>,
 305 above, which shows both in action.
 306 <p>
 307 <strong>NOTE:</strong> You can use the
 308 <kbd>\*[&lt;colorname&gt;]</kbd> inline escape in any
 309 <a href="docprocessing.html#TOP">document processing</a>
 310 macro that takes a
 311 <a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>.
 312 However, you must remember to reset the colour at the end of the
 313 argument (typically with <kbd>\*[black]</kbd>) unless you want all
 314 subsequent invocations of that particular macro to be colourized.
 315 <p>
 316 Furthermore, if you use <kbd>\*[&lt;colorname&gt;]</kbd> in the
 317 string argument passed to
 318 <a href="docelement.html#HEAD">.HEAD</a>,
 319 <a href="docelement.html#SUBHEAD">.SUBHEAD</a>
 320 or
 321 <a href="docelement.html#PARAHEAD">.PARAHEAD</a>,
 322 and you've requested that any of these types of heads be numbered,
 323 the numbers themselves will not be coloured, only the text you
 324 passed the macro.  If you wish the numbers to be colourized as
 325 well, you must explicitly tell <strong>mom</strong> that you wish
 326 all of the head(s), subhead(s) or parahead(s), including the
 327 numbers, colourized by invoking the appropriate
 328 <a href="docelement.html#DOCELEMENT_CONTROL">control macro</a>.
 329
 330 <br>
 331
 332 <hr>
 333 <a href="docprocessing.html#TOP">Next</a>&nbsp;&nbsp;
 334 <a href="inlines.html#TOP">Prev</a>&nbsp;&nbsp;
 335 <a href="#TOP">Top</a>&nbsp;&nbsp;
 336 <a href="toc.html">Back to Table of Contents</a>
 337 </body>
 338 </html>