[PATCH 08/19] man/curs_initscr.3x: Fix content, style, and markup nits.

[G. Branden Robinson]

Content:
* Refer to terminfo capabilities by both name and code.
* Promote mention `wrefresh()` to man page cross reference.
* Clarify applications of `endwin()`, `set_term()`, and `delscreen()`.
* Relocate mention of X/Open Curses's underspecification of error
  returns from "RETURN VALUE" to "PORTABILITY".

Style:
* Parallelize wording of "RETURN VALUE" section with that of other
  recently edited ncurses man pages.
* Protect function names from hyphenation.
* Favor "terminal" over "tty".
* Favor "ncurses" over "this implementation".
* Set names of C objects defined externally to ncurses in italics, not
  bold.

Markup:
* Break input lines after commas and around multi-word parentheticals.
* 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 punctuation-only second arguments to `BR` and `IR` macros, to
  avoid false positives reported by one of Thomas Dickey's
  style-checking scripts, per his communication.
---
 man/curs_initscr.3x | 244 +++++++++++++++++++++++++++++---------------
 1 file changed, 162 insertions(+), 82 deletions(-)

diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x
index 673d105d9..091fa13b0 100644
--- a/man/curs_initscr.3x
+++ b/man/curs_initscr.3x
@@ -70,7 +70,6 @@ .SS initscr
 .B \%initscr
 determines the terminal type and initializes the library's
 .IR SCREEN ","
-and
 .IR WINDOW ","
 and other data structures.
 It is normally the first
@@ -147,7 +146,10 @@ .SS newterm
 It returns a variable of structure type
 .I SCREEN
 .BR * ","
-which should be saved as a reference to that terminal.
+which should be saved for later use with
+.B \%set_term
+and
+.BR \%delscreen "."
 .PP
 .B \%newterm
 passes the file descriptor of the output stream to the
@@ -180,13 +182,23 @@ .SS newterm
 interface.
 .SS endwin
 The program must also call
-\fBendwin\fP for each terminal being used before exiting from \fBcurses\fP.
-If \fBnewterm\fP is called more than once for the same terminal, the first
-terminal referred to must be the last one for which \fBendwin\fP is called.
+.B \%endwin
+for each terminal being used before exiting from
+.IR curses "."
+If
+.B \%newterm
+is called more than once for the same terminal,
+the first terminal referred to must be the last one for which
+.B \%endwin
+is called.
 .PP
-A program should always call \fBendwin\fP before exiting or escaping from
-\fBcurses\fP mode temporarily.
-This routine
+A program should always call
+.B \%endwin
+before exiting the application
+or temporarily suspending
+.IR curses "'s"
+management of the terminal.
+.BR \%endwin ":"
 .bP
 resets colors to correspond with the default color pair 0,
 .bP
@@ -194,132 +206,200 @@ .SS endwin
 .bP
 clears the remainder of the line so that it uses the default colors,
 .bP
-sets the cursor to normal visibility (see \fBcurs_set\fP(3X)),
+sets the cursor to normal visibility
+(see \fB\%curs_set\fP(3X)),
 .bP
-stops cursor-addressing mode using the \fIexit_ca_mode\fP terminal capability,
+if applicable,
+stops cursor-addressing mode using the
+.B \%exit_ca_mode
+.RB \%( rmcup )
+terminal capability,
+and
 .bP
-restores tty modes (see \fBreset_shell_mode\fP(3X)).
+restores terminal modes (see \fB\%reset_shell_mode\fP(3X)).
 .PP
-Calling \fB\%refresh\fP(3X) or \fBdoupdate\fP(3X) after a
-temporary escape causes the program to resume visual mode.
+Calling \fB\%refresh\fP(3X) or \fB\%doupdate\fP(3X) after a
+temporary escape causes
+.I curses
+to resume managing the terminal.
 .SS isendwin
-The \fBisendwin\fP routine returns \fBTRUE\fP if \fBendwin\fP has been
-called without any subsequent calls to \fB\%wrefresh\fP,
-and \fBFALSE\fP otherwise.
+.B \%isendwin
+returns
+.B TRUE
+if
+.B \%endwin
+has been called without any subsequent calls to \fB\%wrefresh\fP(3X),
+and
+.B FALSE
+otherwise.
 .SS set_term
-The \fBset_term\fP routine is used to switch between different terminals.
-The screen reference \fInew\fP becomes the new current terminal.
-The previous terminal is returned by the routine.
-This is the only routine which manipulates \fISCREEN\fP pointers;
-all other routines affect only the current terminal.
+.B \%set_term
+re-orients the
+.I curses
+library's operations to another terminal
+when the application has arranged to manage more than one with
+.BR \%newterm "."
+.B \%set_term
+expects a
+.I SCREEN
+pointer previously returned by
+.B \%newterm
+as an argument,
+and returns the previous one.
+.B \%set_term
+is the only
+.I curses
+API function that manipulates
+.I SCREEN
+pointers;
+all others affect only the current terminal.
 .SS delscreen
