[PATCH 23/42] man/curs_bkgrnd.3x: Revise.

[G. Branden Robinson]

Content:
* Clarify that these functions apply to the wide curses configuration.
* Add cross reference to curs_attr(3X).
* Synchronize description with curs_bkgd.3x, altering as appropriate to
  cross reference wide ncurses functions.
* Fully describe bkgrnd/wbkgrnd repaint behavior, instead of steering
  reader to the non-wide page.  This violates the DRY principle, but I
  think it's more important to have documentation that is convenient for
  users of the wide ncurses API to not have to clutter their minds with
  details for the "narrow" one.  (Also, the ncurses man pages commit
  many other DRY offenses, and I have multiple notions for how we might
  address them.)
* Move material about behavioral details unspecified by SVr4 or X/Open
  from "NOTES" to "PORTABILITY" (but retain the description of ncurses'
  own behavior).
* Add caveat about asymmetry between `{w,}getbkgd` and `{w,}getbkrnd`.
* Add cross reference to non-wide configuration counterpart man page.
* Add cross references to curs_add_wch(3X) curs_attr(3X) in "SEE ALSO"
  section.

Style:
* Tighten wording.

Markup:
* Add definitions of `` and '' strings so we can use them for quotation.
* Protect function name literals from hyphenation.
* Use man(7) font style selection macros a little more often, but not
  for ncurses function names, since these are generally man page cross
  references (or might become them).
---
 man/curs_bkgrnd.3x | 164 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 125 insertions(+), 39 deletions(-)

diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x
index 25421b78f..ee253b21b 100644
--- a/man/curs_bkgrnd.3x
+++ b/man/curs_bkgrnd.3x
@@ -29,6 +29,17 @@
 .\"
 .\" $Id: curs_bkgrnd.3x,v 1.34 2023/12/02 21:30:00 tom Exp $
 .TH curs_bkgrnd 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
@@ -60,67 +71,142 @@ .SH DESCRIPTION
 of a
 .I curses
 window
+(in the library's \*(``wide\*('' configuration)
 is a
 .I \%cchar_t
-combining a set of
-.I attributes
+combining a set of attributes
+(see \fB\%curs_attr\fP(3X))
 with a complex character called the
 .I "blank character."
 The blank character is a spacing character that populates a window's
 character cells when their contents are erased without replacement.
 The background's attributes are combined with all non-blank characters
-written to the window with the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X)
-families of functions.
-Both
-the character and attribute parts of the background are combined with
-the blank characters.
-.PP
-The background becomes a property of the
-character and moves with the character through any scrolling and
-insert/delete line/character operations.
+written to the window,
+as with the \fB\%wadd_wch\fP(3X) and \fB\%wins_wch\fP(3X) families of
+functions.
+The blank character and attributes of the background combine with
+characters written to the window as described below.
+The background becomes a property of the character and moves with it
+through any scrolling and insert/delete line/character operations.
+To the extent possible on a given terminal,
+the attribute part of the background is displayed as the graphic
+rendition of the character put on the screen.
+.SS "bkgrnd, wbkgrnd"
+\fB\%bkgrnd\fP and \fB\%wbkgrnd\fP set the background property of
+\fB\%stdscr\fP or the specified window and then apply this setting to
+every character cell in that window.
+.bP
+The rendition of every character in the window changes to the new
+background rendition.
+.bP
+Wherever the former background character appears,
+it changes to the new background character.
 .PP
-To the extent possible on a
-particular terminal, the attribute part of the background is displayed
-as the graphic rendition of the character put on the screen.
-.SS bkgrnd
-The \fBbkgrnd\fP and \fBwbkgrnd\fP functions
-set the background property of the current or specified window
-and then apply this setting to every character position in that window:
+.I \%ncurses
+updates the rendition of each character cell by comparing the character,
+non-color attributes,
+and colors.
+The library applies to following procedure to each cell in the window,
+whether or not it is blank.
 .bP
