[PATCH 40/40] man/curs_terminfo.3x: Revise.

[G. Branden Robinson]

Content:
* Migrate terminology: "routine" -> "function".
* Set capability names first, with the terminfo code for it following in
  parentheses.
* Say "X/Open Curses" instead of just "X/Open"; that organization
  produces more than one standard.
* Say "terminal" instead of "tty".

Style:
* Set "curses" in italics, not roman.
* Set "long" C data type in italics, not bold or roman.
* Set function parameter literals in bold, not roman.
* Use `EX`/`EE` macros to set (one-line) code examples (setupterm,
  del_curterm).
* Protect variable literals "lines" and "columns" from automatic
  hyphenation.
* Protect function names from automatic hyphenation: tparm, tputs, putp,
  reset_shell_mode, reset_prog_mode, tiparm, tiscan_s, tgetstr, tgoto,
  and so forth.
* Protect man page topic names from automatic hyphenation.
* Protect capability names from automatic hyphenation: enter_ca_mode,
  exit_ca_mode.
* Use "that", not "which", with restrictive subordinate clauses.
* Tighten wording.
* Fix run-on sentence and other grammar nits.
* Quote an inline example of a function call.
* Favor present tense over future.
* Favor active voice over passive.
* Quote section title cross references.
* Replace colons dangling at the ends of sentences with English.
* Favor English phrases over Latin abbreviations.
* Permit a break within a quoted inline code example ("tic -x"), since
  the quotation marks clearly delimit its boundaries.
* Spell out small integers used narratively instead of as code examples.

Markup:
* Break input lines after commas and around multi-word parentheticals.
* Refill some input lines.
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross (and topic self-)references.
* Annotate an unclear point with a *roff comment.
* Drop hyphenation control escape sequence from a non-text-block table
  entry, where they are not necessary.
* Break long input line in table with \newline escape sequence.
---
 man/curs_terminfo.3x | 632 +++++++++++++++++++++++++++----------------
 1 file changed, 406 insertions(+), 226 deletions(-)

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index e8da78165..1f7af6591 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -116,14 +116,14 @@ .SH SYNOPSIS
 \fBint setterm(const char *\fIterm\fP);
 .fi
 .SH DESCRIPTION
-These low-level routines must be called by programs that have to deal
-directly with the
+These low-level functions must be called by programs that deal directly
+with the
 .I \%term\%info
 database to handle certain terminal capabilities,
 such as programming function keys.
 For all other functionality,
 .I curses
-routines are more suitable and their use is recommended.
+functions are more suitable and their use is recommended.
 .PP
 None of these functions use
 (or are aware of)
@@ -139,11 +139,10 @@ .SS Initialization
 The high-level
 .I curses
 functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to
-initialize the low-level set of terminal-dependent variables
-listed in \fB\%term_variables\fP(3X).
+initialize the low-level set of terminal-dependent variables listed in
+\fB\%term_variables\fP(3X).
 .PP
-Applications can use the
-terminal capabilities either directly
+Applications can use the terminal capabilities either directly
 (via header definitions),
 or by special functions.
 The header files
@@ -152,57 +151,77 @@ .SS Initialization
 .I \%term.h
 should be included
 (in that order)
-to get the definitions for these strings, numbers, and flags.
+to get the definitions for these strings,
+numbers,
+and flags.
 .PP
 The
 .I \%term\%info
 variables
-\fBlines\fP and \fBcolumns\fP are initialized by \fB\%setupterm\fP as
-follows:
+.B \%lines
+and
+.B \%columns
+are initialized by \fB\%setupterm\fP as follows.
 .bP
 If \fB\%use_env(FALSE)\fP has been called,
-values for \fBlines\fP and \fBcolumns\fP specified in
+values for
+.B \%lines
+and
+.B \%columns
+specified in
 .I \%term\%info
 are used.
 .bP
 Otherwise,
-if the environment variables \fILINES\fP and \fI\%COLUMNS\fP exist,
+if the environment variables
+.I LINES
+and
+.I \%COLUMNS
+exist,
 their values are used.
