[PATCH 088/177] man/curs_color.3x: Revise "RETURN VALUE" section.

[G. Branden Robinson]

Content:
* Drop material about what X/Open Curses and SVr4 do; it will return in
  a subsequent commit.
* Refer to terminfo capability both by full name and cap-code.

Style:
* Favor active voice over passive.
* Favor "ncurses" over "this implementation".
* Migrate from inset tagged paragraphs to bulleted paragraphs.

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 | 116 ++++++++++++++++++++++++++++++----------------
 1 file changed, 76 insertions(+), 40 deletions(-)

diff --git a/man/curs_color.3x b/man/curs_color.3x
index 3b54c949d..03f82c318 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -433,51 +433,87 @@ .SS PAIR_NUMBER
 \fIattr\fP parameter and returns it as a color pair number;
 it is the inverse operation of \fB\%COLOR_PAIR\fP.
 .SH RETURN VALUE
-The routines \fB\%can_change_color\fP and \fB\%has_colors\fP return \fBTRUE\fP
-or \fBFALSE\fP.
-.PP
-All other routines return the integer \fBERR\fP upon failure and an \fBOK\fP
-(SVr4 specifies only \*(``an integer value
-other than \fBERR\fP\*('') upon successful completion.
+.B \%can_change_color
+and
+.B \%has_colors
+return
+.B TRUE
+or
+.BR FALSE "."
+The other functions return
+.B OK
+on success and
+.B ERR
+on failure.
 .PP
-X/Open defines no error conditions.
-SVr4 does document some error conditions which apply in general:
+In
+.IR \%ncurses ","
+functions returning an
+.I int
+recognize several error conditions.
 .bP
-This implementation will return \fBERR\fP on attempts to
-use color values outside the range \fB0\fP to \fB\%COLORS\fP\-1
-(except for the default colors extension),
-or use color pairs outside the range \fB0\fP to \fB\%COLOR_PAIRS\-1\fP.
-.IP
-Color values used in \fB\%init_color\fP must be
-in the range \fB0\fP to \fB1000\fP.
-.IP
-An error is returned from all functions
-if the terminal has not been initialized.
-.IP
-An error is returned from secondary functions such as \fB\%init_pair\fP
-if \fB\%start_color\fP was not called.
+All return
+.B ERR
+if the screen has not been initialized;
+see \fBinitscr\fP(3X) or \fBnewterm\fP(3X).
 .bP
-SVr4 does much the same, except that
-it returns \fBERR\fP from \fB\%pair_content\fP if the pair was not initialized
-using \fB\%init_pairs\fP
-and
-it returns \fBERR\fP from \fB\%color_content\fP
-if the terminal does not support changing colors.
-.IP
-This implementation does not return \fBERR\fP for either case.
-.PP
-Specific functions make additional checks:
-.RS 3
-.TP 5
-\fB\%init_color\fP
+All except
+.B \%start_color
+return
+.B ERR
+if
+.B \%start_color
+has not been called,
+or itself returned
+.BR ERR "."
+.bP
+.B \%start_color
 returns
 .B ERR
-if the terminal does not support
-this feature, e.g., if the \fB\%initialize_color\fP capability is absent
-from the terminal description.
-.TP 5
-\fB\%start_color\fP
-returns an error if the color table cannot be allocated.
+if it cannot allocate memory for its color pair table.
+.bP
+.B \%init_color
+returns
+.B ERR
+if the terminal type does not support assignable color values;
+that is,
+if the
+.B \%initialize_color
+.RB ( initc )
+capability is absent from its description.
+.bP
+.B \%init_color
+returns
+.B ERR
+if any of its
+.IR r ","
+.IR g ","
+.I b
+arguments is outside the range 0-1000 inclusive.
+.bP
+.BR \%init_pair ","
+.BR \%init_color ","
+.BR \%init_extended_pair ","
+.BR \%init_extended_color ","
+.BR \%color_content ","
+.BR \%pair_content ","
+.BR \%extended_color_content ","
+and
+.B \%extended_pair_content
+return
+.B ERR
+on attempts to use
+.RS
+.bP
+color identifiers outside the range
+.RB \%0- COLORS \-1
+inclusive,
+the default colors extension notwithstanding,
+or
+.bP
+color pairs identifiers outside the range
+.RB \%0- COLOR_PAIRS \-1
+inclusive.
 .RE
 .SH NOTES
 In the \fI\%ncurses\fP implementation,
-- 
2.30.2

signature.asc
Description: PGP signature