[PATCH 07/19] man/curs_initscr.3x: Revise "DESCRIPTION" section.

[G. Branden Robinson]

Content:
* Add `use_tiocl` to list of functions one might call before `initscr`.
* Rearrange and expand discussion of when the programmer would use
  `newterm` before, or instead of, `initscr`.
* Illuminate relationship between `initscr`, `newterm`, and `setupterm`.

Style:
* Make `filter`, `ripoffline` and `use_env` into man page cross
  references.
* Set libc symbol `NULL` in italics, not bold, just as we would a
  function name.

Markup:
* 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 | 136 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 104 insertions(+), 32 deletions(-)

diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x
index 73f9c69a6..673d105d9 100644
--- a/man/curs_initscr.3x
+++ b/man/curs_initscr.3x
@@ -67,45 +67,117 @@ .SH SYNOPSIS
 .fi
 .SH DESCRIPTION
 .SS initscr
-\fBinitscr\fP is normally the first \fBcurses\fP routine to call when
-initializing a program.
-A few special routines sometimes need to be called before it;
-these are \fBslk_init\fP(3X), \fBfilter\fP, \fBripoffline\fP,
-\fBuse_env\fP.
-For multiple-terminal applications,
-\fBnewterm\fP may be called before \fBinitscr\fP.
+.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
+.I curses
+function call a program performs.
+However,
+an application with unusual needs might employ a few other
+.I curses
+functions beforehand:
+.bP
+\fB\%slk_init\fP(3X) to set up soft-label keys;
+.bP
+\fB\%filter\fP(3X) if the program is designed to operate in a process
+pipeline;
+.bP
+\fB\%ripoffline\fP(3X) to reserve up to five lines at the top and/or
+bottom of the screen from management by
+.BR \%stdscr ","
+the standard
+.I curses
+window;
+and
+.bP
+\fB\%use_env\fP(3X) and/or \fB\%use_tioctl\fP(3X) to configure use of
+the process environment and operating system's terminal driver,
+respectively,
+when determining the dimensions of the terminal display.
 .PP
-The initscr code determines the terminal type and initializes all \fBcurses\fP
-data structures.
-\fBinitscr\fP also causes the first call to \fB\%refresh\fP(3X)
-to clear the screen.
-If errors occur, \fBinitscr\fP writes an appropriate error
-message to standard error and exits;
-otherwise, a pointer is returned to \fBstdscr\fP.
-.SS newterm
-A program that outputs to more than one terminal should use the \fBnewterm\fP
-routine for each terminal instead of \fBinitscr\fP.
-A program that needs to inspect capabilities,
-so it can continue to run in a line-oriented mode if the
-terminal cannot support a screen-oriented program, would also use
-\fBnewterm\fP.
+Further,
+a
+.I curses
+program might call
+.B \%newterm
+prior to or instead of
+.B \%initscr
+in two specialized cases described in its subsection below.
 .PP
-The routine \fBnewterm\fP should be called once for each terminal.
-It returns a variable of type \fISCREEN *\fP which should be saved
-as a reference to that terminal.
-\fBnewterm\fP's arguments are
+.B \%initscr
+causes the first \fB\%refresh\fP(3X) call to clear the screen.
+If errors occur,
+.B \%initscr
+writes an appropriate diagnostic message to the standard error stream
+and exits;
+otherwise,
+it returns a pointer to
+.BR stdscr "."
+.SS newterm
+An application that manages multiple terminals should call
+.B \%newterm
+once for each such device
+.I instead
+of
+.BR \%initscr "."
+.BR \%newterm 's
+arguments are
 .bP
-the \fItype\fP of the terminal to be used in place of \fB$TERM\fP,
+the
+.I type
+of the associated terminal,
+or
+.I NULL
+to use the
+.I TERM
+environment variable;
 .bP
-an output stream connected to the terminal, and
+an output stream
+.I outf
+connected to the terminal;
+and
 .bP
-an input stream connected to the terminal
+an input stream
+.I inf
+connected to the terminal.
+It returns a variable of structure type
+.I SCREEN
+.BR * ","
+which should be saved as a reference to that terminal.
 .PP
-If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used.
+.B \%newterm
+passes the file descriptor of the output stream to the
+.I \%term\%info
+function \fB\%setupterm\fP(3X),
+which returns a pointer to a
+.I \%TERMINAL
+structure that
+.B \%newterm
+stores in the
+.I SCREEN
+it returns to the application.
 .PP
-The file descriptor of the output stream is passed to \fBsetupterm\fP(3X),
-which returns a pointer to a \fI\%TERMINAL\fP structure.
-\fBnewterm\fP's return value holds a pointer to the \fI\%TERMINAL\fP structure.
+An application that needs to inspect a terminal type's capabilities,
+so that it can continue to run in a line-oriented mode
+if the terminal cannot support a screen-oriented program,
+would also use
+.BR \%newterm "."
+If at most one terminal connection is needed,
+the programmer could perform such a capability test,
+decide which mode in which to operate,
+then call
+.B \%delscreen
+on the pointer returned by
+.BR \%newterm ","
+and proceed with either
+.B \%initscr
+or a
+.RI non- curses
+interface.
 .SS endwin
 The program must also call
 \fBendwin\fP for each terminal being used before exiting from \fBcurses\fP.
-- 
2.30.2

signature.asc
Description: PGP signature