-If these environment variables do not
-exist and the program is running in a window, the current window size
+If these environment variables do not exist and the program is running
+in a window,
+the current window size
 is used.
-Otherwise, if the environment variables do not exist, the
-values for \fBlines\fP and \fBcolumns\fP specified in the
+Otherwise,
+if the environment variables do not exist,
+the values for
+.B \%lines
+and
+.B \%columns
+specified in the
 .I \%term\%info
 database are used.
 .PP
-Parameterized strings should be passed through \fBtparm\fP to instantiate them.
+Parameterized strings should be passed through \fB\%tparm\fP to
+instantiate them.
 All
 .I \%term\%info
 strings
-(including the output of \fBtparm\fP)
-should be printed
-with \fBtputs\fP or \fBputp\fP.
-Call \fBreset_shell_mode\fP to restore the
-tty modes before exiting [see \fBcurs_kernel\fP(3X)].
-.PP
-Programs which use
+(including the output of \fB\%tparm\fP)
+should be sent to the terminal device with \fB\%tputs\fP or
+\fB\%putp\fP.
+Call \fB\%reset_shell_mode\fP to restore the terminal modes before
+exiting;
+see \fB\%curs_kernel\fP(3X).
+.PP
+Programs that use
 cursor addressing should
 .bP
-output \fBenter_ca_mode\fP upon startup and
+output \fB\%enter_ca_mode\fP upon startup and
 .bP
-output \fBexit_ca_mode\fP before exiting.
+output \fB\%exit_ca_mode\fP before exiting.
 .PP
-Programs which execute shell subprocesses should
+Programs that execute shell subprocesses should
 .bP
-call \fBreset_shell_mode\fP and
-output \fBexit_ca_mode\fP before the shell
+call \fB\%reset_shell_mode\fP and
+output \fB\%exit_ca_mode\fP before the shell
 is called and
 .bP
-output \fBenter_ca_mode\fP and
-call \fBreset_prog_mode\fP after returning from the shell.
+output \fB\%enter_ca_mode\fP and
+call \fB\%reset_prog_mode\fP after returning from the shell.
 .PP
-The \fB\%setupterm\fP routine reads in the
+\fB\%setupterm\fP reads in the
 .I \%term\%info
 database,
 initializing the
@@ -210,49 +229,84 @@ .SS Initialization
 structures,
 but does not set up the output virtualization structures used by
 .I curses.
-These are its parameters:
+Its parameters follow.
 .RS 3
 .TP 5
-\fIterm\fP
-is the terminal type, a character string.
-If \fIterm\fP is null,
-the environment variable \fITERM\fP is used.
+.I term
+is the terminal type,
+a character string.
+If
+.I term
+is null,
+the environment variable
+.I TERM
+is read.
 .TP 5
-\fIfiledes\fP
+.I filedes
 is the file descriptor used for getting and setting terminal I/O modes.
 .IP
-Higher-level applications use \fBnewterm\fP(3X) for initializing the terminal,
-passing an output \fIstream\fP rather than a \fIdescriptor\fP.
-In curses, the two are the same because \fBnewterm\fP calls \fBsetupterm\fP,
+Higher-level applications use \fB\%newterm\fP(3X) to initialize the
+terminal,
+passing an output
+.I stream
+rather than a
+.I descriptor.
+In
+.I curses,
+the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
 passing the file descriptor derived from its output stream parameter.
 .TP 5
-\fIerrret\fP
+.I errret
 points to an optional location where an error status can be returned to
 the caller.
-If \fIerrret\fP is not null,
-then \fBsetupterm\fP returns \fBOK\fP or
-\fBERR\fP and stores a status value in the integer pointed to by
-\fIerrret\fP.
-A return value of \fBOK\fP combined with status of \fB1\fP in \fIerrret\fP
+If
+.I errret
+is not null,
+then \fB\%setupterm\fP returns
+.B OK
+or
+.B ERR
+and stores a status value in the integer pointed to by
+.I errret.
+A return value of
+.B OK
+combined with status of
+.B 1
+in
+.I errret
 is normal.
 .IP
-If \fBERR\fP is returned, examine \fIerrret\fP:
+If
+.B ERR
+is returned,
+examine
+.I errret:
 .RS
 .TP 5
 .B 1
-means that the terminal is hardcopy, cannot be used
-for \fIcurses\fP applications.
+means that the terminal is hardcopy,
+and cannot be used for
+.I curses
+applications.
 .IP
 \fB\%setupterm\fP determines if the entry is a hardcopy type by
-checking the \fBhc\fP (\fBhardcopy\fP) capability.
+checking the
+.B \%hardcopy
+.RB ( hc )
+capability.
 .TP 5
 .B 0
 means that the terminal could not be found,
 or that it is a generic type,
-having too little information for \fIcurses\fP applications to run.
+having too little information for
+.I curses
+applications to run.
 .IP
 \fB\%setupterm\fP determines if the entry is a generic type by
-checking the \fBgn\fP \%(\fBgeneric_type\fP) capability.
+checking the
+.B \%generic_type
+.RB ( gn )
+capability.
 .TP 5
 .B \-1
 means that the
@@ -260,31 +314,40 @@ .SS Initialization
 database could not be found.
 .RE
 .IP
-If \fIerrret\fP is
-null, \fB\%setupterm\fP prints an error message upon finding an error
-and exits.
-Thus, the simplest call is:
+If
+.I errret
+is null,
+\fB\%setupterm\fP reports an error message upon finding an error and
+exits.
+Thus,
+the simplest call is:
 .RS
 .IP
-\fBsetupterm((char *)0, 1, (int *)0);\fP
+.EX
+setupterm((char *)0, 1, (int *)0);
+.EE
 .RE
 .IP
-which uses all the defaults and sends the output to \fBstdout\fP.
+which uses all the defaults and sends the output to
+.BR stdout .
 .RE
-.\" ***************************************************************************
+.\" ********************************************************************
 .SS "The Terminal State"
-The \fBsetupterm\fP routine stores its information about the terminal
-in a \fI\%TERMINAL\fP structure pointed to by the global variable 
\fBcur_term\fP.
+\fB\%setupterm\fP stores its information about the terminal in a
+.I \%TERMINAL
+structure pointed to by the global variable \fB\%cur_term\fP.
 If it detects an error,
-or decides that the terminal is unsuitable (hardcopy or generic),
+or decides that the terminal is unsuitable
+(hardcopy or generic),
 it discards this information,
 making it not available to applications.
 .PP
-If \fBsetupterm\fP is called repeatedly for the same terminal type,
+If \fB\%setupterm\fP is called repeatedly for the same terminal type,
 it will reuse the information.
 It maintains only one copy of a given terminal's capabilities in memory.
 If it is called for different terminal types,
-\fBsetupterm\fP allocates new storage for each set of terminal capabilities.
+\fB\%setupterm\fP allocates new storage for each set of terminal
+capabilities.
 .PP
 \fB\%set_curterm\fP sets \fB\%cur_term\fP to
 .I \%nterm,
@@ -296,7 +359,7 @@ .SS "The Terminal State"
 .I \%nterm.
 It returns the old value of \fB\%cur_term\fP.
 .PP
-\fB\%del_curterm\fP routine frees the space pointed to by
+\fB\%del_curterm\fP frees the space pointed to by
 .I \%oterm
 and makes it available for further use.
 If
@@ -310,29 +373,42 @@ .SS "The Terminal State"
 and string variables thereafter may refer to invalid memory locations
 until another \fB\%setupterm\fP has been called.
 .PP
-The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\fP,
-except that it is called after restoring memory to a previous state (for
-example, when reloading a game saved as a core image dump).
-\fBrestartterm\fP assumes that the windows and the input and output options
-are the same as when memory was saved,
+\fB\%restartterm\fP is similar to \fB\%setupterm\fP and \fB\%initscr\fP,
+except that it is called after restoring memory to a previous state
+(for example,
+when reloading a game saved as a core image dump).
+\fB\%restartterm\fP assumes that the windows and the input and output
+options are the same as when memory was saved,
 but the terminal type and baud rate may be different.
