[PATCH 047/100] man/ncurses.3x: Revise "ENVIRONMENT" section, COLUMNS (3/21).

[G. Branden Robinson]

Content:
* Mention terminfo capabilities by name _and_ code.

Style:
* Don't use pronouns without clear antecedents.

* man/man_db.renames.in: Add `use_tioctl()`.
---
 man/man_db.renames.in |  1 +
 man/ncurses.3x        | 76 ++++++++++++++++++++++++++++---------------
 2 files changed, 51 insertions(+), 26 deletions(-)

diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 70733fbaa..95ae66695 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -258,6 +258,7 @@ use_default_colors.3x               
use_default_colors.3ncurses
 use_env.3x                     use_env.3ncurses
 use_extended_names.3x          use_extended_names.3ncurses
 use_legacy_coding.3x           use_legacy_coding.3ncurses
+use_tioctl.3x                  use_tioctl.3ncurses
 vidputs.3x                     vidputs.3ncurses
 wadd_wch.3x                    wadd_wch.3ncurses
 waddch.3x                      waddch.3ncurses
diff --git a/man/ncurses.3x b/man/ncurses.3x
index a5d94d59f..9b84571e3 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1071,35 +1071,59 @@ .SS "\fICC\fP (command character)"
 .I \%ncurses
 ignores its value if it is not one character in length.
 .SS "\fICOLUMNS\fP"
-Specify the width of the screen in characters.
+This variable specifies the width of the screen in characters.
 Applications running in a windowing environment usually are able to
 obtain the width of the window in which they are executing.
-If neither the \fI\%COLUMNS\fP value
-nor the terminal's screen size is available,
-\fI\%ncurses\fP uses the size which may be specified in the terminfo
-database
-(i.e., the \fBcols\fP capability).
+If
+.I \%COLUMNS
+is not defined and the terminal's screen size is not available from the
+terminal driver,
+.I \%ncurses
+uses the size specified by the
+.B \%columns
+.RB ( \%cols )
+capability of the terminal type's entry in the
+.I \%term\%info
+database,
+if any.
+.PP
+It is important that your application use the correct screen size.
+Automatic detection thereof is not always possible because an
+application may be running on a host that does not honor NAWS
+(Negotiations About Window Size)
+or as a different user ID than the owner of the terminal device file.
+Setting
+.I \%COLUMNS
+and/or
+.I \%LINES
+overrides the library's use of the screen size obtained from the
+operating system.
 .PP
-It is important that your application use a correct size for the screen.
-This is not always possible because your application may be
-running on a host which does not honor NAWS (Negotiations About Window
-Size), or because you are temporarily running as another user.
-However,
-setting \fI\%COLUMNS\fP and/or \fILINES\fP overrides the library's use
-of the screen size obtained from the operating system.
-.PP
-Either \fI\%COLUMNS\fP or \fILINES\fP symbols may be specified
-independently.
-This is mainly useful to circumvent legacy misfeatures of terminal 
descriptions,
-e.g., xterm which commonly specifies a 65 line screen.
-For best results, \fBlines\fP and \fBcols\fP should not be specified in
-a terminal description for terminals which are run as emulations.
-.PP
-Use the \fBuse_env\fP function to disable all use of external environment
-(but not including system calls) to determine the screen size.
-Use the \fBuse_tioctl\fP function to update \fI\%COLUMNS\fP or
-\fILINES\fP to match the screen size obtained from system calls or the
-terminal database.
+The
+.I \%COLUMNS
+and
+.I \%LINES
+variables may be specified independently.
+This property is useful to circumvent misfeatures of legacy terminal
+type descriptions;
+\fI\%xterm\fP(1) descriptions specifying 65 lines were once notorious.
+For best results,
+avoid specifying
+.B cols
+and
+.B lines
+capability codes in
+.I \%term\%info
+descriptions of terminal emulators.
+.PP
+\fBuse_env\fP(3X) can disable use of the process environment
+in determining the screen size.
+\fBuse_tioctl\fP(3X) can update
+.I \%COLUMNS
+and
+.I \%LINES
+to match the screen size obtained from system calls or the terminal
+database.
 .SS "\fIESCDELAY\fP"
 Specifies the total time,
 in milliseconds,
-- 
2.30.2

signature.asc
Description: PGP signature