[PATCH 04/19] man/curs_{bkgd,bkgrnd}.3x: Revise.

[G. Branden Robinson]

Content:
* Add survey of the 3 elemental functions to leading paragraph, and the
  usual pointer to ncurses(3X) for elucidation of the "what it means
  when the function name omits the leading 'w'" point.
* [bkgd] Refer to "chtype" value instead of "background character
  value", which is less clear.
* Add "HISTORY" section.

Style:
* Coalesce single-sentence first paragraph with succeeding one.  Thomas
  applied italics to the first occurrence of the "blank character" term,
  whereas I had it italicized at its point of definition.  Make these
  the same location.
* Revise subsection headings to name only the elemental functions, since
  they no longer say anything in particular about the stdscr-based ones.
* Align language of "RETURN VALUE" section more closely with other
  recently edited ncurses man pages.
* Set name of nonexistent function "wgetbkgd" in italics, not bold.
* Favor present tense over future.
* Recast.

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).
* Quote punctuation-only second arguments to `BR` and `IR` macros, to
  avoid false positives reported by one of Thomas Dickey's
  style-checking scripts, per his communication.
* Annotate citation of SVID 4.
* Break input lines after commas.
---
 man/curs_bkgd.3x   | 161 +++++++++++++++++++++++++++++++--------------
 man/curs_bkgrnd.3x |  89 ++++++++++++++++---------
 2 files changed, 168 insertions(+), 82 deletions(-)

diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x
index a8a5191b7..458b27fab 100644
--- a/man/curs_bkgd.3x
+++ b/man/curs_bkgd.3x
@@ -74,15 +74,22 @@ .SH DESCRIPTION
 .I \%chtype
 combining a set of attributes
 (see \fB\%curs_attr\fP(3X))
-with a character called the
-.I "blank character."
-.PP
-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
+with the window's
+.I "blank character,"
+a spacing character that populates a window's character cells
+when their contents are erased without replacement.
+The background's attributes combine with all non-blank characters
 written to the window,
 as with the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X) families of
 functions.
+.B \%wbkgd
+sets a window's blank character and updates its contents,
+whereas
+.B \%wbkgdset
+does only the former.
+.B \%getbkgd
+retrieves the blank character.
+\fB\%ncurses\fP(3X) describes the variants of these functions.
 .PP
 The blank character and attributes of the background combine with
 characters written to the window as described below.
@@ -92,13 +99,15 @@ .SH DESCRIPTION
 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 "bkgd, wbkgd"
-\fB\%bkgd\fP and \fB\%wbkgd\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.
+.SS wbkgd
+.B \%wbkgd
+sets
+.IR win 's
+background property,
+then applies this setting to every character cell in it.
 .bP
-The rendition of every character in the window changes to the new
-background rendition.
+The rendition of every character in the window changes to that of the
+new blank character.
 .bP
 Wherever the former blank character appears,
 it changes to the new blank character.
@@ -142,79 +151,131 @@ .SS "bkgd, wbkgd"
 and then adding attributes from the new background.
 .PP
 .I \%ncurses
-treats a background character value of zero (0) as a blank character.
+treats a
+.I \%chtype
+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 blank character's color attribute.
-.SS "bkgdset, wbkgdset"
-\fB\%bkgdset\fP and \fB\%wbkgdset\fP manipulate the background of
-the applicable window,
-without updating the character cells as \fB\%bkgd\fP and
-\fB\%wbkgd\fP do;
+.SS wbkgdset
+.B \%wbkgdset
+assigns the specified window's blank character
+without updating its character cells as
+.B \%wbkgd
+does;
 only future writes reflect the updated blank character.
 .SS getbkgd
-\fB\%getbkgd\fP obtains the given window's background character and
-attribute combination.
+.B \%getbkgd
+obtains the specified window's blank character
+and returns it.
 .SH RETURN VALUE
