[PATCH 12/23] man/curs_terminfo.3x: Revise "DESCRIPTION" section.

[G. Branden Robinson]

* Make the relationship between curses and terminfo
  setup/teardown functions more clear, so that the application
  programmer has a better idea if/when they must be called.
* Explicitly cross reference term_variables(3X) when discussing
  initialization of terminal capability variables.
* Describe what characterizes a terminal as "hard-copy".  For the kids.
* Drop discussion (outdated since introduction of use_ioctl(3X)) of how
  terminal dimensions are determined in favor of cross reference to
  use_env(3X).  (ncurses(3X) also briefly covers the subject.)
* Clarify cross reference leading reader to capability list.
* Add "Header Files" subsection to "PORTABILITY" section, since modern
  systems don't need to include the "curses.h" header file if they don't
  use the curses API (cf. the terminfo API).

* man/man_db.renames.in: Add reset_prog_mode.3x.
---
 man/curs_terminfo.3x  | 108 ++++++++++++++++--------------------------
 man/man_db.renames.in |   1 +
 2 files changed, 43 insertions(+), 66 deletions(-)

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 966c28622..8fa83eeb2 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -134,64 +134,29 @@ .SH DESCRIPTION
 Capability string values have no associated encoding;
 they are strings of 8-bit characters.
 .SS Initialization
-Initially,
-\fB\%setupterm\fP should be called.
-The high-level
-.I curses
-functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to
-initialize the low-level set of terminal-dependent variables listed in
+Call
+.B \%setupterm
+from your application to have
+.I \%term\%info
+manage the terminal device;
+this action initializes the terminal-dependent variables listed in
 \fB\%term_variables\fP(3X).
-.PP
-Applications can use the terminal capabilities either directly
-(via header definitions),
-or by special functions.
-The header files
-.I \%curses.h
-and
-.I \%term.h
-should be included
-(in that order)
-to get the definitions for these strings,
-numbers,
-and flags.
-.PP
-The
+(A
+.I curses
+application calling \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) achieves
+the same result.)
+Applications can use the terminal capabilities either directly,
+by object definitions corresponding to capability names and codes
+(see \fB\%term_variables\fP(3X))
+or by calling the functions documented here.
+.B \%setupterm
+initializes the
 .I \%term\%info
 variables
 .B \%lines
 and
 .B \%columns
-are initialized by \fB\%setupterm\fP as follows.
-.bP
-If \fB\%use_env(FALSE)\fP has been called,
-values for
-.B \%lines
-and
-.B \%columns
-specified in
-.I \%term\%info
-are used.
-.bP
-Otherwise,
-if the environment variables
-.I LINES
-and
-.I \%COLUMNS
-exist,
-their values are used.
-If these environment variables do not exist and the program is running
-in a window,
-the current window size
-is used.
-Otherwise,
-if the environment variables do not exist,
-the values for
-.B \%lines
-and
-.B \%columns
-specified in the
-.I \%term\%info
-database are used.
+as described in \fB\%use_env\fP(3X).
 .PP
 Parameterized strings should be passed through \fB\%tparm\fP to
 instantiate them.
@@ -201,12 +166,19 @@ .SS Initialization
 (including the output of \fB\%tparm\fP)
 should be sent to the terminal device with \fB\%tputs\fP or
 \fB\%putp\fP.
-Call \fB\%reset_shell_mode\fP to restore the terminal modes before
-exiting;
-see \fB\%curs_kernel\fP(3X).
+Call
+\fB\%reset_shell_mode\fP(3X) to restore the terminal modes before
+exiting.
+(A
+.I curses
+application calling \fB\%endwin\fP(3X) achieves the same result.)
+.\" XXX: What should a "pure" terminfo application that wants to link
+.\" only with libtinfo, and not libcurses, do?
 .PP
-Programs that use
-cursor addressing should
+Programs that use cursor addressing should emit certain capabilities
+at specific times.
+Specifically,
+output
 .bP
 output \fB\%enter_ca_mode\fP upon startup and
 .bP
@@ -214,12 +186,16 @@ .SS Initialization
 .PP
 Programs that execute shell subprocesses should
 .bP
-call \fB\%reset_shell_mode\fP and
-output \fB\%exit_ca_mode\fP before the shell
-is called and
+call \fB\%reset_shell_mode\fP(3X) and output
+.B \%exit_ca_mode
+before the shell is called,
+and
 .bP
-output \fB\%enter_ca_mode\fP and
-call \fB\%reset_prog_mode\fP after returning from the shell.
+output
+.B \%enter_ca_mode
+and call \fB\%reset_prog_mode\fP(3X) after returning from the shell.
+.\" XXX: What should a "pure" terminfo application that wants to link
+.\" only with libtinfo, and not libcurses, do?
 .PP
 \fB\%setupterm\fP reads in the
 .I \%term\%info
@@ -284,7 +260,8 @@ .SS Initialization
 .RS
 .TP 5
 .B 1
-means that the terminal is hardcopy,
+means that the terminal is a hard-copy type
+(lacks destructive backspace),
 and cannot be used for
 .I curses
 applications.
@@ -580,9 +557,8 @@ .SS "Terminal Capability Functions"
 passed to them.
 The
 .I cap-code
-for each capability is given in the table column entitled
-.I cap-code
-code in the capabilities section of \fB\%terminfo\fP(5).
+for each capability is given in the table column of that name
+in the \*(``Predefined Capabilities\*('' section of \fB\%terminfo\fP(5).
 .PP
 These functions return special values to denote errors.
 .PP
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 79fbba2a1..a6206f4b9 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -242,6 +242,7 @@ putp.3x                     putp.3ncurses
 putwin.3x                      putwin.3ncurses
 raw.3x                         raw.3ncurses
 refresh.3x                     refresh.3ncurses
+reset_prog_mode.3x             reset_prog_mode.3ncurses
 reset_shell_mode.3x            reset_shell_mode.3ncurses
 restartterm.3x                 restartterm.3ncurses
 ripoffline.3x                  ripoffline.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature