[PATCH 15/23] man/curs_terminfo.3x: Fix style and markup nits.

[G. Branden Robinson]

Style:
* Recast for clarity.
* Fix missing period at end of sentence.
* Set formal parameter names in italics, not bold (they are not
  literals).
* Present "padding" as an item of terminology and italicize it.
* Set within-paragraph example without paragraph spacing around it.
* Drop formal parameter from inline presentation of C type.
* Favor active voice over passive.
* Characterize more actions as behavior of the library rather than of a
  specific function like `setupterm()`.
* Set libc symbol `stdout` in italics, not bold, just as we would a
  standard C library (not ncurses) function name.

Markup:
* Use `RS`/`RE` man(7) macros for a within-paragraph display, not `IP`.
* 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 trailing punctuation arguments to man(7) font alternation
  macros.  The package does not require this; it avoids false positives
  reported by one of Thomas Dickey's style-checking scripts, per his
  communication.

* man/man_db.renames.in: Add reset_prog_mode.3x.
---
 man/curs_terminfo.3x | 91 ++++++++++++++++++++++++++------------------
 1 file changed, 53 insertions(+), 38 deletions(-)

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 82bfc1fa0..7c77e87a8 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -158,14 +158,18 @@ .SS Initialization
 .B \%columns
 as described in \fB\%use_env\fP(3X).
 .PP
-Parameterized strings should be passed through \fB\%tparm\fP to
-instantiate them.
+Pass parameterized string capability values through
+.B \%tparm
+to instantiate them.
 All
 .I \%term\%info
 strings
