[PATCH 160/177] man/curs_terminfo.3x: Revise "PORTABILITY" section.

[G. Branden Robinson]

Content:
* Correct systematic misspelling of function names; they were spuriously
  prefixed with "B" (likely damage from a botched migration from `\fB`).

Style:
* Lightly recast.
* Use roman instead of bold in example display.
* Set macro names and other C symbols in italics, not bold, when
  referring to them generically in this section, as opposed to the
  ncurses topic/implementation.
* Favor "ncurses" over "this implementation".
---
 man/curs_terminfo.3x | 80 +++++++++++++++++++++++---------------------
 1 file changed, 41 insertions(+), 39 deletions(-)

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 3b1f5430c..082f8bb7f 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -739,7 +739,7 @@ .SH NOTES
 is also provided in the non-wide-character configuration.
 .\" ********************************************************************
 .SH EXTENSIONS
-The functions marked as extensions were designed for
+The functions marked as extensions originated in
 .IR \%ncurses ","
 and are not found in SVr4
 .IR curses ","
@@ -773,26 +773,23 @@ .SS "Header Files"
 and
 .I \%term.h
 in that order
-to get the definitions for these strings,
-numbers,
-and flags.
+to make visible the definitions of the string arrays
+storing the capability names and codes.
 .SS "Compatibility Macros"
-This implementation provides a few macros for compatibility with systems
-before SVr4
-(see section \*(``HISTORY\*('' below).
-They include
-.IR \%Bcrmode ","
-.IR \%Bfixterm ","
-.IR \%Bgettmode ","
-.IR \%Bnocrmode ","
-.IR \%Bresetterm ","
-.IR \%Bsaveterm ","
-and"
-.IR \%Bsetterm "."
 .I \%ncurses
-implements each of these symbols as macros for BSD
+implements a few macros for early System\ V
 .I curses
-compatibility.
+compatibility
+(see section \*(``HISTORY\*('' below).
+They include
+.IR \%crmode ","
+.IR \%fixterm ","
+.IR \%gettmode ","
+.IR \%nocrmode ","
+.IR \%resetterm ","
+.IR \%saveterm ","
+and
+.IR \%setterm "."
 .PP
 In SVr4,
 these are found in
@@ -810,13 +807,13 @@ .SS "Compatibility Macros"
 stating that the call
 .RS
 .EX
-.BI setupterm( term ", 1, (int *)0)"
+.RI setupterm( term ", 1, (int *)0)"
 .EE
 .RE
 provides the same functionality as
 .RS
 .EX
-.BI setterm( term )
+.RI setterm( term )
 .EE
 .RE
 and discouraging the latter for new programs.
@@ -824,7 +821,7 @@ .SS "Legacy Data"
 .I \%setupterm
 copies the terminal name to the array
 .IR \%ttytype "."
-This is not part of X/Open Curses,
+This behavior is not specified by X/Open Curses,
 but is assumed by some applications.
 .PP
 Other implementions may not declare the capability name arrays.
@@ -844,8 +841,10 @@ .SS "Output Buffering"
 .I \%initscr
 or
 .I \%newterm
-uses buffered I/O,
-and would write to the corresponding stream.
+used buffered I/O,
+and wrote to the corresponding
+.I stdio
+stream.
 In addition to the limitation that the terminal was left in
 block-buffered mode on exit
 (like System\ V
@@ -853,19 +852,20 @@ .SS "Output Buffering"
 it was problematic because
 .I \%ncurses
 did not allow a reliable way to clean up on receiving
-.BR SIGTSTP "."
+.IR SIGTSTP "."
 .PP
 .I \%ncurses
 .RI 6. x
 uses output buffers managed directly by
 .IR \%ncurses "."
-Some of the low-level functions described in this manual page write
-to the standard output.
-They are not signal-safe.
-The high-level functions in
+The lower-level functions described here
+that write to the terminal device
+do so via the standard output stream;
+they thus are not signal-safe.
+The higher-level functions in
 .I \%ncurses
-employ alternate versions of these functions using the more reliable
-buffering scheme.
+employ alternate versions of these functions
+using a more reliable buffering scheme.
 .SS "Function Prototypes"
 The X/Open Curses prototypes are based on the SVr4
 .I curses
@@ -889,7 +889,8 @@ .SS "Function Prototypes"
 \*(``writable strings\*('' are an obsolescent C language feature.
 .IP
 As an extension,
-this implementation can be configured to change the function prototypes
+.I \%ncurses
+can be configured to change the function prototypes
 to use the
 .I \%const
 keyword.
@@ -902,7 +903,8 @@ .SS "Function Prototypes"
 with a fixed number of parameters,
 rather than a variable argument list.
 .IP
-This implementation uses a variable argument list,
+.I \%ncurses
+uses a variable argument list,
 but can be configured to use the fixed-parameter list.
 Portable applications should provide nine parameters after the format;
 zeroes are fine for this purpose.
@@ -957,7 +959,7 @@ .SS "Function Prototypes"
 .I \%ncurses
 library checks usage of these capabilities,
 and returns
-.B ERR
+.I ERR
 if the capability mishandles string parameters.
 But it cannot check if a calling program provides strings in the right
 places for the
@@ -976,7 +978,7 @@ .SS "Special \fITERM\fP treatment"
 .\" XXX: as opposed to the Unix terminal driver, termio(s)?
 as with the MinGW port,
 .bP
-.B \%setupterm
+.I \%setupterm
 interprets a missing/empty
 .I TERM
 variable as the special value \*(``unknown\*(''.
@@ -993,7 +995,7 @@ .SS "Special \fITERM\fP treatment"
 while the latter does not.
 A generic terminal is unsuitable for full-screen applications.
 .bP
-.B \%setupterm
+.I \%setupterm
 allows explicit use of the Microsoft Windows console driver by checking
 whether the
 .I TERM
@@ -1004,9 +1006,9 @@ .SS "Other Portability Issues"
 .I \%set_curterm
 returns an
 .IR int ","
-.B OK
+.I OK
 or
-.BR ERR "."
+.IR ERR "."
 We have chosen to implement the X/Open Curses semantics.
 .PP
 In SVr4,
@@ -1019,9 +1021,9 @@ .SS "Other Portability Issues"
 (Solaris
 .IR \%xcurses ")"
 returns a value other than
-.B OK
+.I OK
 or
-.B ERR
+.I ERR
 from
 .IR \%tputs "."
 It instead returns the length of the string,
-- 
2.30.2

signature.asc
Description: PGP signature