-Accordingly, \fBrestartterm\fP saves various tty state bits,
-calls \fBsetupterm\fP, and then restores the bits.
-.\" ***************************************************************************
+Accordingly,
+\fB\%restartterm\fP saves various terminal state bits,
+calls \fB\%setupterm\fP,
+and then restores the bits.
+.\" ********************************************************************
 .SS "Formatting Output"
-The \fBtparm\fP routine instantiates the string \fIstr\fP with
-parameters \fIpi\fP.  A pointer is returned to the result of \fIstr\fP
+\fB\%tparm\fP instantiates the string
+.I str
+with parameters
+.I pi.
+A pointer is returned to the result of
+.I str
 with the parameters applied.
-Application developers should keep in mind these quirks of the interface:
+Application developers should keep in mind these quirks of the
+interface:
 .bP
-Although \fBtparm\fP's actual parameters may be integers or strings,
-the prototype expects \fBlong\fP (integer) values.
+Although \fB\%tparm\fP's actual parameters may be integers or strings,
+the prototype expects
+.I long
+(integer) values.
 .bP
-Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
+Aside from the
+.B \%set_attributes\fP
+.RB ( sgr )
+capability,
 most terminal capabilities require no more than one or two parameters.
 .bP
-Padding information is ignored by \fBtparm\fP;
-it is interpreted by \fBtputs\fP.
+Padding information is ignored by \fB\%tparm\fP;
+it is interpreted by \fB\%tputs\fP.
 .bP
 The capability string is null-terminated.
 Use \*(``\e200\*('' where an ASCII NUL is needed in the output.
@@ -345,22 +421,28 @@ .SS "Formatting Output"
 rather than
 .IR long s.
 .PP
-Both \fBtparm\fP and \fBtiparm\fP assume that the application passes
+Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
 parameters consistent with the terminal description.
-Two extensions are provided as alternatives to deal with untrusted data:
+Two extensions are provided as alternatives to deal with untrusted data.
 .bP
-\fBtiparm_s\fP is an extension which is a safer formatting function
-than \fBtparm\fR or \fBtiparm\fR,
-because it allows the developer to tell the curses
+\fB\%tiparm_s\fP is an extension which is a safer formatting function
+than \fB\%tparm\fR or \fB\%tiparm\fR,
+because it allows the developer to tell the
+.I curses
 library how many parameters to expect in the parameter list,
 and which may be string parameters.
 .IP
 The \fImask\fP parameter has one bit set for each of the parameters
-(up to 9) which will be passed as char* rather than numbers.
+(up to 9)
+passed as
+.I char
+pointers rather than numbers.
 .bP
-The extension \fBtiscan_s\fP allows the application
-to inspect a formatting capability to see what the curses library would assume.
-.\" ***************************************************************************
+The extension \fB\%tiscan_s\fP allows the application to inspect a
+formatting capability to see what the
+.I curses
+library would assume.
+.\" ********************************************************************
 .SS "Output Functions"
 String capabilities can contain padding information,
 a time delay
@@ -371,41 +453,65 @@ .SS "Output Functions"
 (thirty seconds),
 it is capped at that value.
 .PP
-The \fBtputs\fP routine interprets time-delay information in the string
-\fIstr\fP and outputs it, executing the delays:
+\fB\%tputs\fP interprets time-delay information in the string
+.I str
+and outputs it,
+executing the delays:
 .bP
-The \fIstr\fP parameter must be a terminfo string
-variable or the return value from
-\fBtparm\fP, \fBtiparm\fP, \fBtgetstr\fP, or \fBtgoto\fP.
+The
+.I str
+parameter must be a
+.I \%term\%info
+string variable or the return value of
+\fB\%tparm\fP,
+\fB\%tiparm\fP,
+\fB\%tgetstr\fP,
+or \fB\%tgoto\fP.
 .IP
-The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP
+The \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the
+.I termcap
 interface,
-which happens to share this function name with the
+which happens to share these function names with the
 .I \%term\%info
-interface.
+API.
 .bP
-\fIaffcnt\fP is the number of lines affected, or 1 if
-not applicable.
+.I affcnt
+is the number of lines affected,
+or
+.B 1
+if not applicable.
 .bP
-\fIputc\fP is a \fI\%putchar\fP-like function to which
-the characters are passed, one at a time.
+.I putc
+is a
+.IR \%putchar -like
+function to which the characters are passed,
+one at a time.
 .IP
-If \fBtputs\fP processes a time-delay,
-it uses the \fBdelay_output\fP(3X) function,
+If \fB\%tputs\fP processes a time-delay,
+it uses the \fB\%delay_output\fP(3X) function,
 routing any resulting padding characters through this function.
 .PP
-The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, \%putchar)\fR.
-The output of \fBputp\fP always goes to \fBstdout\fP, rather than
-the \fIfiledes\fP specified in \fBsetupterm\fP.
-.PP
-The \fBvidputs\fP routine displays the string on the terminal in the
-video attribute mode \fIattrs\fP, which is any combination of the
-attributes listed in \fBcurses\fP(3X).
-The characters are passed to
-the \fI\%putchar\fP-like function \fIputc\fP.
-.PP
-The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except
-that it outputs through \fI\%putchar\fP.
+\fB\%putp\fR calls
+.RB \%\*(`` tputs(\c
+.IB str ", 1, putchar)\c
+\*(''.
+The output of \fB\%putp\fP always goes to
+.BR stdout ,
+rather than the
+.I \%file\%des
+specified in \fB\%setupterm\fP.
+.PP
+\fB\%vidputs\fP displays the string on the terminal in the video
+attribute mode
+.I attrs,
+which is any combination of the attributes listed in \fB\%curses\fP(3X).
+The characters are passed to the
+.IR \%putchar -like
+function
+.I putc.
+.PP
+\fB\%vidattr\fP is like \fB\%vidputs\fP,
+except that it outputs through \fI\%putchar\fP(3).
 .PP
 .B \%vid_attr
 and
@@ -442,62 +548,83 @@ .SS "Output Functions"
 saying that applications must provide a null pointer for that argument;
 but see section \*(``EXTENSIONS\*('' below.
 .PP
-The \fBmvcur\fP routine provides low-level cursor motion.
-It takes effect immediately (rather than at the next refresh).
+\fB\%mvcur\fP provides low-level cursor motion.
+It takes effect immediately
+(rather than at the next refresh).
 Unlike the other low-level output functions,
-which either write to the standard output or pass an output function parameter,
-\fBmvcur\fP uses an output file descriptor derived from
-the output stream parameter of \fBnewterm\fP(3X).
+which either write to the standard output or pass an output function
+parameter,
+\fB\%mvcur\fP uses an output file descriptor derived from
+the output stream parameter of \fB\%newterm\fP(3X).
 .PP
-While \fBputp\fP and \fBmvcur\fP are low-level functions which
-do not use the high-level curses state,
-they are declared in
+While \fB\%putp\fP and \fB\%mvcur\fP are low-level functions that do not
+use high-level
+.I curses
+state,
+.I \%ncurses
+declares them in
 .I \%curses.h
 because System\ V did this
-(see \fIHISTORY\fP).
-.\" ***************************************************************************
+(see section \*(``HISTORY\*('' below).
+.\" ********************************************************************
 .SS "Terminal Capability Functions"
-The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return
-the value of the capability corresponding to the
+\fB\%tigetflag\fP,
+\fB\%tigetnum\fP,
+and \fB\%tigetstr\fP return the value of the capability corresponding to
+the
 .I \%term\%info
-\fIcap-code\fP passed to them, such as \fBxenl\fP.
-The \fIcap-code\fP for each capability is given in the table column entitled
-\fIcap-code\fP code in the capabilities section of \fB\%terminfo\fP(5).
+.I cap-code,
+such as
+.BR xenl ,
+passed to them.
+The
+.I cap-code
+for each capability is given in the table column entitled
+.I cap-code
+code in the capabilities section of \fB\%terminfo\fP(5).
 .PP
-These routines return special values to denote errors.
+These functions return special values to denote errors.
 .PP
-The \fBtigetflag\fP routine returns
+\fB\%tigetflag\fP returns
 .TP
-\fB\-1\fP
-if \fIcap-code\fP is not a Boolean capability,
+.B \-1
+if
+.I cap-code
+is not a Boolean capability,
 or
 .TP
-\fB0\fP
+.B 0
 if it is canceled or absent from the terminal description.
 .PP
-The \fBtigetnum\fP routine returns
+\fB\%tigetnum\fP returns
 .TP
-\fB\-2\fP
-if \fIcap-code\fP is not a numeric capability, or
+.B \-2
+if
+.I cap-code
+is not a numeric capability,
+or
 .TP
-\fB\-1\fP
+.B \-1
 if it is canceled or absent from the terminal description.
 .PP
-The \fBtigetstr\fP routine returns
+\fB\%tigetstr\fP returns
 .TP
-\fB(char *)\-1\fP
-if \fIcap-code\fP is not a string capability,
+.B "(char *)\-1"
+if
+.I cap-code
+is not a string capability,
 or
 .TP
-\fB0\fP
+.B 0
 if it is canceled or absent from the terminal description.
-.\" ***************************************************************************
+.\" ********************************************************************
 .SS "Terminal Capability Names"
 These null-terminated arrays contain
 .bP
 the short \fI\%term\%info\fP names (\*(``codes\*(''),
 .bP
-the \fItermcap\fP names (\*(``names\*(''), and
+the \fItermcap\fP names (\*(``names\*(''),
+and
 .bP
 the long \fI\%term\%info\fP names (\*(``fnames\*('')
 .PP
@@ -512,71 +639,90 @@ .SS "Terminal Capability Names"
 \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
 .fi
 .RE
-.\" ***************************************************************************
+.\" ********************************************************************
 .SS "Releasing Memory"
-Each successful call to \fBsetupterm\fP allocates memory to hold the terminal
-description.
-As a side-effect, it sets \fBcur_term\fP to point to this memory.
+Each successful call to \fB\%setupterm\fP allocates memory to hold the
+terminal description.
+As a side effect,
+it sets \fB\%cur_term\fP to point to this memory.
 If an application calls
 .IP
-\fBdel_curterm(cur_term);\fP
+.EX
+del_curterm(cur_term);
+.EE
 .PP
 the memory will be freed.
 .PP
-The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage
-allocated by \fBsetupterm\fP:
+The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
+storage allocated by \fB\%setupterm\fP as follows.
 .bP
-the \*(``static\*('' terminfo variables [a-z].
-Before \fI\%ncurses\fP 6.3, those were shared by all screens.
-With \fI\%ncurses\fP 6.3, those are allocated per screen.
-See \fB\%terminfo\fP(5) for details.
+They add the \*(``static\*(''
+.I \%term\%info
+variables [a-z].
+Before
+.I \%ncurses
+6.3,
+those were shared by all screens.
+With
+.I \%ncurses
+6.3,
+those are allocated per screen.
+See \fB\%terminfo\fP(5).
 .bP
-to improve performance,
-\fI\%ncurses\fP 6.3 caches the result of analyzing terminfo
+To improve performance,
+.I \%ncurses
+6.3 caches the result of analyzing
+.I \%term\%info
 strings for their parameter types.
-That is stored as a binary tree referenced from the \fI\%TERMINAL\fP structure.
+That is stored as a binary tree referenced from the
+.I \%TERMINAL
+structure.
 .PP
-The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP.
-Normally they do not free this memory, but it is possible to do that using
-the \fBdelscreen\fP(3X) function.
-.\" ***************************************************************************
+The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use
+\fB\%setupterm\fP.
+Normally they do not free this memory,
+but it is possible to do that using the \fB\%delscreen\fP(3X) function.
+.\" ********************************************************************
 .SH RETURN VALUE
-X/Open defines no failure conditions.
+X/Open Curses defines no failure conditions.
 In
 .I \%ncurses,
 .TP 5
-\fBdel_curterm\fP
-returns an error
-if its terminal parameter is null.
+.B del_curtem
+fails if its terminal parameter is null.
 .TP 5
-\fBputp\fP
-calls \fBtputs\fP, returning the same error-codes.
+.B putp
+calls \fB\%tputs\fP,
+returning the same error codes.
 .TP 5
-\fBrestartterm\fP
-returns an error
-if the associated call to \fBsetupterm\fP returns an error.
+.B restartterm
+fails if the associated call to \fB\%setupterm\fP returns an error.
 .TP 5
-\fBsetupterm\fP
-returns an error
-if it cannot allocate enough memory, or
-create the initial windows
+.B setupterm
+fails if it cannot allocate enough memory,
+or create the initial windows
 .RB ( \%stdscr ,
 .BR \%curscr ,
 and
 .BR \%newscr )
 Other error conditions are documented above.
 .TP 5
-\fBtparm\fP
-returns a null if the capability would require unexpected parameters,
-e.g., too many, too few, or incorrect types
-(strings where integers are expected, or vice versa).
+.B tparm
+returns a null pointer if the capability would require unexpected
+parameters;
+that is,
+too many,
+too few,
+or incorrect types
+(strings where integers are expected,
+or vice versa).
 .TP 5
-\fBtputs\fP
-returns an error if the string parameter is null.
+.B tputs
+fails if the string parameter is null.
 It does not detect I/O errors:
-X/Open Curses states that \fBtputs\fP ignores the return value
-of the output function \fIputc\fP.
-.\" ***************************************************************************
+X/Open Curses states that \fB\%tputs\fP ignores the return value
+of the output function \fI\%putc\fP.
+.\" ********************************************************************
 .SH NOTES
 The
 .B \%vid_attr
@@ -590,7 +736,7 @@ .SH NOTES
 wide-character API were developed,
 and unlike the other wide-character functions,
 is also provided in the non-wide-character configuration.
-.\" ***************************************************************************
+.\" ********************************************************************
 .SH EXTENSIONS
 The functions marked as extensions were designed for
 .I \%ncurses,
@@ -598,7 +744,9 @@ .SH EXTENSIONS
 .IR curses ,
 4.4BSD
 .IR curses ,
-or any other previous curses implementation.
+or any other previous
+.I curses
+implementation.
 .PP
 .I \%ncurses
 allows
@@ -609,7 +757,7 @@ .SH EXTENSIONS
 .I pair
 .RI ( short )
 argument.
-.\" ***************************************************************************
+.\" ********************************************************************
 .SH PORTABILITY
 \fB\%setterm\fP is not described by X/Open and must be considered
 non-portable.
@@ -624,7 +772,8 @@ .SS "Compatibility Macros"
 \fB\%Bgettmode\fP,
 \fB\%Bnocrmode\fP,
 \fB\%Bresetterm\fP,
-\fB\%Bsaveterm\fP, and
+\fB\%Bsaveterm\fP,
+and
 \fB\%Bsetterm\fP.
 .PP
 In SVr4,
@@ -650,7 +799,8 @@ .SS "Compatibility Macros"
 compatibility.
 .SS "Legacy Data"
 \fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP.
-This is not part of X/Open Curses, but is assumed by some applications.
+This is not part of X/Open Curses,
+but is assumed by some applications.
 .PP
 Other implementions may not declare the capability name arrays.
 Some provide them without declaring them.
@@ -658,7 +808,7 @@ .SS "Legacy Data"
 .PP
 Extended terminal capability names,
 as defined by
-.RB \%\*(`` "@TIC@\ \-x" \*('',
+.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
@@ -716,9 +866,9 @@ .SS "Function Prototypes"
 parameters,
 rather than a variable argument list.
 .IP
-This implementation uses a variable argument list, but can be
-configured to use the fixed-parameter list.
-Portable applications should provide 9 parameters after the format;
+This implementation 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.
 .IP
 In response to review comments by Thomas E. Dickey,
@@ -738,15 +888,22 @@ .SS "Function Prototypes"
 .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, before C was standardized.
-Since then, there is a standard
-(and pointers are not required to fit in a long).
+That approach dates back to the mid-1980s,
+before C was standardized.
+Since then,
+there is a standard
+(and pointers are not required to fit in a
+.IR long ).
 .bP
 Providing the right number of parameters for a variadic function
 such as \fB\%tiparm\fP can be a problem,
 in particular for string parameters.
-However, only a few terminfo capabilities use string parameters
-(e.g., the ones used for programmable function keys).
+However,
+only a few
+.I \%term\%info
+capabilities use string parameters
+(for instance,
+the ones used for programmable function keys).
 .IP
 The \fI\%ncurses\fP library checks usage of these capabilities,
 and returns an error if the capability mishandles string parameters.
@@ -757,17 +914,22 @@ .SS "Function Prototypes"
 a table,
 so that it calls \fB\%tparm\fP correctly.
 .SS "Special \fITERM\fP treatment"
-If configured to use the terminal-driver,
-e.g., for the MinGW port,
+If configured to use the terminal driver,
+.\" 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\*(''.
 .IP
-SVr4 curses uses the
-special value \*(``dumb\*(''.
+SVr4
+.I curses
+uses the special value \*(``dumb\*(''.
 .IP
-The difference between the two is that
-the former uses the \fBgn\fP (\fB\%generic_type\fR) terminfo capability,
+The difference between the two is that the former uses the
+.B \%generic_type
+.RB ( gn )
+.I \%term\%info
+capability,
 while the latter does not.
 A generic terminal is unsuitable for full-screen applications.
 .bP
@@ -818,14 +980,27 @@ .SS "Other Portability Issues"
 .I curses
 function that is not well specified.
 .PP
-X/Open notes that after calling \fBmvcur\fP, the curses state may not match the
-actual terminal state, and that an application should touch and refresh
-the window before resuming normal curses calls.
-Both \fI\%ncurses\fP and System V Release 4 curses implement \fBmvcur\fP
-using the \fISCREEN\fP data allocated in either \fBinitscr\fP or
-\fBnewterm\fP.
-So though it is documented as a terminfo function,
-\fBmvcur\fP is really a curses function which is not well specified.
+X/Open notes that after calling \fB\%mvcur\fP,
+the
+.I curses
+state may not match the actual terminal state,
+and that an application should touch and refresh the window before
+resuming normal
+.I curses
+calls.
+Both
+.I \%ncurses
+and SVr4
+.I curses
+implement \fB\%mvcur\fP using the
+.I SCREEN
+data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
+So though it is documented as a
+.I \%term\%info
+function,
+\fB\%mvcur\fP is really a
+.I curses
+function that is not well specified.
 .PP
 X/Open Curses states that the old location must be given for
 \fB\%mvcur\fP to accommodate terminals that lack absolute cursor
@@ -836,10 +1011,14 @@ .SS "Other Portability Issues"
 The \-1 tells
 .I \%ncurses
 that the old location is unknown,
-and that it must use only absolute motion
-(such as \fI\%cursor_address\fP)
-rather than the least costly combination of absolute and relative motion.
-.\" ***************************************************************************
+and that it must use only absolute motion,
+as with the
+.B \%cursor_address
+.RB ( cup )
+capability,
+rather than the least costly combination of absolute and relative
+motion.
+.\" ********************************************************************
 .SH HISTORY
 SVr2 (1984) introduced the
 .I \%term\%info
@@ -851,14 +1030,15 @@ .SH HISTORY
 lB lx.
 Function       Description
 _
-fixterm        restore tty to \*(``in curses\*('' state
-gettmode       establish current tty modes
+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 \fI\%putchar\fP
-resetterm      set tty modes to \*(``out of curses\*('' state
-resetty        reset tty flags to stored value
-saveterm       save current modes as \*(``in curses\*('' state
-savetty        store current tty flags
+putp   use \fBtputs\fP to send characters via \fIputchar\fP
+resetterm      set terminal modes to \*(``out of \fIcurses\fP\*(''\
+ state
+resetty        reset terminal flags to stored value
+saveterm       save current modes as \*(``in \fIcurses\fP\*('' state
+savetty        store current terminal flags
 setterm        establish terminal with given type
 setupterm      establish terminal with given type
 tparm  interpolate parameters into string capability
-- 
2.30.2

signature.asc
Description: PGP signature