[PATCH 028/177] man/curs_bkg{,rn}d.3x: Fix content and style nits.

[G. Branden Robinson]

Content:
* It's not the curses library itself that needs to be "initialized"
  before use of these functions, but the `SCREEN` data structure that
  the library manages.
* Quote SVID 4 more precisely.

Style:
* Recast for clarity and consistency with usage in other ncurses man
  pages.
  + The background property of a window is a character of the
    appropriate type: `chtype` or `cchar_t`.
  + Refer to "character code", not "character value".
  + Clarify in introductory paragraph that the color pair selection of
    the background character may influence these functions' behavior.
  + Continue terminological reform: favor the term "color pair
    selection" over "color attribute".
  + Use parenthetical to reinforce notion that window erasure need not
    be total (affecting every cell).
  + Use more care in terminology: it is a "window" that is cleared or
    erased, not "the screen" per se.
* Fix missing period.
* Drop extraneous word ("if").
* Set function names in italics, not bold, when referring to them
  generically (as in the "PORTABILITY" and "HISTORY" sections), as
  opposed to the ncurses topic/implementation.
* Drop trailing empty parentheses from function reference (except in a
  direct quotation); that styling is not the practice of the ncurses man
  pages.
---
 man/curs_bkgd.3x   | 85 ++++++++++++++++++++++++++--------------------
 man/curs_bkgrnd.3x | 75 ++++++++++++++++++++++++----------------
 2 files changed, 94 insertions(+), 66 deletions(-)

diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x
index e6c56b425..3e3764b2a 100644
--- a/man/curs_bkgd.3x
+++ b/man/curs_bkgd.3x
@@ -66,36 +66,46 @@ .SH SYNOPSIS
 .SH DESCRIPTION
 Every
 .I curses
-window has a background property.
-In the library's non-wide configuration,
-this property is a
-.I \%chtype
-which combines a set of attributes with the
+window has a
 .I "background character"
-(see \fB\%curs_attr\fP(3X)).
-The background character is a spacing character.
-.PP
-When erasing parts of the screen,
+property:
+in the library's non-wide configuration,
+it is a
+.I curses
+character
+.RI \%( chtype )
+that combines a set of attributes
+(and,
+if colors are enabled,
+a color pair identifier)
+with a character code.
+When erasing
+(parts of)
+a window,
 .I curses
-fills the cells with the background character.
+replaces the erased cells with the background character.
+.PP
 .I curses
-also uses the window background when writing characters to the screen.
+also uses the background character when writing characters to a
+populated window.
 .bP
-The attribute part of the background combines with all
-non-blank characters written into the window,
-as with the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X) families of
-functions.
+The attribute part of the background character combines with all
+non-blank character cells in the window,
+as populated by the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X)
+families of functions
+(and those that call them).
 .bP
-Both the character and attribute parts of the background combine with
-blank characters that are written into the window.
-.PP
-The background becomes a property of the character and moves with it
-through any scrolling and insert/delete line/character operations.
+Both the character code and attributes of the background character
+combine with blank character cells in the window.
 .PP
-To the extent possible on a given terminal,
+The background character's set of attributes becomes a property
+of the character cell
+and move with it through any scrolling
+and insert/delete line/character operations.
+To the extent possible on the terminal type,
 .I curses
-displays the attributes of the background
-as the graphic rendition of the character put on the screen.
+displays the attributes of the background character
+as the graphic rendition of a character cell on the display.
 .SS "bkgd, wbkgd"
 .B \%bkgd
 and
@@ -149,17 +159,19 @@ .SS "bkgd, wbkgd"
 first removing those that may have come from the current background,
 and then adding attributes from the new background.
 .PP
-If the new background's character is nonspacing,
+If the new background's character is non-spacing
+(for example,
+if it is a control character),
 .I \%ncurses
 retains the existing background character,
 except for one special case:
 .I \%ncurses
-treats a background character value of zero (0) as a space.
+treats a background character code of zero (0) as a space.
 .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.
+ignores the new background character's color pair selection.
 .SS "bkgdset, wbkgdset"
 .B \%bkgdset
 and
@@ -181,7 +193,7 @@ .SH RETURN VALUE
 .B \%bkgdset
 and
 .B \%wbkgdset
-do not return a value
+do not return a value.
 .PP
 Functions returning an
 .I int
@@ -194,10 +206,11 @@ .SH RETURN VALUE
 .IR \%ncurses ","
 failure occurs if
 .bP
-if the library has not been initialized,
+the
+.I curses
+screen has not been initialized,
 or
 .bP
-if
 .I win
 is
 .IR NULL "."
@@ -227,7 +240,7 @@ .SH NOTES
 .IR \%ncurses ","
 like SVr4
 .IR curses ","
-checks to ensure that,
+checks to ensure that it is,
 and retains the existing background character if the check fails.
 .SH PORTABILITY
 X/Open Curses Issue\ 4 describes these functions.