-The \fBdelscreen\fP routine frees storage associated with the
-\fISCREEN\fP data structure.
-The \fBendwin\fP routine does not do
-this, so \fBdelscreen\fP should be called after \fBendwin\fP if a
-particular \fISCREEN\fP is no longer needed.
+.B \%delscreen
+frees the storage backing the supplied
+.I SCREEN
+pointer argument.
+.B \%endwin
+does not,
+so that an application can resume managing a terminal with
+.I curses
+after a
+(possibly conditional or temporary)
+suspension;
+see \fB\%curs_kernel\fP(3X).
+Call
+.B \%delscreen
+after
+.B \%endwin
+when a particular
+.I SCREEN
+structure
+is no longer needed.
 .SH RETURN VALUE
-\fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP
-upon successful completion.
-.PP
-Routines that return pointers always return \fBNULL\fP on error.
+.B \%endwin
+returns
+.B OK
+on success and
+.B ERR
+on failure.
 .PP
-X/Open defines no error conditions.
-In this implementation
+In
+.IR \%ncurses ","
 .bP
-\fBendwin\fP returns
+.B \%endwin
+returns
 .B ERR
 if
 .RS
 .bP
-the terminal was not initialized, or
+the terminal was not initialized,
 .bP
-\fBendwin\fP is called more than once without updating the screen, or
+.B \%endwin
+is called more than once without updating the screen,
+or
 .bP
-\fBreset_shell_mode\fP(3X) return
+\fB\%reset_shell_mode\fP(3X) returns
 .BR ERR "."
 .RE
 .bP
-\fBnewterm\fP
+.B \%newterm
 returns
 .B ERR
-if it cannot allocate the data structures for the screen,
-or for the top-level windows within the screen,
-i.e.,
-\fBcurscr\fP, \fBnewscr\fP, or \fBstdscr\fP.
-.bP
-\fBset_term\fP
-returns no error.
+if it cannot allocate storage for the
+.I SCREEN
+data structure
+or the top-level windows thereof:
+.BR \%curscr ","
+.BR \%newscr ","
+and
+.BR \%stdscr "."
+.PP
+Functions that return pointers return
+.I NULL
+on error.
+In
+.IR \%ncurses ","
+.B \%set_term
+does not fail.
 .SH PORTABILITY
-These functions were described in X/Open Curses, Issue 4.
-As of 2015, the current document is X/Open Curses, Issue 7.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
 .SS Differences
 X/Open Curses specifies that portable applications must not
-call \fBinitscr\fP more than once:
+call \fB\%initscr\fP more than once:
 .bP
-The portable way to use \fBinitscr\fP is once only,
+The portable way to use \fB\%initscr\fP is once only,
 using \fB\%refresh\fP(3X)
-to restore the screen after \fBendwin\fP.
+to restore the screen after \fB\%endwin\fP.
 .bP
-This implementation allows using \fBinitscr\fP after \fBendwin\fP.
+This implementation allows using \fB\%initscr\fP after \fB\%endwin\fP.
 .PP
 Old versions of curses, e.g., BSD 4.4, would return a null pointer
-from \fBinitscr\fP when an error is detected, rather than exiting.
-It is safe but redundant to check the return value of \fBinitscr\fP
+from \fB\%initscr\fP when an error is detected, rather than exiting.
+It is safe but redundant to check the return value of \fB\%initscr\fP
 in X/Open Curses.
 .PP
-Calling \fBendwin\fP does not dispose of the memory allocated in \fBinitscr\fP
-or \fBnewterm\fP.
+Calling \fB\%endwin\fP does not dispose of the memory allocated in
+\fB\%initscr\fP or \fB\%newterm\fP.
 Deleting a \fISCREEN\fP provides a way to do this:
 .bP
