[PATCH 14/52] man/curs_color.3x: Recast.

[G. Branden Robinson]

Content:
* Recast overview to tighten wording.
* Rename "Color Rendering" subsection to "Rendering" since it also
  discusses the composition of non-color attribute data.
* Add man page cross references to wide-character API alternative
  functions.
* Add forward reference when employing "HLS" term out of nowhere.

Style:
* Favor active voice over passive.
* Favor imperative mood over declarative when recommending action.
* Italicize item of terminology when introducing it.
* Set data type names in italics, not bold.

Markup:
* Break input lines after commas and colons and around multi-word
  parentheticals.

Also:

* man/man_db.renames.in: Add man page topic names to supplemental list.
---
 man/curs_color.3x     | 79 +++++++++++++++++++++++++------------------
 man/man_db.renames.in |  3 ++
 2 files changed, 50 insertions(+), 32 deletions(-)

diff --git a/man/curs_color.3x b/man/curs_color.3x
index d56419613..20b06288e 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -104,43 +104,55 @@ .SH SYNOPSIS
 .fi
 .SH DESCRIPTION
 .SS Overview
-\fIcurses\fP supports color attributes on terminals with that capability.
-To use these routines \fB\%start_color\fP must be called, usually right after
-\fB\%initscr\fP.
-Colors are always used in pairs (referred to as color pairs).
-A color pair consists of a foreground color (for characters) and a background
-color (for the blank field on which the characters are displayed).
-A programmer initializes a color pair with the routine \fB\%init_pair\fP.
-After it has been initialized, \fB\%COLOR_PAIR\fP(\fIn\fP)
-can be used to convert the pair to a video attribute.
+\fIcurses\fP supports color attributes on terminals with that
+capability.
+Call \fB\%start_color\fP
+(typically right after \fB\%initscr\fP(3X))
+to enable this feature.
+Colors are always used in pairs.
+A
+.I "color pair"
+couples a foreground color for characters with a background color for
+the blank field on which characters are rendered.
+\fB\%init_pair\fP initializes a color pair.
+The macro \fB\%COLOR_PAIR\fP(\fIn\fP) can then convert the pair to a
+video attribute.
 .PP
-If a terminal is capable of redefining colors, the programmer can use the
-routine \fB\%init_color\fP to change the definition of a color.
-The routines \fB\%has_colors\fP and \fB\%can_change_color\fP
+If a terminal has the relevant capability,
+\fB\%init_color\fP permits (re)definition of a color.
+\fB\%has_colors\fP and \fB\%can_change_color\fP
 return \fBTRUE\fP or \fBFALSE\fP,
-depending on whether the terminal has color capabilities and whether the
+depending on whether the terminal has color capability and whether the
 programmer can change the colors.
-The routine \fB\%color_content\fP allows a
-programmer to extract the amounts of red, green, and blue components in an
-initialized color.
-The routine \fB\%pair_content\fP allows a programmer to find
-out how a given color pair is currently defined.
-.SS Color Rendering
-The \fIcurses\fP library combines these inputs to produce the
-actual foreground and background colors shown on the screen:
+\fB\%color_content\fP permits extraction of the
+red,
+green,
+and blue components of an initialized color.
+\fB\%pair_content\fP permits discovery of a color pair's current
+definition.
+.SS Rendering
+.I curses
+combines the following data to render a character cell.
+Any of them can include color information.
 .bP
-per-character video attributes (e.g., via \fB\%waddch\fP),
+.I curses
+character attributes,
+as from \fB\%waddch\fP(3X) or \fB\%wadd_wch\fP(3X)
 .bP
-the window attribute (e.g., by \fB\%wattrset\fP), and
+window attributes,
+as from \fB\%wattrset\fP(3X) or \fB\%wattr_set\fP(3X)
 .bP
-the background character (e.g., \fB\%wbkgdset\fP).
+window background character atttributes,
+as from \fB\%wbkgdset\fP(3X) or \fB\%wbkgrndset\fP(3X)
 .PP
-Per-character and window attributes are usually set by a parameter containing
-video attributes including a color pair value.
-Some functions such as \fB\%wattr_set\fP use a separate parameter which
-is the color pair number.
+Per-character and window attributes are usually set through a function
+parameter containing attributes including a color pair value.
+Some functions,
+like \fB\%wattr_set\fP,
+use a separate color pair number parameter.
 .PP
-The background character is a special case: it includes a character value,
+The background character is a special case:
+it includes a character code,
 just as if it were passed to \fB\%waddch\fP.
 .PP
 The \fIcurses\fP library does the actual work of combining these color
@@ -199,12 +211,15 @@ .SS COLOR_PAIRS
 its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP,
 but this is not always true.
 .bP
-A few terminals use HLS colors,
+A few terminals use the HLS color space
+(see \fB\%start_color\fP below),
 ignoring this rule;
 and
 .bP
-terminals supporting a large number of colors are limited by the number
-of color pairs that a \fIsigned short\fP value can represent.
+terminals supporting a large number of colors are limited to the number
+of color pairs that a
+.I "signed short"
+value can represent.
 .SH FUNCTIONS
 .SS start_color
 The \fB\%start_color\fP routine requires no arguments.
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index fdc18a465..22840c5ca 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -240,7 +240,10 @@ wadd_wch.3x                        wadd_wch.3ncurses
 waddch.3x                      waddch.3ncurses
 waddstr.3x                     waddstr.3ncurses
 waddwstr.3x                    waddwstr.3ncurses
+wattrset.3x                    wattrset.3ncurses
+wattr_set.3x                   wattr_set.3ncurses
 wbkgdset.3x                    wbkgdset.3ncurses
+wbkgrndset.3x                  wbkgrndset.3ncurses
 wget_wch.3x                    wget_wch.3ncurses
 wgetch.3x                      wgetch.3ncurses
 wgetstr.3x                     wgetstr.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature