[PATCH 16/42] man/ncurses.3x: Revise "Environment variables" subsection.

[G. Branden Robinson]

* Rename it to "Effects of GUIs and Environment Variables", using
  titlecase.
* Introduce and motivate the importance of $TERM.  Add cross reference
  to tset(1) for people having problems setting a good $TERM value.
* Discuss GUIs in favor of a geriatric mention of AT&T 630 devices.
  (C'mon--the top Google hit for this device is its sales brochure,
  dated 1987, on Bitsavers.)
* Add cross reference to wresize(3X), an important ncurses extension.
* Drop topically irrelevant content about global variables LINES, COLS,
  and `curscr`, and constants `TRUE`, and `FALSE`.  This discussion is
  also redundant with curs_variables(3X).

Style:
* Set file and environment variable names in italics.
* Drop vertical spacing around within-paragraph quasi-displays, to
  cohere the $TERMINFO discussion.
* Recast.

Markup:
* Use man(7) font style macros more and *roff font escape sequences
  less, except for man page cross references.
* Quote multi-word macro arguments, modeling good *roff practice.
* Break input lines after commas.
* Annotate configuration-dependent claim that needs to be revisited.
  (It's not trivial to fix this because the text would need to change
  based on a configuration-time variable.  It's on my to-do list.)
---
 man/ncurses.3x | 82 +++++++++++++++++++++++++-------------------------
 1 file changed, 41 insertions(+), 41 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 5e0c60eca..24207fefd 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -286,62 +286,62 @@ .SS Overview
 translates these into unique
 .I "key codes."
 See \fB\%getch\fP(3X).
-.SS Environment variables
+.SS "Effects of GUIs and Environment Variables"
+The selection of an approprate value of
+.I TERM
+in the process environment is essential to correct
+.I curses
+and
+.I \%term\%info
+library operation.
+A well-configured system selects a correct
+.I TERM
+value automatically;
+\fB\%tset\fP(1) may assist with troubleshooting exotic situations.
+.PP
 If the environment variables \fILINES\fP and \fI\%COLUMNS\fP are set,
 or if the
-program is executing in a window environment, line and column information in
-the environment will override information read by \fIterminfo\fP.
-This would affect a program running in an AT&T 630 layer,
-for example, where the size of a
-screen is changeable (see \fBENVIRONMENT\fP).
+.I curses
+program is executing in a graphical windowing environment,
+the information obtained thence overrides that obtained by
+.IR \%term\%info .
+An
+.I \%ncurses
+extension supports resizable terminals;
+see \fB\%wresize\fP(3X).
 .PP
 If the environment variable \fI\%TERMINFO\fP is defined,
-any program using
-\fBcurses\fP checks for a local terminal definition before checking in the
-standard place.
-For example, if \fITERM\fP is set to \fBatt4424\fP, then the
-compiled terminal definition is found in
-.PP
+a
+.I curses
+program checks first for a terminal type description in the location it
+identifies.
+For example,
+if \fITERM\fP is set to \fBatt4424\fP,
+that terminal type's compiled description is normally found in
 .RS 4
-.EX
-\fB\*d/a/att4424\fP.
-.EE
+.IR \*d/a/att4424 .
 .RE
-.PP
 (The \fBa\fP is copied from the first letter of \fBatt4424\fP to avoid
 creation of huge directories.)
+.\" XXX: That's accurate only for builds not using `--with-hashed-db`.
 However,
 if \fI\%TERMINFO\fP is set to
-\fB$HOME/myterms\fP, \fBcurses\fP first checks
-.PP
+.BR \%$HOME/myterms ,
+.I curses
+first checks
 .RS 4
-.EX
-\fB$HOME/myterms/a/att4424\fP,
-.EE
+.IR $HOME/myterms/a/att4424 ,
 .RE
-.PP
-and if that fails, it then checks
-.PP
+and if that fails,
+it then checks
 .RS 4
-.EX
-\fB\*d/a/att4424\fP.
-.EE
+.IR \*d/a/att4424 .
 .RE
+.I \%TERMINFO
+is useful for developing experimental type descriptions or when write
+permission to \fI\*d\fP is not available.
 .PP
-This is useful for developing experimental definitions or when write
-permission in \fB\*d\fP is not available.
-.PP
-The integer variables \fBLINES\fP and \fBCOLS\fP are defined in
-\fB<curses.h>\fP and will be filled in by \fBinitscr\fP with the size of the
-screen.
-The constants \fBTRUE\fP and \fBFALSE\fP have the values \fB1\fP and
-\fB0\fP, respectively.
-.PP
-The \fBcurses\fP routines also define the \fBWINDOW *\fP variable \fBcurscr\fP
-which is used for certain low-level operations like clearing and redrawing a
-screen containing garbage.
-The \fBcurscr\fP can be used in only a few routines.
-.\"
+See section \*(``ENVIRONMENT\*('' below.
 .SS Routine and Argument Names
 Many \fBcurses\fP routines have two or more versions.
 The routines prefixed with \fIw\fP require a window argument.
-- 
2.30.2

signature.asc
Description: PGP signature