diff options
Diffstat (limited to 'contrib/mom/momdoc/color.html')
| -rw-r--r-- | contrib/mom/momdoc/color.html | 505 |
1 files changed, 505 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html new file mode 100644 index 0000000..f53b5c0 --- /dev/null +++ b/contrib/mom/momdoc/color.html @@ -0,0 +1,505 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004-2020 Free Software Foundation, Inc. +Written by Peter Schaffter (peter@schaffter.ca). + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, 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=utf-8"/> + <title>Mom -- Colour</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="graphical.html#top">Next: Graphical objects</a></td> +</tr> +</table> + +<h1 class="docs">Coloured text</h1> + +<div style="text-align: center;"> +<a href="#index-color">List of color macros</a> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 class="docs">Introduction</h2> + +<p> +Mom’s support for coloured text is straightforward. You begin +by telling mom about the colours you want with +<a href="#newcolor">NEWCOLOR</a> +or +<a href="#xcolor">XCOLOR</a>. +Afterwards, any time you want text to be coloured, you either colour +it with an +<a href="definitions.html#inlines">inline escape</a> +that contains the colour name (e.g. <kbd><span class="nobr">\*[red]</span></kbd> +or <kbd><span class="nobr">\*[blue]</span></kbd>) or invoke the macro +<a href="#color">COLOR</a> +with the name of the colour you want. +</p> + +<p id="color-example"> +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 +<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 XCOLOR, you’d enter this: +<br/> +<span class="pre-in-pp"> + .XCOLOR yellow +</span> +If you use NEWCOLOR, you might enter: +<br/> +<span class="pre-in-pp"> + .NEWCOLOR yellow RGB #FFFF00 +</span> +</p> + +<p id="color-example2" style="margin-top: -1em;"> +After defining or initializing the colour yellow you’d +colourise the name, Jack, either with an inline escape +<br/> +<span class="pre-in-pp"> + All work and no play makes \*[yellow]Jack\*[black] a dull boy. +</span> +or with the +<a href="#color">COLOR</a> +macro +<br/> +<span class="pre-in-pp"> + All work and no play makes + .COLOR yellow + Jack + .COLOR black + a dull boy. +</span> +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. +</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> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +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 <kbd>\D</kbd> +<a href="definitions.html#inlines">inline escapes</a>, +although you may give a colour as one of the arguments to +mom’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> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +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 mom. +</p> +</div> + +<div class="macro-list-container"> +<h3 id="index-color" class="macro-list">Coloured text macros</h3> + +<ul class="macro-list"> + <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">\*[<colourname>]</a> (inline escape)</li> +</ul> +</div> + +<div class="rule-medium" style="margin-bottom: 1.5em;"><hr/></div> + +<!-- -NEWCOLOR- --> + +<div class="macro-id-overline"> +<h3 id="newcolor" class="macro-id">Creating (initializing) a colour with NEWCOLOR</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>NEWCOLOR</b> <kbd class="macro-args"><colour name> [<colour scheme>] <colour components></kbd> +</div> + +<p> +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 <kbd>.NEWCOLOR</kbd> (or +<kbd><a href="#xcolor">.XCOLOR</a></kbd>), +mom 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><span class="nobr">\*[<colour name>]</span></kbd></a>). +</p> + +<p> +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. +</p> + +<p> +The second argument, which is entirely optional, is the +“colour scheme” you want mom to use when mixing the +colour. Valid arguments are +<br/> +<span class="pre-in-pp"> + RGB (3 components: red green blue) + CYM (3 components: cyan yellow magenta) + CMYK (4 components: cyan magenta yellow black) + GRAY (1 component) +</span> +If you omit the second argument, mom assumes you +want RGB. +</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 mom about a colour named “YELLOW”, you +could enter one of the following: +<br/> +<span class="pre-in-pp"> + .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" +</span> +After you’ve told mom about a colour, you can then get her to +set text in that colour either with the +<a href="definitions.html#inlines">inline escape</a>, +<a href="#color-inline"><kbd><span class="nobr">\*[<colourname>]</span></kbd></a>, +or the macro +<a href="#color">COLOR</a>. +(See the +<a href="#color-example">example</a>, +above.) +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +The colourname you give to NEWCOLOR may be used with groff’s +<kbd>\m[<colourname>]</kbd> inline escape (the <kbd>\m</kbd> +escape is used to set text and rule colours). Thus, assuming +a colourname “blueblack” set with NEWCOLOR, +<kbd><span class="nobr">\*[blueblack]</span></kbd> and <kbd>\m[blueblack]</kbd> +are equivalent. Furthermore, the colourname can be given as an +argument to <b>groff</b>’s +<a href="definitions.html#primitives">primitive</a> +request, <kbd>.gcolor</kbd> (which does the same thing as +<kbd>\m[<colourname>]</kbd>). +</p> + +<p class="tip-bottom"> +Equally, the colourname may be used with +<kbd>\M[<colourname>]</kbd> and <kbd>.fcolor</kbd>, which set +the “fill” colour for solid graphical objects. +</p> +</div> + +<div class="box-tip"> +<p id="color-tip" class="tip-top"> +<span class="tip">Tips for newbies:</span> +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”. +</p> + +<p class="tip-bottom"> +Alternatively, you can use mom’s simpler +<kbd><a href="#xcolor">XCOLOR</a></kbd> +macro to initialize one of the 256 pre-defined X colours by +supplying the name of the colour as an argument. +</p> +</div> + +<!-- -XCOLOR- --> + +<div class="macro-id-overline"> +<h3 id="xcolor" class="macro-id">Initializing a colour with XCOLOR</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>XCOLOR</b> <kbd class="macro-args"><X colourname> [<alias>]</kbd> +</div> + +<p class="requires"> +<kbd style="font-style: normal"><X colourname></kbd> <i>must be all one word, all lower case.</i> +<br/> +(See +<a href="#xcolor-names" style="font-style: normal;">Finding X colour names</a> +for how to get a list of valid colour names.) +</p> + +<p> +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. +</p> + +<p> +For example, if you want to initialize the X colour, coral, all you +have to do is enter +<br/> +<span class="pre-in-pp"> + .XCOLOR coral +</span> +Afterwards +<br/> +<span class="pre-in-pp"> + .COLOR coral +</span> + +will colourise subsequent text coral until you instruct mom to +return to black, or some other pre-defined, initialized colour. +(The +<a href="definitions.html#inlines">inline escape</a> +<kbd><span class="nobr">\*[coral]</span></kbd> will equally colourise text coral +after you’ve initialized the colour with XCOLOR.) +</p> + +<p> +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. +</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 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. +</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 XCOLOR allows you to come up with more +convenient name by which to reference the colour. For example, you +could enter +<br/> +<span class="pre-in-pp"> + .XCOLOR mediumspringgreen mygreen +</span> +or +<span class="pre-in-pp"> + .XCOLOR mediumspringgreen MYGREEN +</span> +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> + +<h3 id="xcolor-names" class="docs">Finding X colour names</h3> + +<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 colour names, remember that the +names, passed as arguments to XCOLOR, must be all one word, all in +lower case. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Both the colourname and the alias you give to XCOLOR may be +used with groff’s <kbd>\m[<colourname>]</kbd> +inline escape (the <kbd>\m</kbd> escape is used to set +text and rule colours). Thus, assuming an X-colourname +“mediumspringgreen” set with +XCOLOR, and an alias, “mygreen”, +<kbd><span class="nobr">\*[mediumspringgreen]</span></kbd>, +<kbd><span class="nobr">\m[mediumspringgreen]</span></kbd>, +<kbd><span class="nobr">\*[mygreen]</span></kbd> and +<kbd><span class="nobr">\m[mygreen]</span></kbd> are all equivalent. +Furthermore, both the colourname and the alias can be given as an +argument to groff’s +<a href="definitions.html#primitives">primitive</a> +request, <kbd>.gcolor</kbd> (which does the same thing as +<kbd><span class="nobr">\m[<colourname>]</span></kbd>). +</p> + +<p class="tip-bottom"> +The colourname initialized with XCOLOR <i>but not the +alias</i> may also be used with groff’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 +XCOLOR for <kbd>\M</kbd> or <kbd>.fcolor</kbd>, you MUST give the +full colourname; the alias won’t work. +</p> +</div> + +<!-- -COLOR- --> + +<div class="macro-id-overline"> +<h3 id="color" class="macro-id">Invoking a colour</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>COLOR</b> <kbd class="macro-args"><colourname></kbd> +</div> + +<p id="color-inline" class="requires" style="font-style: normal;"> +Inline: <kbd>\*[<colourname>]</kbd> +</p> + +<p> +Once you’ve told mom about a colour (via +<a href="#newcolor">NEWCOLOR</a> +or +<a href="#xcolor">XCOLOR</a>, +you use either the macro COLOR or the +<a href="definitions.html#inlines">inline escape</a>, +<kbd><span class="nobr">\*[<colourname>]</span></kbd>, to cause mom to set +subsequent text in that colour. See the +<a href="#color-example2">example</a>, +above, which shows both in action. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +You can use the <kbd><span class="nobr">\*[<colourname>]</span></kbd> +inline escape in any +<a href="docprocessing.html#top">document processing</a> +macro that takes a +<a href="definitions.html#stringargument">string argument</a>. +However, you must remember to reset the colour at the end of the +argument (typically with <kbd><span class="nobr">\*[black]</span></kbd>) unless +you want all subsequent invocations of that particular macro to be +colourised. +</p> + +<p> +Furthermore, if you use +<kbd><span class="nobr">\*[<colourname>]</span></kbd> in the string +argument passed to +<a href="docelement.html#heading">HEADING <n></a> +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 +<a href="docelement.html#heading-style">HEADING_STYLE <n></a>. +</p> + +<p class="tip-bottom"> +For colourising underscored text, see +<a href="goodies.html#underscore-color">Colourising underscored text</a> +in the notes at the end of +<a href="goodies.html#underscore">UNDERSCORE</a>. +</p> +</div> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="graphical.html#top">Next: Graphical objects</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> |