-X/Open Curses does not say what happens to \fI\%WINDOW\fPs when \fBdelscreen\fP
+X/Open Curses does not say what happens to \fI\%WINDOW\fPs when
+\fB\%delscreen\fP
 \*(``frees storage associated with the \fISCREEN\fP\*(''
 nor does the SVr4 documentation help,
-adding that it should be called after \fBendwin\fP if a \fISCREEN\fP
+adding that it should be called after \fB\%endwin\fP if a \fISCREEN\fP
 is no longer needed.
 .bP
 However, \fI\%WINDOW\fPs are implicitly associated with a \fISCREEN\fP.
-so that it is reasonable to expect \fBdelscreen\fP to deal with these.
+so that it is reasonable to expect \fB\%delscreen\fP to deal with these.
 .bP
 SVr4 curses deletes the standard \fI\%WINDOW\fP structures
-\fBstdscr\fP and \fBcurscr\fP as well as a work area \fBnewscr\fP.
+\fB\%stdscr\fP and \fB\%curscr\fP as well as a work area \fB\%newscr\fP.
 SVr4 curses ignores other windows.
 .bP
 Since version 4.0 (1996),
 \fI\%ncurses\fP has maintained a list of all windows for each screen,
-using that information to delete those windows when \fBdelscreen\fP is called.
+using that information to delete those windows when \fB\%delscreen\fP is
+called.
 .bP
 NetBSD copied this feature of \fI\%ncurses\fP in 2001.
 PDCurses follows the SVr4 model,
 deleting only the standard \fI\%WINDOW\fP structures.
 .SS "High-level versus Low-level"
 Different implementations may disagree regarding the level of some functions.
-For example, \fISCREEN\fP (returned by \fBnewterm\fP) and
-\fI\%TERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for
-the output stream.
-If an application switches screens using \fBset_term\fR,
-or switches terminals using \fBset_curterm\fP(3X),
+For example, \fISCREEN\fP (returned by \fB\%newterm\fP) and
+\fI\%TERMINAL\fP (returned by \fB\%setupterm\fP(3X)) hold file
+descriptors for the output stream.
+If an application switches screens using \fB\%set_term\fR,
+or switches terminals using \fB\%set_curterm\fP(3X),
 applications which use the output file descriptor can have different
 behavior depending on which structure holds the corresponding descriptor.
-.PP
-For example
 .bP
-NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fI\%TERMINAL\fP.
-\fI\%ncurses\fP and SVr4 use the descriptor in \fISCREEN\fP.
+NetBSD's
+.I \%baudrate
+function uses the descriptor in
+.IR \%TERMINAL "."
+.I \%ncurses
+and SVr4
+.I curses
+use the descriptor in
+.IR SCREEN "."
 .bP
 NetBSD and \fI\%ncurses\fP use the descriptor
 in \fI\%TERMINAL\fP
 for terminal I/O modes,
 e.g.,
-\fBdef_shell_mode\fP(3X),
-\fBdef_prog_mode\fP(3X).
+\fB\%def_shell_mode\fP(3X),
+\fB\%def_prog_mode\fP(3X).
 SVr4 curses uses the descriptor in \fISCREEN\fP.
-.SS "Unset \fITERM\fP Variable"
-If the \fITERM\fP variable is missing or empty, \fBinitscr\fP uses the
+.SS "Unset \f(BITERM\fP Variable"
+If the \fITERM\fP variable is missing or empty, \fB\%initscr\fP uses the
 value \*(``unknown\*('',
-which normally corresponds to a terminal entry with the \fIgeneric\fP
-(\fIgn\fP) capability.
-Generic entries are detected by \fBsetupterm\fP(3X)
+which normally corresponds to a terminal entry with the
+.B \%generic
+.RB ( gn )
+capability.
+Generic entries are detected by \fB\%setupterm\fP(3X)
 and cannot be used for full-screen operation.
 Other implementations may handle
 a missing/empty \fITERM\fP variable differently.
@@ -343,7 +423,7 @@ .SS "Signal Handlers"
 .RE
 .PP
 This implementation establishes signal handlers during initialization,
-e.g., \fBinitscr\fP or \fBnewterm\fP.
+e.g., \fB\%initscr\fP or \fB\%newterm\fP.
 Applications which must handle these signals should set up the corresponding
 handlers \fIafter\fP initializing the library:
 .TP 5
@@ -355,18 +435,18 @@ .SS "Signal Handlers"
 Walking the \fISCREEN\fP list is unsafe, since all list management
 is done without any signal blocking.
 .bP
-On systems which have \fBREENTRANT\fP turned on, \fBset_term\fP uses
+On systems which have \fB\%REENTRANT\fP turned on, \fB\%set_term\fP uses
 functions which could deadlock or misbehave in other ways.
 .bP
-\fBendwin\fP calls other functions,
+\fB\%endwin\fP calls other functions,
 many of which use \fI\%stdio\fP(3) or other library functions which are
 clearly unsafe.
 .RE
 .TP 5
 .B SIGTERM
-This uses the same handler as \fBSIGINT\fP, with the same limitations.
+This uses the same handler as \fB\%SIGINT\fP, with the same limitations.
 It is not mentioned in X/Open Curses, but is more suitable for this
-purpose than \fBSIGQUIT\fP (which is used in debugging).
+purpose than \fB\%SIGQUIT\fP (which is used in debugging).
 .TP 5
 .B SIGTSTP
 This handles the \fIstop\fP signal, used in job control.
@@ -396,8 +476,8 @@ .SS "Signal Handlers"
 .BR \%KEY_RESIZE "."
 .RE
 .IP
-At the same time, \fI\%ncurses\fP calls \fBresizeterm\fP to adjust the
-standard screen \fBstdscr\fP,
+At the same time, \fI\%ncurses\fP calls \fB\%resizeterm\fP to adjust the
+standard screen \fB\%stdscr\fP,
 and update other data such as \fBLINES\fP and \fBCOLS\fP.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
-- 
2.30.2

signature.asc
Description: PGP signature