[PATCH 12/40] man/tput.1: Revise (1/10) (NAME, SYNOPSIS, DESCRIPTION introduction).

[G. Branden Robinson]

Content:
* Add "init" as page topic name (like "reset"), since tput specially
  supports being called by that name.
* Expand summary description to highlight the use of the command to
  exercise, not merely query, terminal capabilities.
* Drop material coaching the reader in elementary shell usage.

Style:
* Recast introductory paragraphs of description.  Introduce necessary
  concepts sooner.

Markup:
* Protect operand literals from hyphenation in synopsis.
* Protect "@TPUT@" from hyphenation, since we don't know how it will
  expand.
---
 man/tput.1 | 41 +++++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/man/tput.1 b/man/tput.1
index c133eb51b..ec203f288 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -48,8 +48,11 @@
 .ds d @TERMINFO@
 .SH NAME
 \fB\%@TPUT@\fP,
+\fB\%init\fP,
 \fB\%reset\fP \-
-initialize a terminal or query \fI\%term\%info\fP database
+initialize a terminal,
+exercise its capabilities,
+or query \fI\%term\%info\fP database
 .SH SYNOPSIS
 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP]
 {\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
@@ -58,26 +61,33 @@ .SH SYNOPSIS
 .PP
 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
 .PP
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBreset\fP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
 .PP
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBlongname\fP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
 .PP
 \fB@TPUT@ \-S\fP
 .PP
 \fB@TPUT@ \-V\fP
 .SH DESCRIPTION
-\fB@TPUT@\fP uses the \fI\%term\%info\fP library and database to make
-the values of terminal-specific capabilities and information available
-to the shell,
+\fB\%@TPUT@\fP uses the
+.I \%term\%info
+library and database to make terminal-specific capabilities and
+information available to the shell,
 to initialize or reset the terminal,
-or report the long name of the current
+or
+to report a description of the current
 (or specified)
 terminal type.
+Terminal capabilities are accessed by
+.I cap-code.
+\fB\%terminfo\fP(5) discusses capabilities at length and presents a
+complete list of
+.I cap-codes.
 When retrieving capability values,
 the result depends upon the capability's type.
 .TP 9 \" "Boolean" + 2n
 Boolean
-\fB@TPUT@\fP sets its exit status to
+\fB\%@TPUT@\fP sets its exit status to
 .B 0
 if the terminal possesses
 .I cap-code,
@@ -85,8 +95,8 @@ .SH DESCRIPTION
 .B 1
 if it does not.
 .TP
-integer
-\fB@TPUT@\fP writes
+numeric
+\fB\%@TPUT@\fP writes
 .IR cap-code 's
 decimal value to the standard output stream if defined
 .RB ( \-1
@@ -94,20 +104,15 @@ .SH DESCRIPTION
 followed by a newline.
 .TP
 string
-\fB@TPUT@\fP writes
+\fB\%@TPUT@\fP writes
 .IR cap-code 's
 value to the standard output stream if defined,
 without a trailing newline.
 .PP
 Before using a value returned on the standard output,
-the application should test \fB@TPUT@\fP's exit status
-(for example,
-using \fB$?\fP in \fIsh\fP(1))
-to be sure it is \fB0\fP;
+the application should test \fB\%@TPUT@\fP's exit status
+to be sure it is 0;
 see section \*(``EXIT STATUS\*('' below.
-For a complete list of
-.I cap-codes,
-see \fB\%terminfo\fP(5).
 .SS Commands
 A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are
 special; they are defined by the \fB@TPUT@\fP program.
-- 
2.30.2

signature.asc
Description: PGP signature