-Functions returning an \fIint\fP return \fBOK\fP on success.
-\fB\%bkgd\fP returns \fBERR\fP if the library has not been initialized.
-\fB\%wbkgd\fP and \fB\%getbkgd\fP return \fBERR\fP if a \fI\%WINDOW\fP
-pointer argument is null.
+.B \%bkgd
+and
+.B \%wbkgd
+return
+.B ERR
+upon failure and
+.B OK
+upon success.
+In
+.IR \%ncurses ","
+failure occurs if
+.bP
+the library has not been initialized,
+or
+.bP
+a
+.I \%WINDOW
+pointer
+.I win
+is null,
+or
 .PP
-\fB\%bkgdset\fP and \fBwbkgdset\fP do not return a value.
+.B \%bkgdset
+and
+.B \%wbkgdset
+do not return a value.
 .PP
-\fB\%getbkgd\fP returns a window's blank character.
+.B \%getbkgd
+returns a blank character as described above.
 .SH NOTES
 Unusually,
-there is no \fB\%wgetbkgd\fP function;
-\fB\%getbkgd\fP behaves as one would expect \fB\%wgetbkgd\fP to,
-accepting a \fI\%WINDOW\fP pointer argument.
+there is no
+.I \%wgetbkgd
+function;
+.B \%getbkgd
+behaves as one would expect
+.B \%wgetbkgd
+to,
+accepting a
+.I \%WINDOW
+pointer argument.
 .PP
-\fB\%bkgd\fP and
-\fB\%bkgdset\fP
+.B \%bkgd
+and
+.B \%bkgdset
 may be implemented as macros.
 .PP
 X/Open Curses mentions that the character part of the background must
 be a single-byte value.
-\fI\%ncurses\fP,
-like SVr4 \fIcurses\fP,
+.IR \%ncurses ","
+like SVr4
+.IR curses ","
 checks to ensure that,
-and will reuse the old background character if the check fails.
+and reuses the old blank character if the check fails.
 .SH PORTABILITY
 X/Open Curses,
 Issue 4 describes these functions.
 It specifies that
-\fB\%bkgd\fP,
-\fB\%wbkgd\fP,
+.IR \%bkgd ","
+.IR \%wbkgd ","
 and
-\fB\%getbkgd\fP
-return \fBERR\fP on failure
+.I \%getbkgd
+return
+.B ERR
+on failure
 (in the case of the last,
 this value is cast to
 .IR \%chtype ),
 but describes no failure conditions.
 .PP
