[PATCH 092/177] man/curs_color.3x: Revise "HISTORY" section.

[G. Branden Robinson]

Content:
* Push back some observations of the implementation from SVr4 to SVr3.2;
  annotate them.  Add detail.
* More carefully refer to character _codes_, rather than "characters",
  where significant.  Synecdoche is best avoided in technical
  documentation.
* Put a date on ncurses 5.3, for perspective relative to subsequent
  developments.
* Update state of affairs in NetBSD curses.  It seems to use 9 bits for
  a color pair identifier, not 10 (not a change, but an error on this
  man page's part, it seems).

Style:
* Drop legal contract-esque conceit of spelling out words followed by
  their representations in parenthesized numerals.
* Improve hyphen usage.  For example, don't use them to make noun
  phrases out of things that aren't.  We don't say, "I have two-cats."

Markup:
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references (because
  man/make_sed.sh recognizes only certain patterns when rewriting such
  cross references) and terms in the "NAME" section (because the
  generated edit_man.sh script expects font selection escape sequences
  when scraping terms thence to gather names for man page aliases).
---
 man/curs_color.3x | 121 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 85 insertions(+), 36 deletions(-)

diff --git a/man/curs_color.3x b/man/curs_color.3x
index a2844579f..f6c74448e 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -646,56 +646,105 @@ .SH PORTABILITY
 .I \%ncurses
 does neither.
 .SH HISTORY
-SVr3.2 introduced color support to curses in 1987.
-.PP
-SVr4 made internal changes,
-e.g., moving the storage for the color state
-from \fBSP\fP (the \fISCREEN\fP structure)
-to \fB\%cur_term\fP (the \fI\%TERMINAL\fP structure),
-but provided the same set of library functions.
-.PP
-SVr4 curses limits the number of color pairs to 64,
-reserving color pair zero (0) as the terminal's initial uncolored state.
-This limit arises because the color pair information is a bitfield
-in the \fB\%chtype\fP data type (denoted by \fB\%A_COLOR\fP).
+SVr3.2 (1987) introduced color support with all of the symbols in the
+synopsis above except those marked as extensions.
+It reserved color pair 0 as the terminal's initial,
+\*(``uncolored\*('' state,
+.\" "we assume that color 0 is always a default background.", SVr3.2
+.\" usr/src/lib/libcurses/screen/start_col.c
+and limited the number of possible color pairs to 64,
+because the color pair datum was encoded in six bits of a
+.IR \%chtype "."
 .PP
-Other implementations of curses had different limits:
+SVr4 made only internal changes,
+such as moving the storage of color state
+from the
+.I SCREEN
+structure
+(pointed to by
+.IR SP )
+to the
+.I \%TERMINAL
+structure
+(pointed to by
+.IR \%cur_term ")."
+.PP
+Other
+.I curses
+implementations impose different limits on the number of colors and
+color pairs.
 .bP
 .I \%PCCurses
-(1987-1990) provided for only eight (8) colors.
+(1987-1990) provided for only 8 colors
+(and therefore required at most 8\(mu8 = 64 color pairs).
 .bP
 .I \%PDCurses
 (1992-present) inherited the 8-color limitation from
 .IR \%PCCurses ,
 but changed this to 256 in version 2.5 (2001),
-along with changing \fB\%chtype\fP from 16-bits to 32-bits.
+and widened its
+.I \%chtype
+from 16 to 32 bits.
 .bP
 X/Open Curses (1992-present)
-added a new structure \fB\%cchar_t\fP to store the character,
-attributes and color pair values, allowing increased range of color pairs.
-Both color pairs and color-values used a signed \fBshort\fP,
-limiting values to 15 bits.
+specified a new structure type,
+.IR \%cchar_t ","
+to store the character code,
+attribute flags,
+and color pair identifier,
+allowing an increased range of color pairs.
+It specifies a
+.I short
+as storing identifiers for colors and color pairs,
+limiting portable values to 15 bits;
+negative values are invalid in System\ V.
 .bP
-\fI\%ncurses\fP (1992-present) uses eight bits
-for \fB\%A_COLOR\fP in \fB\%chtype\fP values.
+.I \%ncurses
+(1992-present),
+in its non-wide configuration,
+uses 8 bits of
+.I \%chtype
+for the color pair identifier.
 .IP
-Version 5.3 provided a wide-character interface (2002),
-but left color pairs as part of the attributes-field.
+Version 5.3 (2002) offered a wide-character interface,
+but encoded the color pair identifier with attributes
+in the character type.
 .IP
 Since version 6 (2015),
-ncurses uses a separate \fBint\fP for color pairs in the \fB\%cchar_t\fP 
values.
-When those color pair values fit in 8 bits,
-ncurses allows color pairs to be manipulated
-via the functions using \fB\%chtype\fP values.
-.bP
-NetBSD curses used 6 bits from
-2000 (when colors were first supported) until 2004.
-At that point, NetBSD changed to use 10 bits.
-As of 2021, that size is unchanged.
-Like \fI\%ncurses\fP before version 6,
-the NetBSD color pair information is stored in
-the attributes field of \fB\%cchar_t\fP, limiting the number of color pairs
-by the size of the bitfield.
+.I \%ncurses
+uses a separate
+.I int
+for the color pair identifier in a
+.IR \%cchar_t ","
+introducing extension functions to manage the wider type.
+When a color pair value fits in 8 bits,
+.I \%ncurses
+permits color pair data to be manipulated
+via the functions taking
+.I \%chtype
+arguments,
+even when a
+.I curses
+window uses wide-character cells.
+.bP
+NetBSD
+.I curses
+used 6 bits for the color pair identifier from 2000
+(when it first added color support)
+until 2004.
+At that point,
+NetBSD widened the color pair identifier to use 9 bits.
+As of 2025,
+that size is unchanged.
+.\" http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/libcurses/curses.h?rev=1.133
+.\" indicates a mask of 0x03fe0000.
+Like
+.I \%ncurses
+before version 6,
+the NetBSD color pair datum is stored in
+the attributes field of
+.IR \%cchar_t ","
+limiting the number of color pairs.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_attr\fP(3X),
-- 
2.30.2

signature.asc
Description: PGP signature