[groff] 03/19: [docs]: Update `defcolor` request description.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 91167df54a773fb20839c68ad5900b2e449d95b4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Sep 13 22:56:29 2021 +1000

    [docs]: Update `defcolor` request description.
---
 doc/groff.texi       | 53 +++++++++++++++---------------
 man/groff.7.man      | 70 +++++++++++++++++++++++++++------------
 man/groff_diff.7.man | 92 +++++++++++++++++++++++-----------------------------
 3 files changed, 117 insertions(+), 98 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 67b5347..0a22826 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -424,7 +424,7 @@ developing GNU and promoting software freedom.''
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0
-@subtitle August 2021
+@subtitle September 2021
 @author by Trent A.@tie{}Fisher
 @author and Werner Lemberg
 
@@ -14357,41 +14357,40 @@ beginning of your document to control color output.
 Colors can be also turned off with the @option{-c} command-line option.
 @endDefreq
 
-@Defreq {defcolor, ident scheme color_components}
-Define color with name @var{ident}.  @var{scheme} can be one of the
-following values: @code{rgb} (three components), @code{cmy} (three
-components), @code{cmyk} (four components), and @code{gray} or
-@code{grey} (one component).
+@Defreq {defcolor, ident scheme color-component @dots{}}
+Define a color named @var{ident} for use with the @code{fcolor} and
+@code{gcolor} requests and the @code{\m} and @code{\M} escape sequences.
+@var{scheme} identifies a color space and determines the number of
+required @var{color-component}s; it must be one of @samp{rgb} (three
+components), @samp{cmy} (three components), @samp{cmyk} (four
+components), or @samp{gray} (one component). @samp{grey} is accepted as
+a synonym of @samp{gray}.  The color components can be encoded as a
+hexadecimal value starting with @samp{#} or @samp{##}.  The former
+indicates that each component is in the range 0--255 (0--FF), the latter
+the range 0--65535 (0--FFFF).
 
-@cindex default color
-@cindex color, default
-Color components can be given either as a hexadecimal string or as
-positive decimal integers in the range 0--65535.  A hexadecimal string
-contains all color components concatenated.  It must start with either
-@code{#} or @code{##}; the former specifies hex values in the range
-0--255 (which are internally multiplied by@tie{}257), the latter in the
-range 0--65535.  Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
-(magenta).  The default color name @c{default} can't be redefined; its
-value is device-specific (usually black).  It is possible that the
-default color for @code{\m} and @code{\M} is not identical.
+@Example
+.defcolor half gray #7f
+.defcolor pink rgb #FFC0CB
+.defcolor magenta rgb  ##ffff0000ffff
+@endExample
 
 @cindex @code{f} unit, and colors
 @cindex unit, @code{f}, and colors
-A new scaling indicator@tie{}@code{f} has been introduced, which
-multiplies its value by 65536; this makes it convenient to specify color
-components as fractions in the range 0 to@tie{}1 (1f equals 65536u).
-Example:
+Alternatively, each color component can be specified as a decimal
+fraction in the range 0--1, interpreted using a default scaling
+indicator of@tie{}@code{f}, which multiplies its value by 65536.
 
 @Example
+.defcolor gray50 rgb 0.5 0.5 0.5
 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
 @endExample
 
-Note that @code{f} is the default scaling indicator for the
-@code{defcolor} request, thus the above statement is equivalent to
-
-@Example
-.defcolor darkgreen rgb 0.1 0.5 0.2
-@endExample
+@cindex default color
+@cindex color, default
+Each output device has a color named @samp{default} that cannot be
+redefined.  A device's default drawing and fill colors are not
+necessarily the same.
 @endDefreq
 
 @DefreqList {gcolor, [@Var{color}]}
diff --git a/man/groff.7.man b/man/groff.7.man
index b1e5b43..13f01aa 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1691,29 +1691,59 @@ Same as
 .request .de
 but with compatibility mode switched off during macro expansion.
 .
+.
 .TPx
-.REQ .defcolor "color scheme component"
-Define or redefine a color with name
-.IR color .
+.REQ .defcolor "ident scheme color-component \f[R].\|.\|."
+Define a color named
+.I ident
+for use with the
+.B fcolor
+and
+.B gcolor
+requests and the
+.B \[rs]m
+and
+.B \[rs]M
+escape sequences.
+.
 .I scheme
-can be
-.BR rgb ,
-.BR cym ,
-.BR cymk ,
-.BR gray ,
+identifies a color space and determines the number of required
+.IR color-component s;
+it must be one of
+.RB \[lq] rgb \[rq]
+(three components),
+.RB \[lq] cmy \[rq]
+(three components),
+.RB \[lq] cmyk \[rq]
+(four components),
 or
-.BR grey .
-.I component
-can be single components specified as fractions in the range 0 to 1
-(default scaling indicator\~\c
-.scaleindicator f ),
-as a string of two-digit hexadecimal color components with a leading
-.BR # ,
-or as a string of four-digit hexadecimal components with two leading
-.BR # .
-The color
-.B default
-can't be redefined.
+.RB \[lq] gray \[rq]
+(one component).
+.
+.RB \[lq] grey \[rq]
+is accepted as a synonym of
+.RB \[lq] gray \[rq].
+.
+The color components can be encoded as a hexadecimal value starting
+with
+.B #
+or
+.BR ## .
+.
+The former indicates that each component is in the range 0\[en]255
+(0\[en]FF),
+the latter the range 0\[en]65535 (0\[en]FFFF).
+.
+Alternatively,
+each color component can be specified as a decimal fraction in the range
+0\[en]1,
+interpreted using a default scaling indicator
+.RB of\~\[lq] f \[rq].
+.
+Each output device has a color named
+.RB \[lq] default \[rq]
+that cannot be redefined.
+.
 .
 .TPx
 .REQ .dei "macro"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 3a08f4d..c9797b5 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1734,75 +1734,65 @@ it.
 In compatibility mode, long names are not recognized, and the
 incompatibilities caused by long names do not arise.
 .
+.
 .TP
-.BI .defcolor\~ xxx\~scheme\~color_components
-Define color
-.IR xxx .
+.B .defcolor\~\c
+.IR "ident scheme color-component\~" .\|.\|.
+Define a color named
+.I ident
+for use with the
+.B fcolor
+and
+.B gcolor
+requests and the
+.B \[rs]m
+and
+.B \[rs]M
+escape sequences.
+.
 .I scheme
-can be one of the following values:
-.B rgb
+identifies a color space and determines the number of required
+.IR color-component s;
+it must be one of
+.RB \[lq] rgb \[rq]
 (three components),
-.B cmy
+.RB \[lq] cmy \[rq]
 (three components),
-.B cmyk
-(four components), and
-.B gray
+.RB \[lq] cmyk \[rq]
+(four components),
 or
-.B grey
+.RB \[lq] gray \[rq]
 (one component).
 .
-Color components can be given either as a hexadecimal string or as
-positive decimal integers in the range 0\[en]65535.
+.RB \[lq] grey \[rq]
+is accepted as a synonym of
+.RB \[lq] gray \[rq].
 .
-A hexadecimal string contains all color components concatenated; it
-must start with either
+The color components can be encoded as a hexadecimal value starting
+with
 .B #
 or
 .BR ## .
-The former specifies hex values in the range 0\[en]255 (which are
-internally multiplied by\~257), the latter in the range 0\[en]65535.
-.
-Examples: #FFC0CB (pink), ##ffff0000ffff (magenta).
-.
-A new scaling indicator,
-.RB \[lq] f \[rq]\~has
-has been introduced which multiplies its value by\~65536;
-this makes it convenient to specify color components as fractions in the
-range 0 to\~1.
 .
-Example:
+The former indicates that each component is in the range 0\[en]255
+(0\[en]FF),
+the latter the range 0\[en]65535 (0\[en]FFFF).
 .
-.RS
-.IP
-.EX
-\&.defcolor darkgreen rgb 0.1f 0.5f 0.2f
-.EE
-.RE
+Alternatively,
+each color component can be specified as a decimal fraction in the range
+0\[en]1,
+interpreted using a default scaling indicator
+.RB of\~\[lq] f \[rq],
+which multiplies its value by 65536.
 .
-.IP
-Note that
-.B f
-is the default scaling indicator for the
-.B defcolor
-request, thus the above statement is equivalent to
 .
-.RS
 .IP
-.EX
-\&.defcolor darkgreen rgb 0.1 0.5 0.2
-.EE
-.RE
+Each output device has a color named
+.RB \[lq] default \[rq]
+that cannot be redefined.
 .
-.IP
-The color named
-.B default
-(which is device-specific) can't be redefined.
+A device's default drawing and fill colors are not necessarily the same.
 .
-It is possible that the default color for
-.B \[rs]M
-and
-.B \[rs]m
-is not the same.
 .
 .TP
 .BI .de1\~ xx\~yy