-The SVr4.0 manual says that \fB\%bkgd\fP and \fB\%wbkgd\fP may return
-\fBOK\fP
-\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
-which refers to the return value from \fB\%wrefresh\fP(3X),
+SVr4 documentation
+.\" SVID 4, vol. 3, p. 482
+says that
+.I \%bkgd
+and
+.I \%wbkgd
+return
+.B OK
+\*(``or a non-negative integer if
+.I \%immedok \" empty function call parentheses elided
+is set\*('',
+which refers to the return value from
+.IR \%wrefresh ","
 used to implement the immediate repainting.
-SVr4 \fIcurses\fP's \fB\%wrefresh\fP returns the number of characters
-written to the screen during the refresh.
-\fI\%ncurses\fP does not do that.
+SVr4
+.IR curses 's
+.I \%wrefresh
+returns the number of characters written to the screen by the refresh.
+.I \%ncurses
+does not do that.
 .PP
-Neither X/Open Curses nor the SVr4 manual pages detail how the rendition
-of characters on the screen updates when \fB\%bkgd\fP or \fB\%wbkgd\fP
-changes the blank character.
+Neither X/Open Curses nor SVr4 describes
+how renditions of characters already on the screen change when
+.I \%wbkgd
+alters the blank character.
 .IR \%ncurses ,
 like SVr4
 .IR curses ,
 does not
 (in its non-wide configuration)
-store the background and window attribute contributions to each
-character cell separately.
+store the character code and attribute components of each character cell
+separately.
+.SH HISTORY
+SVr3.1 (1987)
+introduced these functions.
 .SH SEE ALSO
 \fB\%curs_bkgrnd\fP(3X) describes the corresponding functions in the
 wide configuration of
diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x
index 4c64ec60e..8087e89fa 100644
--- a/man/curs_bkgrnd.3x
+++ b/man/curs_bkgrnd.3x
@@ -76,16 +76,22 @@ .SH DESCRIPTION
 .I \%cchar_t
 combining a set of attributes
 (see \fB\%curs_attr\fP(3X))
-with the window's blank character.
-.PP
-The
-.I "blank character"
-is a spacing complex character that populates a window's character cells
+with the window's
+.I "blank character,"
+a spacing complex 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
+The background's attributes combine with all non-blank characters
 written to the window,
 as with the \fB\%wadd_wch\fP(3X) and \fB\%wins_wch\fP(3X) families of
 functions.
+.B \%wbkgrnd
+sets a window's blank character and updates its contents,
+whereas
+.B \%wbkgrndset
+does only the former.
+.B \%getbkgrnd
+retrieves the blank character.
+\fB\%ncurses\fP(3X) describes the variants of these functions.
 .PP
 The blank character and attributes of the background combine with
 characters written to the window as described below.
@@ -95,13 +101,15 @@ .SH DESCRIPTION
 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.
+.SS wbkgrnd
+.B \%wbkgrnd
+sets
+.IR win 's
+background property,
+then applies this setting to every character cell in it.
 .bP
-The rendition of every character in the window changes to the new
-background rendition.
+The rendition of every character in the window changes to that of the
+new blank character.
 .bP
 Wherever the former blank character appears,
 it changes to the new blank character.
@@ -151,20 +159,24 @@ .SS "bkgrnd, wbkgrnd"
 or if color has not been initialized with \fB\%start_color\fP(3X),
 .I \%ncurses
 ignores the new blank 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
-blank character and attribute pair of \fB\%stdscr\fP or the
-specified window and store it via the
+.SS wbkgrndset
+.B \%wbkgrndset
+assigns the specified window's blank character
+without updating its character cells as
+.B \%wbkgrnd
+does;
+only future writes reflect the updated blank character.
+.SS wgetbkgrnd
+.B \%wgetbkgrnd
+obtains the specified window's blank character
+and stores it via the
 .I wch
 pointer.
 .SH RETURN VALUE
-\fBbkgrndset\fP and \fBwbkgrndset\fP do not return a value.
+.B \%bkgrndset
+and
+.B \%wbkgrndset
+do not return a value.
 .PP
 The other functions return
 .B ERR
@@ -172,14 +184,17 @@ .SH RETURN VALUE
 .B OK
 upon success.
 In
-.IR \%ncurses ,
+.IR \%ncurses ","
 failure occurs if
 .bP
+the library has not been initialized,
+.bP
 a
 .I \%WINDOW
 pointer
 .I win
-is null, or
+is null,
+or
 .bP
 a
 .I \%cchar_t
@@ -187,15 +202,18 @@ .SH RETURN VALUE
 .I wch
 is null.
 .SH NOTES
-\fB\%bkgrnd\fP,
-\fB\%bkgrndset\fP, and
-\fB\%getbkgrnd\fP
+.BR \%bkgrnd ","
+.BR \%bkgrndset ","
+and
+.B \%getbkgrnd
 may be implemented as macros.
 .PP
 Unlike their counterparts in the non-wide configuration of
 .IR \%ncurses ,
-\fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP supply the blank character
-and attribute in a modifiable
+.B \%getbkgrnd
+and
+.B \%wgetbkgrnd
+supply the blank character and attribute in a modifiable
 .I \%cchar_t
 parameter,
 not as the return value.
@@ -204,9 +222,16 @@ .SH PORTABILITY
 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
+X/Open Curses does not describe
+how renditions of characters already on the screen change when
+.I \%wbkgrnd
+alters the blank character.
+.I \%ncurses
+follows the approach used in SVr4
 .IR curses .
+.SH HISTORY
+These functions were initially specified by X/Open Curses,
+Issue 4.
 .SH SEE ALSO
 \fB\%curs_bkgd\fP(3X) describes the corresponding functions in the
 non-wide configuration of
-- 
2.30.2

signature.asc
Description: PGP signature