[PATCH 16/23] man/curs_terminfo.3x: Revise "PORTABILITY" and "HISTORY" sections.

[G. Branden Robinson]

Style:
* Improve placement of "only" modifier placement.
* Set function names in italics, not bold, when referring to them
  generically as opposed to the ncurses topic/implementation (except in
  examples of input).
* Replace colon dangling at the end of a sentence with a period.  The
  subsequent use of bulleted paragraphs makes the structure clear.

Markup:
* Favor man(7) font macros over roff(7) 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_terminfo.3x | 178 ++++++++++++++++++++++++++++---------------
 1 file changed, 117 insertions(+), 61 deletions(-)

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 7c77e87a8..e98ba5a00 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -745,8 +745,8 @@ .SH EXTENSIONS
 argument.
 .\" ********************************************************************
 .SH PORTABILITY
-\fB\%setterm\fP is not described by X/Open and must be considered
-non-portable.
+.I \%setterm
+is not described by X/Open and must be considered non-portable.
 All other functions are as described by X/Open.
 .SS "Header Files"
 On legacy
@@ -765,38 +765,49 @@ .SS "Compatibility Macros"
 before SVr4
 (see section \*(``HISTORY\*('' below).
 They include
-\fB\%Bcrmode\fP,
-\fB\%Bfixterm\fP,
-\fB\%Bgettmode\fP,
-\fB\%Bnocrmode\fP,
-\fB\%Bresetterm\fP,
-\fB\%Bsaveterm\fP,
-and
-\fB\%Bsetterm\fP.
+.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
+.I curses
+compatibility.
 .PP
 In SVr4,
 these are found in
 .IR \%curses.h ,
-but except for \fB\%setterm\fP,
+but except for
+.IR \%setterm ","
 are likewise macros.
 The one function,
-\fB\%setterm\fP,
+.IR \%setterm ","
 is mentioned in the manual page.
-It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP,
+It further notes that
+.I \%setterm
+was replaced by
+.IR \%setupterm ","
 stating that the call
 .RS
 .EX
-setupterm(\fIterm\fP, 1, (int *)0)
+.BI setupterm( term ", 1, (int *)0)"
 .EE
 .RE
-provides the same functionality as \fB\%setterm(\fIterm\fB)\fR,
-discouraging the latter for new programs.
-.I \%ncurses
-implements each of these symbols as macros for BSD
-.I curses
-compatibility.
+provides the same functionality as
+.RS
+.EX
+.BI setterm( term )
+.EE
+.RE
+and discouraging the latter for new programs.
 .SS "Legacy Data"
-\fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP.
+.I \%setupterm
+copies the terminal name to the array
+.IR \%ttytype "."
 This is not part of X/Open Curses,
 but is assumed by some applications.
 .PP
@@ -809,9 +820,15 @@ .SS "Legacy Data"
 .RB \%\*(`` "@TIC@ \-x" \*('',
 are not stored in the arrays described here.
 .SS "Output Buffering"
-Older versions of \fI\%ncurses\fP assumed that the file descriptor
-passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\fP uses
-buffered I/O,
+Older versions of
+.I \%ncurses
+assumed that the file descriptor passed to
+.I \%setupterm
+from
+.I \%initscr
+or
+.I \%newterm
+uses buffered I/O,
 and would write to the corresponding stream.
 In addition to the limitation that the terminal was left in
 block-buffered mode on exit
@@ -822,7 +839,8 @@ .SS "Output Buffering"
 did not allow a reliable way to clean up on receiving
 .BR SIGTSTP .
 .PP
-The current version (ncurses6)
+.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
@@ -863,8 +881,9 @@ .SS "Function Prototypes"
 .I \%ncurses
 ABI 6 enables this feature by default.
 .bP
-X/Open Curses prototypes \fB\%tparm\fP with a fixed number of
-parameters,
+X/Open Curses prototypes
+.I \%tparm
+with a fixed number of parameters,
 rather than a variable argument list.
 .IP
 This implementation uses a variable argument list,
@@ -873,16 +892,27 @@ .SS "Function Prototypes"
 zeroes are fine for this purpose.
 .IP
 In response to review comments by Thomas E. Dickey,
-X/Open Curses Issue 7 proposed the \fB\%tiparm\fP function in mid-2009.
+X/Open Curses Issue 7 proposed the
+.I \%tiparm
+function in mid-2009.
 .IP
-While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP,
-the older form is only available as a build-time configuration option.
+While
+.I \%tiparm
+is always provided in
+.IR \%ncurses ","
+the older form is available only as a build-time configuration option.
 If not specially configured,
-\fB\%tparm\fP is the same as \fB\%tiparm\fP.
+.I \%tparm
+is the same as
+.IR \%tiparm "."
 .PP
-Both forms of \fB\%tparm\fP have drawbacks:
+Both forms of
+.I \%tparm
+have drawbacks.
 .bP
-Most of the calls to \fB\%tparm\fP use only one or two parameters.
+Most calls to
+.I \%tparm
+require only one or two parameters.
 Passing nine on each call is awkward.
 .IP
 Using
@@ -896,7 +926,9 @@ .SS "Function Prototypes"
 .IR long ).
 .bP
 Providing the right number of parameters for a variadic function
-such as \fB\%tiparm\fP can be a problem,
+such as
+.I \%tiparm
+can be a problem,
 in particular for string parameters.
 However,
 only a few
@@ -905,18 +937,26 @@ .SS "Function Prototypes"
 (for instance,
 the ones used for programmable function keys).
 .IP
-The \fI\%ncurses\fP library checks usage of these capabilities,
+The
+.I \%ncurses
+library checks usage of these capabilities,
 and returns
 .B ERR
 if the capability mishandles string parameters.
 But it cannot check if a calling program provides strings in the right
-places for the \fB\%tparm\fP calls.
+places for the
+.I \%tparm
+calls.
 .IP
-The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with
-a table,
-so that it calls \fB\%tparm\fP correctly.
+.IR \%ncurses 's
+\fB\%@TPUT@\fR(1) checks its use of these capabilities with a table,
+so that it calls
+.I \%tparm
+correctly.
 .SS "Special \fITERM\fP treatment"
-If configured to use the terminal driver,
+If
+.I \%ncurses
+is configured to use the terminal driver,
 .\" XXX: as opposed to the Unix terminal driver, termio(s)?
 as with the MinGW port,
 .bP
@@ -979,13 +1019,13 @@ .SH HISTORY
 .PP
 .TS
 lB lB
-lB lx.
+lI lx.
 Function       Description
 _
 fixterm        restore terminal to \*(``in \fIcurses\fP\*('' state
 gettmode       establish current terminal modes
 mvcur  low level cursor motion
-putp   use \fBtputs\fP to send characters via \fIputchar\fP
+putp   use \fItputs\fP to send characters via \fIputchar\fP
 resetterm      set terminal modes to \*(``out of \fIcurses\fP\*(''\
  state
 resetty        reset terminal flags to stored value
@@ -995,7 +1035,7 @@ .SH HISTORY
 setupterm      establish terminal with given type
 tparm  interpolate parameters into string capability
 tputs  apply padding information to a string
-vidattr        like \fBvidputs\fP, but output through \fIputchar\fP
+vidattr        like \fIvidputs\fP, but output through \fIputchar\fP
 vidputs        T{
 write string to terminal, applying specified attributes
 T}
@@ -1009,7 +1049,7 @@ .SH HISTORY
 .PP
 .TS
 lB lB
-lB lx.
+lI lx.
 Function       Description
 _
 tgetent        look up \fItermcap\fP entry for given \fIname\fP
@@ -1026,7 +1066,8 @@ .SH HISTORY
 .I \%term\%info
 programs obtained capability values from the
 .I \%TERMINAL
-structure initialized by \fB\%setupterm\fP.
+structure initialized by
+.IR \%setupterm "."
 .PP
 SVr3 (1987) extended
 .I \%term\%info
@@ -1034,12 +1075,15 @@ .SH HISTORY
 (like the
 .I termcap
 interface),
-and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
+and reusing
+.I \%tgoto
+and
+.IR \%tputs "."
 .PP
 .ne 4v
 .TS
 lB lB
-lB lx.
+lI lx.
 Function       Description
 _
 tigetflag      get Boolean entry for given \fIid\fP
@@ -1056,32 +1100,39 @@ .SH HISTORY
 .PP
 .TS
 lB lB
-l  lx.
+lI lIx.
 Function       Replaced by
 _
 crmode cbreak
 fixterm        reset_prog_mode
-gettmode       \fIn/a\fP
+gettmode       \fRn/a\fP
 nocrmode       nocbreak
 resetterm      reset_shell_mode
 saveterm       def_prog_mode
 setterm        setupterm
 .TE
 .PP
-SVr3 kept the \fB\%mvcur\fP,
-\fB\%vidattr\fP,
-and \fB\%vidputs\fP functions,
-along with \fB\%putp\fP,
-\fB\%tparm\fP,
-and \fB\%tputs\fP.
+SVr3 kept the
+.IR \%mvcur ","
+.IR \%vidattr ","
+and
+.I \%vidputs
+functions,
+along with
+.IR \%putp ","
+.IR \%tparm ","
+and
+.IR \%tputs "."
 The latter were needed to support padding,
-and to handle capabilities accessed by functions such as \fB\%vidattr\fP
-(which used more than the two parameters supported by \fB\%tgoto\fP).
+and to handle capabilities accessed by functions such as
+.I \%vidattr
+(which used more than the two parameters supported by
+.IR \%tgoto ")."
 .PP
 SVr3 introduced the functions for switching between terminal
 descriptions;
 for example,
-\fB\%set_curterm\fP.
+.IR \%set_curterm "."
 Some changes reflected incremental improvements to the SVr2 library.
 .bP
 The
@@ -1091,11 +1142,16 @@ .SH HISTORY
 .I term
 structure provided in SVr2.
 .bP
-Various global variables such as \fB\%boolnames\fP were mentioned
-in the programming manual at this point,
+Various global variables such as
+.I \%boolnames
+were mentioned in the programming manual at this point,
 though the variables had been provided in SVr2.
 .PP
-SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions.
+SVr4 (1989) added the
+.I \%vid_attr
+and
+.I \%vid_puts
+functions.
 .PP
 Other low-level functions are declared in the
 .I curses
-- 
2.30.2

signature.asc
Description: PGP signature