[PATCH 09/43] man/curs_terminfo.3x: Fix style and markup nits in subsection "The Terminal State".

[G. Branden Robinson]

Content:
* Discuss "capabilities", not "variables", as having the types
  "Boolean", "numeric", and "string".
* Drop passing mention of initscr; it's a high-level API function.
* Generalize example of `restartterm()` usage.

Style:
* Favor "line speed" over "baud rate".  Bits per second and baud rate
  have been distinguishable in data communications for a very long time
  now.  (Even _that_ statement concedes too much to the visibility
  of analog encoding methods from contemporary software.)
* Set name of API symbol "oterm" in bold, not italics.
* Refer to memory as such when discussing resource management, not
  loosely as "space".
* Favor present tense over future.
* Tighten wording.

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_terminfo.3x | 81 +++++++++++++++++++++++++++-----------------
 1 file changed, 50 insertions(+), 31 deletions(-)

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 2c373f6f6..084d2b194 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -330,57 +330,76 @@ .SS Initialization
 .RE
 .\" ********************************************************************
 .SS "The Terminal State"
-\fB\%setupterm\fP stores its information about the terminal in a
+.B \%setupterm
+stores its information about the terminal in a
 .I \%TERMINAL
-structure pointed to by the global variable \fB\%cur_term\fP.
+structure pointed to by the global variable
+.BR \%cur_term "."
 If it detects an error,
 or decides that the terminal is unsuitable
 (hardcopy or generic),
 it discards this information,
-making it not available to applications.
+making it unavailable to applications.
 .PP
-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,
-\fB\%setupterm\fP allocates new storage for each set of terminal
-capabilities.
+If
+.B \%setupterm
+is called repeatedly for the same terminal type,
+it reuses the information.
+It maintains only one copy of a given type's capabilities in memory.
+If called for different types,
+.B \%setupterm
+allocates new storage for each set of terminal capabilities.
 .PP
-\fB\%set_curterm\fP sets \fB\%cur_term\fP to
-.IR \%nterm ,
-and makes all of the
+.B \%set_curterm
+sets
+.B \%cur_term
+to
+.IR \%nterm ","
+making all of the
 .I \%term\%info
 Boolean,
 numeric,
-and string variables use the values from
-.IR \%nterm .
-It returns the old value of \fB\%cur_term\fP.
+and string capabilities use the values from
+.IR \%nterm "."
+It returns the old value of
+.BR \%cur_term "."
 .PP
-\fB\%del_curterm\fP frees the space pointed to by
-.I \%oterm
-and makes it available for further use.
+.B \%del_curterm
+frees the memory pointed to by
+.BR \%oterm ","
+making it available for further use.
 If
-.I \%oterm
+.B \%oterm
 is
-the same as \fB\%cur_term\fP,
+the same as
+.BR \%cur_term ","
 references to any of the
 .I \%term\%info
 Boolean,
 numeric,
-and string variables thereafter may refer to invalid memory locations
-until another \fB\%setupterm\fP has been called.
+and string capabilities thereafter may refer to invalid memory locations
+until
+.B \%setupterm
+is called again.
 .PP
-\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
+.B \%restartterm
+is similar to
+.BR \%setupterm ","
+but is intended for use after restoring program 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.
+when reloading an application that has been suspended from one terminal
+session and restored in another).
+.B \%restartterm
+assumes that the display dimensions
+and the input and output options are the same as when memory was saved,
+but the terminal type and line speed may differ.
 Accordingly,
-\fB\%restartterm\fP saves various terminal state bits,
-calls \fB\%setupterm\fP,
-and then restores the bits.
+.B \%restartterm
+saves relevant terminal state,
+calls
+.BR \%setupterm ","
+then restores that state.
 .\" ********************************************************************
 .SS "Formatting Output"
 \fB\%tparm\fP instantiates the string
-- 
2.30.2

signature.asc
Description: PGP signature