[PATCH 13/40] man/tput.1: Revise (2/10) (Commands -> Operands).

[G. Branden Robinson]

Content:
* Rename "Commands" subsection to "Operands", since it describes
  non-option arguments to the tput command, and not all operands are
  "commands"--some are parameters to capabilities.
* Use consistent terminology to refer to capability types: "Boolean",
  "numeric", and "string".
* More carefully distinguish streams from file descriptors.
* Refer reader to terminfo(5) for details of reset capabilities.
* Introduce term "pseudo-capabilities" to characterize operands that
  look like cap-codes but aren't.

Style:
* Adjust paragraph tag width.
* Favor present tense over future.
* Favor English phrases over Latin abbreviations.

Markup:
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references.
* Protect "@TPUT@" and operand literals from hyphenation.
* Break input lines after commas and around multiword parentheticals.
---
 man/tput.1 | 164 ++++++++++++++++++++++++++++-------------------------
 1 file changed, 86 insertions(+), 78 deletions(-)

diff --git a/man/tput.1 b/man/tput.1
index ec203f288..925e1c60c 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -113,139 +113,147 @@ .SH DESCRIPTION
 the application should test \fB\%@TPUT@\fP's exit status
 to be sure it is 0;
 see section \*(``EXIT STATUS\*('' below.
-.SS Commands
-A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are
-special; they are defined by the \fB@TPUT@\fP program.
-The others are the names of \fIcapabilities\fP from the terminal database
-(see \fB\%terminfo\fP(5) for a list).
-Although \fBinit\fP and \fBreset\fP resemble capability names,
-\fB@TPUT@\fP uses several capabilities to perform these special functions.
-.TP
-\fIcap-code\fP
-indicates the capability from the terminal database.
+.SS Operands
+Generally,
+an operand is a
+.I cap-code,
+a capability code from the terminal database,
+or a parameter thereto.
+Three others are specially recognized by \fB\%@TPUT@\fP:
+.BR init ,
+.BR \%reset ,
+and
+.BR \%longname .
+Although these resemble capability codes,
+they in fact receive special handling;
+we term them \*(``pseudo-capabilities\*(''.
+.TP 11n \" "longname" + 2n + adjustment for PDF
+.I cap-code
+indicates a capability from the terminal database.
 .IP
-If the capability is a string that takes parameters, the arguments
-following the capability will be used as parameters for the string.
+If the capability is of string type and takes parameters,
+the arguments following the capability will be used as its parameters.
 .IP
-Most parameters are numbers.
+Most parameters are numeric.
 Only a few terminal capabilities require string parameters;
-\fB@TPUT@\fP uses a table to decide which to pass as strings.
-Normally \fB@TPUT@\fP uses \fBtparm\fP(3X) to perform the substitution.
+\fB\%@TPUT@\fP uses a table to decide which to pass as strings.
+Normally \fB\%@TPUT@\fP uses \fB\%tparm\fP(3X) to perform the
+substitution.
 If no parameters are given for the capability,
-\fB@TPUT@\fP writes the string without performing the substitution.
+\fB\%@TPUT@\fP writes the string without performing the substitution.
 .TP
-\fBinit\fP
-If the terminal database is present and an entry for the user's
-terminal exists (see \fB\-T\fItype\fR, above), the following will
-occur:
+.B init
+initializes the terminal.
+If the terminal database is present
+and an entry for the user's terminal type exists,
+the following occur.
 .RS
 .TP 5
 (1)
-first, \fB@TPUT@\fP retrieves the current terminal mode settings
-for your terminal.
-It does this by successively testing
+\fB\%@TPUT@\fP retrieves the terminal's mode settings.
+It successively tests the file descriptors corresponding to
 .RS
 .bP
-the standard error,
+the standard error stream,
 .bP
-standard output,
+the standard output stream,
 .bP
-standard input and
+the standard input stream,
+and
 .bP
-ultimately \*(``/dev/tty\*(''
+.I \%/dev/tty
 .RE
 .IP
 to obtain terminal settings.
-Having retrieved these settings, \fB@TPUT@\fP remembers which
-file descriptor to use when updating settings.
+Having retrieved them,
+\fB\%@TPUT@\fP remembers which descriptor to use for further updates.
 .TP
 (2)
-if the window size cannot be obtained from the operating system,
-but the terminal description
-(or environment,
-e.g.,
-\fILINES\fP and \fI\%COLUMNS\fP variables specify this),
-update the operating system's notion of the window size.
+If the terminal dimensions cannot be obtained from the operating system,
+but the environment or terminal type database entry describes them,
+\fB\%@TPUT@\fP updates the operating system's notion of them.
 .TP
 (3)
-the terminal modes will be updated:
+\fB\%@TPUT@\fP updates the terminal modes.
 .RS
 .bP
-any delays (e.g., newline) specified in the entry will
-be set in the tty driver,
+Any delays specified in the entry
+(for example,
+when a newline is sent)
+are set in the terminal driver.
 .bP
-tabs expansion will be turned on or off according to
-the specification in the entry, and
+Tab expansion is turned on or off per the specification in the entry,
+and
 .bP
 if tabs are not expanded,
-standard tabs will be set (every 8 spaces).
+standard tabs
+(every 8 spaces)
+are set.
 .RE
 .TP
 (4)
-if present, the terminal's initialization strings will be
-output as detailed in the \fB\%terminfo\fP(5) section on
-.IR "Tabs and Initialization" ,
+If initialization capabilities,
+detailed in subsection \*(``Tabs and Initialization\*('' of
+\fB\%terminfo\fP(5),
+are present,
+\fB\%@TPUT@\fP writes them to the standard output stream.
 .TP
 (5)
-output is flushed.
+\fB\%@TPUT@\fP flushes the standard output stream.
 .RE
 .IP
-If an entry does not
-contain the information needed for any of these activities,
-that activity will silently be skipped.
+If an entry lacks the information needed for an activity above,
+that activity is silently skipped.
 .TP
-\fBreset\fP
-This is similar to \fBinit\fP, with two differences:
+.B reset
+re-initializes the terminal.
+A reset differs from initialization in two ways.
 .RS
 .TP 5
 (1)
-before any other initialization,
-the terminal modes will be reset to a \*(``sane\*('' state:
+\fB\%@TPUT@\fP sets the the terminal modes to a \*(``sane\*('' state,
 .RS
 .bP
-set cooked and echo modes,
+enabling cooked and echo modes,
 .bP
-turn off cbreak and raw modes,
+disabling cbreak and raw modes,
 .bP
-turn on newline translation and
+enabling newline translation,
+and
 .bP
-reset any unset special characters to their default values
+setting any unset special characters to their default values.
 .RE
 .TP 5
 (2)
-Instead of putting out \fIinitialization\fP strings, the terminal's
-\fIreset\fP strings will be output if present
-(\fBrs1\fP, \fBrs2\fP, \fBrs3\fP, \fBrf\fP).
-If the \fIreset\fP strings are not present, but \fIinitialization\fP
-strings are, the \fIinitialization\fP strings will be output.
+If any reset capabilities are defined for the terminal type,
+\fB\%@TPUT@\fP writes them to the output stream.
+Otherwise,
+\fB\%@TPUT@\fP uses any defined initialization capabilities.
+Reset capabilities are detailed in subsection
+\*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
 .RE
-.IP
-Otherwise, \fBreset\fP acts identically to \fBinit\fP.
 .TP
 .B longname
-A terminfo entry begins with one or more names by which an
-application can refer to the entry,
+A
+.I \%term\%info
+entry begins with one or more names by which an application
+can refer to the entry,
 before the list of terminal capabilities.
 The names are separated by \*(``|\*('' characters.
-X/Open states that the last name is the \*(``long name\*(''
-and also that it may include blanks.
+X/Open Curses terms the last name the \*(``long name\*('',
+and indicates that it may include blanks.
 .IP
 \fB\%@TIC@\fP warns if the last name does not include blanks,
-to accommodate old terminfo entries which treated
-the long name as an optional feature.
+to accommodate old
+.I \%term\%info
+entries that treated the long name as an optional feature.
 The long name is often referred to as the description field.
 .IP
 If the terminal database is present and an entry for the user's terminal
-exists
-(see
-.B \-T
-.I type
-above),
-\fB\%@TPUT@\fP reports the terminal's description
-(or \*(``long name\*('')
-to the standard output,
+type exists,
+\fB\%@TPUT@\fP reports its description to the standard output stream,
 without a trailing newline.
-See \fB\%term\%info\fP(5).
+See \fB\%terminfo\fP(5).
 .SS Aliases
 \fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
 commands specially:
-- 
2.30.2

signature.asc
Description: PGP signature