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