-The rendition of every character on the screen is changed to
-the new background rendition.
+.I \%ncurses
+first compares the cell's character to the previously specified blank
+character;
+if they match,
+.I \%ncurses
+writes the new blank character to the cell.
 .bP
-Wherever the former background character
-appears, it is changed to the new background character.
-.SS bkgrndset
-The \fBbkgrndset\fP and \fBwbkgrndset\fP routines manipulate the
-background of the named window.
-.SS getbkgrnd
-The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the given
-or specified window's current background character and attribute pair
-and store it via the
+.I \%ncurses
+then checks if the cell uses color,
+that is,
+its color pair value is nonzero.
+If not,
+it simply replaces the attributes and color pair in the cell with those
+from the new background character.
+.bP
+If the cell uses color,
+and its background color matches that of the current window background,
+.I \%ncurses
+removes attributes that may have come from the current background and
+adds those from the new background.
+It finishes by setting the cell's background to use the new window
+background color.
+.bP
+If the cell uses color,
+and its background color does not match that of the current window
+background,
+.I \%ncurses
+updates only the non-color attributes,
+first removing those that may have come from the current background,
+and then adding attributes from the new background.
+.PP
+.I \%ncurses
+treats a background character value of zero (0) as a blank character.
+.PP
+If the terminal does not support color,
+or if color has not been initialized with \fB\%start_color\fP(3X),
+.I \%ncurses
+ignores the new background character's color attribute.
+.SS "bkgrndset, wbkgrndset"
+\fB\%bkgrndset\fP and \fB\%wbkgrndset\fP manipulate the background of
+the applicable window,
+without updating the character cells as \fB\%bkgrnd\fP and
+\fB\%wbkgrnd\fP do;
+only future writes reflect the updated background.
+.SS "getbkgrnd, wgetbkgrnd"
+The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the
+background character and attribute pair of \fB\%stdscr\fP or the
+specified window and store it via the
 .I wch
 pointer.
 .SH RETURN VALUE
-The \fBbkgrndset\fP and \fBwbkgrndset\fP routines do not return a value.
+\fBbkgrndset\fP and \fBwbkgrndset\fP do not return a value.
 .PP
-Upon successful completion, the other functions return \fBOK\fP.
-Otherwise, they return \fBERR\fP:
+The other functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
+In
+.I \%ncurses,
+failure occurs if
 .bP
-A null \fI\%WINDOW\fP pointer is treated as an error.
+a
+.I \%WINDOW
+pointer
+.I win
+is null, or
 .bP
-A null \fI\%cchar_t\fP pointer is treated as an error.
+a
+.I \%cchar_t
+pointer
+.I wch
+is null.
 .SH NOTES
 \fB\%bkgrnd\fP,
 \fB\%bkgrndset\fP, and
 \fB\%getbkgrnd\fP
 may be available as macros.
 .PP
-X/Open Curses does not provide details on how the rendition is changed.
-This implementation follows the approach used in SVr4 curses,
-which is explained in the manual page for \fBwbkgd\fP.
+Unlike their counterparts in the non-\*(``wide\*('' configuration of
+.I \%ncurses,
+\fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP supply the background character
+and attribute in a modifiable
+.I \%cchar_t
+parameter,
+not as the return value.
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses, Issue 4, describes these functions.
+It specifies no error conditions for them.
+.PP
+X/Open Curses does not provide details of how the rendition is updated.
+This implementation follows the approach used in SVr4
+.I curses.
 .SH SEE ALSO
+\fB\%curs_bkgd\fP(3X) describes the corresponding functions in the
+non-\*(``wide\*('' configuration of
+.I \%ncurses.
+.PP
 \fB\%curses\fP(3X),
-\fB\%curs_bkgd\fP(3X)
+\fB\%curs_add_wch\fP(3X),
+\fB\%curs_attr\fP(3X)
-- 
2.30.2

signature.asc
Description: PGP signature