-(including the output of \fB\%tparm\fP)
-should be sent to the terminal device with \fB\%tputs\fP or
-\fB\%putp\fP.
+(including the output of
+.BR \%tparm ")"
+should be sent to the terminal device with
+.B \%tputs
+or
+.BR \%putp "."
 Call
 \fB\%reset_shell_mode\fP(3X) to restore the terminal modes before
 exiting.
@@ -180,9 +184,12 @@ .SS Initialization
 Specifically,
 output
 .bP
-output \fB\%enter_ca_mode\fP upon startup and
+.B \%enter_ca_mode
+upon startup,
+and
 .bP
-output \fB\%exit_ca_mode\fP before exiting.
+.B \%exit_ca_mode
+before exiting.
 .PP
 Programs that execute shell subprocesses should
 .bP
@@ -238,7 +245,9 @@ .SS Initialization
 If
 .I errret
 is not null,
-then \fB\%setupterm\fP returns
+then
+.B \%setupterm
+returns
 .B OK
 or
 .B ERR
@@ -265,9 +274,7 @@ .SS Initialization
 and cannot be used for
 .I curses
 applications.
-.IP
-\fB\%setupterm\fP determines if the entry is a hardcopy type by
-checking the
+The library determines this fact by checking the terminal type's
 .B \%hardcopy
 .RB ( hc )
 capability.
@@ -279,8 +286,8 @@ .SS Initialization
 .I curses
 applications to run.
 .IP
-\fB\%setupterm\fP determines if the entry is a generic type by
-checking the
+.B \%setupterm
+determines if the entry is a generic type by checking the
 .B \%generic_type
 .RB ( gn )
 capability.
@@ -294,8 +301,8 @@ .SS Initialization
 If
 .I errret
 is null,
-\fB\%setupterm\fP reports an error message upon finding an error and
-exits.
+.B \%setupterm
+reports an error message upon finding an error and exits.
 Thus,
 the simplest call is:
 .RS
@@ -306,7 +313,7 @@ .SS Initialization
 .RE
 .IP
 which uses all the defaults and sends the output to
-.BR stdout .
+.IR stdout .
 .RE
 .\" ********************************************************************
 .SS "The Terminal State"
@@ -346,10 +353,10 @@ .SS "The Terminal State"
 .PP
 .B \%del_curterm
 frees the memory pointed to by
-.BR \%oterm ","
+.IR \%oterm ","
 making it available for further use.
 If
-.B \%oterm
+.I \%oterm
 is
 the same as
 .BR \%cur_term ","
@@ -440,7 +447,8 @@ .SS "Formatting Output"
 library would assume.
 .\" ********************************************************************
 .SS "Output Functions"
-String capabilities can contain padding information,
+String capabilities can contain
+.IR padding ,
 a time delay
 (accommodating performance limitations of hardware terminals)
 expressed as \fB$<\fIn\fB>\fR,
@@ -484,7 +492,7 @@ .SS "Output Functions"
 .IB str ", 1, putchar)\c"
 \*(''.
 The output of \fB\%putp\fP always goes to
-.BR stdout ,
+.IR stdout ,
 rather than the
 .I \%file\%des
 specified in \fB\%setupterm\fP.
@@ -623,11 +631,11 @@ .SS "Releasing Memory"
 As a side effect,
 it sets \fB\%cur_term\fP to point to this memory.
 If an application calls
-.IP
+.RS
 .EX
 del_curterm(cur_term);
 .EE
-.PP
+.RE
 the memory will be freed.
 .PP
 The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
@@ -682,7 +690,7 @@ .SH RETURN VALUE
 .RB \%( stdscr ,
 .BR \%curscr ,
 and
-.BR \%newscr )
+.BR \%newscr ).
 Other error conditions are documented above.
 .TP 5
 .B tparm
@@ -835,7 +843,8 @@ .SS "Function Prototypes"
 .I \%const
 less effectively than a later design might,
 sometimes applying it needlessly to values that are already constant,
-and in most cases overlooking parameters that normally would use
+and in most cases overlooking parameters that normally would benefit
+from
 .IR \%const .
 Passing
 .IR \%const -qualified
@@ -843,7 +852,7 @@ .SS "Function Prototypes"
 .I \%const
 may prevent the program from compiling.
 On the other hand,
-\*(``writable strings\*('' are an obsolescent feature.
+\*(``writable strings\*('' are an obsolescent C language feature.
 .IP
 As an extension,
 this implementation can be configured to change the function prototypes
@@ -879,12 +888,11 @@ .SS "Function Prototypes"
 Using
 .I long
 for the numeric parameter type is a workaround to make the parameter use
-the same amount of stack as a pointer.
-That approach dates back to the mid-1980s,
+the same amount of stack memory as a pointer.
+That approach dates to the mid-1980s,
 before C was standardized.
-Since then,
-there is a standard
-(and pointers are not required to fit in a
+Since ANSI\ C (1989),
+C language standards do not require a pointer to fit in a
 .IR long ).
 .bP
 Providing the right number of parameters for a variadic function
@@ -912,8 +920,10 @@ .SS "Special \fITERM\fP treatment"
 .\" XXX: as opposed to the Unix terminal driver, termio(s)?
 as with the MinGW port,
 .bP
-\fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the
-special value \*(``unknown\*(''.
+.B \%setupterm
+interprets a missing/empty
+.I TERM
+variable as the special value \*(``unknown\*(''.
 .IP
 SVr4
 .I curses
@@ -927,9 +937,12 @@ .SS "Special \fITERM\fP treatment"
 while the latter does not.
 A generic terminal is unsuitable for full-screen applications.
 .bP
-\fB\%setupterm\fP allows explicit use of the
-the windows console driver by checking if \fB$TERM\fP is set to
-\*(``#win32con\*('' or an abbreviation of that string.
+.B \%setupterm
+allows explicit use of the Microsoft Windows console driver by checking
+whether the
+.I TERM
+environment variable has the value \*(``#win32con\*(''
+or an abbreviation of that string.
 .SS "Other Portability Issues"
 In SVr4,
 .I \%set_curterm
@@ -944,10 +957,12 @@ .SS "Other Portability Issues"
 the third argument of
 .I \%tputs
 has the type
-.RB \*(`` "int (*putc)(char)" \*(''.
+.RB \*(`` "int (*)(char)" \*(''.
 .PP
-At least one implementation of X/Open Curses (Solaris) returns a value
-other than
+At least one implementation of X/Open Curses
+(Solaris
+.IR \%xcurses ")"
+returns a value other than
 .B OK
 or
 .B ERR
-- 
2.30.2

signature.asc
Description: PGP signature