@@ -237,7 +250,7 @@ .SH PORTABILITY
 and
 .I getbkgd
 return
-.B ERR
+.I ERR
 on failure
 (in the case of the last,
 this value is cast to
@@ -251,24 +264,24 @@ .SH PORTABILITY
 and
 .I \%wbkgd
 return
-.B OK
+.I OK
 \*(``or a non-negative integer if
-.B \%immedok
+.I \%immedok() \" Courier roman in source
 is set\*('',
 which refers to the return value from
-.IR \%wrefresh() ","
+.IR \%wrefresh ","
 used to implement the immediate repainting.
 SVr4
 .IR curses 's
 .I \%wrefresh
 returns the number of characters
-written to the screen during the refresh;
+written to the window during the refresh;
 that of
 .I \%ncurses
 does not.
 .PP
 Neither X/Open Curses nor the SVr4 manual pages detail how the rendition
-of characters on the screen updates when
+of characters in the window updates when
 .I \%bkgd
 or
 .I \%wbkgd
diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x
index 4e18d1196..645c6f4b1 100644
--- a/man/curs_bkgrnd.3x
+++ b/man/curs_bkgrnd.3x
@@ -68,36 +68,46 @@ .SH SYNOPSIS
 .SH DESCRIPTION
 Every
 .I curses
-window has a background property.
-In the library's wide configuration,
-this property is a
-.I \%cchar_t
-which combines a set of attributes with the
+window has a
 .I "background character"
-(see \fB\%curs_attr\fP(3X)).
-The background character is a spacing character.
-.PP
-When erasing parts of the screen,
+property:
+in the library's wide configuration,
+it is a
 .I curses
-fills the cells with the background character.
+complex character
+.RI \%( cchar_t )
+that combines a set of attributes
+(and,
+if colors are enabled,
+a color pair identifier)
+with a character code.
+When erasing
+(parts of)
+a window,
+.I curses
+replaces the erased cells with the background character.
+.PP
 .I curses
-also uses the window background when writing characters to the screen.
+also uses the background character when writing characters to a
+populated window.
 .bP
-The attribute part of the background combines with all
-non-blank characters written into the window,
-as with the \fB\%wadd_wch\fP(3X) and \fB\%wins_wch\fP(3X) families of
-functions.
+The attribute part of the background character combines with all
+non-blank character cells in the window,
+as populated by the \fB\%wadd_wch\fP(3X) and \fB\%wins_wch\fP(3X)
+families of functions
+(and those that call them).
 .bP
-Both the character and attribute parts of the background combine with
-blank characters that are written into the window.
+Both the character code and attributes of the background character
+combine with blank character cells in the window.
 .PP
-The background becomes a property of the character and moves with it
-through any scrolling and insert/delete line/character operations.
-.PP
-To the extent possible on a given terminal,
+The background character's set of attributes becomes a property
+of the character cell
+and move with it through any scrolling
+and insert/delete line/character operations.
+To the extent possible on the terminal type,
 .I curses
-displays the attributes of the background
-as the graphic rendition of the character put on the screen.
+displays the attributes of the background character
+as the graphic rendition of a character cell on the display.
 .SS "bkgrnd, wbkgrnd"
 .B \%bkgrnd
 and
@@ -151,17 +161,17 @@ .SS "bkgrnd, wbkgrnd"
 first removing those that may have come from the current background,
 and then adding attributes from the new background.
 .PP
-If the new background's character is nonspacing,
+If the new background's character is non-spacing,
 .I \%ncurses
 reuses the old background character,
 except for one special case:
 .I \%ncurses
-treats a background character value of zero (0) as a space.
+treats a background character code of zero (0) as a space.
 .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.
+ignores the new background character's color pair selection.
 .SS "bkgrndset, wbkgrndset"
 .B \%bkgrndset
 and
@@ -191,7 +201,9 @@ .SH RETURN VALUE
 .B \%wbkgrndset
 do not return a value.
 .PP
-The other functions return
+Functions returning an
+.I int
+return
 .B ERR
 upon failure and
 .B OK
@@ -200,6 +212,10 @@ .SH RETURN VALUE
 .IR \%ncurses ","
 failure occurs if
 .bP
+the
+.I curses
+screen has not been initialized,
+.bP
 .I win
 is
 .IR NULL ","
@@ -220,11 +236,10 @@ .SH NOTES
 .B \%getbkgrnd
 and
 .B \%wgetbkgrnd
-supply the background character
-and attribute in a modifiable
+store the background character in a modifiable
 .I \%cchar_t
 parameter,
-not as the return value.
+rather than supplying it as the return value.
 .SH PORTABILITY
 X/Open Curses Issue\ 4 describes these functions.
 It specifies no error conditions for them.
-- 
2.30.2

signature.asc
Description: PGP signature