[PATCH 063/100] man/ncurses.3x: Recast "ENVIRONMENT" section, TERMINFO (19/21).

[G. Branden Robinson]

Content:
* Use *roff logic to compute formatted output of TERMINFO search path
  defaults, if there are any.  I hear the cries of mandoc(1) partisans
  erupting already...

  These are "statically" determined (at build time), so we could
  eliminate the logic from installed man pages if we pursued another
  notion I have.

  https://lists.gnu.org/archive/html/bug-ncurses/2024-03/msg00064.html

Style:
* Tweak shell style in example.  Word-splitting occurs before process
  substitution, so the quotes in

    foo="$(this)"

  are unnecessary.

* Drop a relative inset when setting a series of bulleted paragraphs
  (with the page-local `bP` macro).  The rest of the page does not inset
  them.

Markup:
* Simplify sequence of macro calls to obtain an inset region within an
  indented paragraph.  Dropping a `PP` call preserves the "remembered"
  indentation amount used by un-argumentful `IP`, `TP`, `HP`, and `RS`
  calls.
---
 man/ncurses.3x | 140 +++++++++++++++++++++++++++----------------------
 1 file changed, 78 insertions(+), 62 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index aaa8039d2..f8643985a 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1482,89 +1482,105 @@ .SS "\fITERMCAP\fP"
 .I TERM
 environment variable is stored.
 .SS "\fITERMINFO\fP"
-\fI\%ncurses\fP can be configured to read from multiple terminal
-databases.
-The \fI\%TERMINFO\fP variable overrides the location for
-the default terminal database.
-Terminal descriptions (in terminal format) are stored in terminal databases:
+.I \%ncurses
+can be configured to read terminal type description databases in various
+locations using different formats.
+This variable overrides the default location.
 .bP
-Normally these are stored in a directory tree,
-using subdirectories named by the first letter of the terminal names therein.
-.IP
-This is the scheme used in System V, which legacy Unix systems use,
-and the \fI\%TERMINFO\fP variable is used by \fIcurses\fP applications
-on those
-systems to override the default location of the terminal database.
-.IP \(bu 4
-If \fI\%ncurses\fP is built to use hashed databases,
-then each entry in this list may be the path of a hashed database file, e.g.,
-.RS 4
-.PP
-.RS 4
-.EX
-/usr/share/terminfo.db
-.EE
-.RE
-.PP
+Descriptions in
+.I \%term\%info
+format are normally stored in a directory tree using subdirectories
+named by the common first letters of the terminal types named therein.
+This is the scheme used in System\ V.
+.bP
+If
+.I \%ncurses
+is configured to use hashed databases,
+then
+.I \%TERM\%INFO
+may name its location,
+such as
+.IR \%/usr/share/terminfo.db ,
 rather than
+.IR \%/usr/share/terminfo/ .
 .PP
-.RS 4
-.EX
-/usr/share/terminfo/
-.EE
-.RE
-.PP
-The hashed database uses less disk-space and is a little faster than the
+The hashed database uses less disk space and is a little faster than the
 directory tree.
 However,
 some applications assume the existence of the directory tree,
-reading it directly
-rather than using the terminfo library calls.
-.RE
+and read it directly
+rather than using the
+.I \%term\%info
+API.
 .bP
-If \fI\%ncurses\fP is built with a support for reading termcap files
-directly, then an entry in this list may be the path of a termcap file.
-.IP \(bu 4
-If the \fI\%TERMINFO\fP variable begins with
-\*(``hex:\*('' or \*(``b64:\*('',
-\fI\%ncurses\fP uses the remainder of that variable as a compiled
-terminal description.
-You might produce the base64 format using \fBinfocmp\fP(1M):
-.RS 4
-.PP
+If
+.I \%ncurses
+is configured with
+.I termcap
+support,
+this variable may contain the location of a
+.I \%termcap
+file.
+.bP
+If the value of
+.I \%TERM\%INFO
+begins with \*(``hex:\*('' or \*(``b64:\*('',
+.I \%ncurses
+uses the remainder of the value as a compiled
+.I \%term\%info
+description.
+You might produce the base64 format using \fB\%infocmp\fP(1M).
+.IP
 .RS 4
 .EX
-TERMINFO="$(infocmp \-0 \-Q2 \-q)"
+TERMINFO=$(infocmp \-0 \-Q2 \-q)
 export TERMINFO
 .EE
 .RE
+.IP
+The compiled description is used only if it corresponds to the terminal
+type identified by
+.IR TERM .
 .PP
-The compiled description is used if it corresponds to the terminal identified
-by the \fITERM\fP variable.
-.RE
-.PP
-Setting \fI\%TERMINFO\fP is the simplest,
-but not the only way to set location of the default terminal database.
-The complete list of database locations in order follows:
-.RS 3
+Setting
+.I \%TERM\%INFO
+is the simplest,
+but not the only,
+way to direct
+.I \%ncurses
+to a terminal database.
+The search path is as follows.
 .bP
-the last terminal database to which \fI\%ncurses\fP wrote,
-if any, is searched first
+the last terminal database to which the running
+.I \%ncurses
+application wrote,
+if any
 .bP
-the location specified by the \fI\%TERMINFO\fP environment variable
+the location specified by the
+.I \%TERM\%INFO
+environment variable
 .bP
-$HOME/.terminfo
+.I $HOME/.terminfo
 .bP
-locations listed in the \fI\%TERMINFO_DIRS\fP environment variable
+locations listed in the
+.I \%TERMINFO_DIRS
+environment variable
+.ds td \" empty
+.if !'@TERMINFO_DIRS@'no default value' .as td @TERMINFO_DIRS@
+.if !'@TERMINFO@\*(td'' \{\
 .bP
-one or more locations whose names are configured and compiled into the
-\fI\%ncurses\fP library, i.e.,
+location(s) configured and compiled into
+.I \%ncurses
 .RS 3
+.if !'\*(td'' \{\
 .bP
-@TERMINFO_DIRS@ (corresponding to the \fI\%TERMINFO_DIRS\fP variable)
+.I \%@TERMINFO_DIRS@
+.\}
+.if !'@TERMINFO'' .if !'\*(td'@TERMINFO@' \{\
 .bP
-@TERMINFO@ (corresponding to the \fITERMINFO\fP variable)
-.RE
+.I \%@TERMINFO@
+.\}
+.\}
 .RE
 .SS "\fITERMINFO_DIRS\fP"
 Specifies a list of locations to search for terminal descriptions.
-- 
2.30.2

signature.asc
Description: PGP signature