[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 22/52] man/tput.1: Revise.
From: |
G. Branden Robinson |
Subject: |
[PATCH 22/52] man/tput.1: Revise. |
Date: |
Fri, 22 Dec 2023 17:04:38 -0600 |
Content:
* Change "capname" metasyntactic variable to "cap-code". Arguably, the
best "name" for capabilities we have are their long names, used for C
variables in the library. Termcap and terminfo "codes" abbreviate
these.
* Sort capability types in the order used everywhere else: Boolean,
integer, string.
* Capitalize "Boolean" (capability); it is a proper adjective named for
a person, as with "Newtonian physics" or "Darwinian selection".
* Say "exit status" instead of "exit code" (following the man page
section title).
* Precede here-document tput example with explanatory paragraph and give
"tput -S" its own tagged paragraph so that it is not confused with the
preceding discussion of "tput longname".
* Stop using relative inset for this example; instead, use `IP` with the
now-existing tagged paragraph.
* Include primary (PS1) shell prompt in example along with existing
secondary one (PS2). Set these prompts in roman, not bold, because
they do not consitute user input.
* Stop explaining how a here document works. There are plenty of other
resources for that.
Style:
* Recast.
* Drop relative inset for list of capability types.
* Tweak tag lengths in list of capability types to avoid ugly breaks.
* Quote section title references instead of setting them in bold.
Markup:
* Specify explicit hyphenation for "terminfo" when not appearing in a
man page cross reference (where hyphenation is suppressed).
* Revise synopsis. Temporarily use no-fill mode (`nf` and `fi`
requests) instead of a bunch of noisy break (`br`) requests. Use
`\fP` font selection escape sequences instead of explicitly returning
to roman. Use ellipsis instead of pluralizing metasyntacic operand.
Use paragraph spacing between different operation modes.
---
man/tput.1 | 228 +++++++++++++++++++++++++++++------------------------
1 file changed, 123 insertions(+), 105 deletions(-)
diff --git a/man/tput.1 b/man/tput.1
index b353c10f6..82af0fa10 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -49,63 +49,75 @@
.SH NAME
\fB\%@TPUT@\fP,
\fB\%reset\fP \-
-initialize a terminal or query \fIterminfo\fR database
+initialize a terminal or query \fI\%term\%info\fP database
.SH SYNOPSIS
-\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fIcapname\fR [\fIparameters\fR]
-.br
-\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] [\fB\-x\fR] \fBclear\fR
-.br
-\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBinit\fR
-.br
-\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBreset\fR
-.br
-\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBlongname\fR
-.br
-\fB@TPUT@ \-S\fP \fB<<\fP
-.br
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fIcap-code\fP [\fIparameter\fP
.\|.\|.]
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBreset\fP
+.PP
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBlongname\fP
+.PP
+\fB@TPUT@ \-S\fP
+.PP
\fB@TPUT@ \-V\fP
.SH DESCRIPTION
-The \fB@TPUT@\fP utility uses the \fBterminfo\fP database to make the
-values of terminal-dependent capabilities and information available to
-the shell,
+\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,
to initialize or reset the terminal,
-or return the long name of the requested terminal type.
-The result depends upon the capability's type:
-.RS 3
-.TP 5
-string
-\fB@TPUT@\fP writes the string to the standard output.
-No trailing newline is supplied.
+or report the long name of the current
+(or specified)
+terminal type.
+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
+.B 0
+if the terminal possesses
+.I cap-code,
+and
+.B 1
+if it does not.
.TP
integer
-\fB@TPUT@\fP writes the decimal value to the standard output,
-with a trailing newline.
+\fB@TPUT@\fP writes
+.IR cap-code 's
+decimal value to the standard output stream if defined
+.RB ( \-1
+if it is not)
+followed by a newline.
.TP
-boolean
-\fB@TPUT@\fP simply sets the exit code
-(\fB0\fP for TRUE if the terminal has the capability,
-\fB1\fP for FALSE if it does not),
-and writes nothing to the standard output.
-.RE
+string
+\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.
-(See the \fBEXIT STATUS\fP and \fBDIAGNOSTICS\fP sections.)
-For a complete list of capabilities
-and the \fIcapname\fP associated with each, see \fBterminfo\fP(5).
+to be sure it is \fB0\fP;
+see sections \*(``EXIT STATUS\*('' and \*(``DIAGNOSTICS\*('' below.
+For a complete list of
+.I cap-codes,
+see \fB\%terminfo\fP(5).
.SS Options
.TP
\fB\-S\fP
-allows more than one capability per invocation of \fB@TPUT@\fP. The
-capabilities must be passed to \fB@TPUT@\fP from the standard input
-instead of from the command line (see example).
-Only one \fIcapname\fP is allowed per line.
+allows more than one capability per invocation of \fB@TPUT@\fP.
+The capabilities must be passed to \fB@TPUT@\fP from the standard input
+instead of from the command line
+(see example).
+Only one \fIcap-code\fP is allowed per line.
The \fB\-S\fP option changes the
-meaning of the \fB0\fP and \fB1\fP boolean and string exit codes (see the
-EXIT STATUS section).
+meaning of the \fB0\fP and \fB1\fP Boolean and string exit statuses
+(see section \*(``EXIT STATUS\*('' below).
.IP
Because some capabilities may use
\fIstring\fP parameters rather than \fInumbers\fP,
@@ -131,11 +143,11 @@ .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 \fBterminfo\fP(5) for a list).
+(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
-\fIcapname\fP
+\fIcap-code\fP
indicates the capability from the terminal database.
.IP
If the capability is a string that takes parameters, the arguments
@@ -197,7 +209,7 @@ .SS Commands
.TP
(4)
if present, the terminal's initialization strings will be
-output as detailed in the \fBterminfo\fP(5) section on
+output as detailed in the \fB\%terminfo\fP(5) section on
.IR "Tabs and Initialization" ,
.TP
(5)
@@ -242,7 +254,7 @@ .SS Commands
of the terminal will be put out.
The long name is the last
name in the first line of the terminal's description in the
-\fBterminfo\fP database [see \fBterm\fP(5)].
+\fI\%term\%info\fP database [see \fBterm\fP(5)].
.SS Aliases
\fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
commands specially:
@@ -308,60 +320,61 @@ .SS "Terminal Size"
.SH EXIT STATUS
If the \fB\-S\fP option is used,
\fB@TPUT@\fP checks for errors from each line,
-and if any errors are found, will set the exit code to 4 plus the
+and if any errors are found, will set the exit status to 4 plus the
number of lines with errors.
-If no errors are found, the exit code is \fB0\fP.
+If no errors are found, the exit status is \fB0\fP.
No indication of which line failed can be given so
-exit code \fB1\fP will never appear.
-Exit codes \fB2\fP, \fB3\fP, and
+exit status \fB1\fP will never appear.
+Exit statuses \fB2\fP, \fB3\fP, and
\fB4\fP retain their usual interpretation.
If the \fB\-S\fP option is not used,
-the exit code depends on the type of \fIcapname\fP:
+the exit status depends on the type of \fIcap-code\fP:
.RS 3
.TP
-.I boolean
+.I Boolean
a value of \fB0\fP is set for TRUE and \fB1\fP for FALSE.
.TP
.I string
a value of \fB0\fP is set if the
-\fIcapname\fP is defined for this terminal \fItype\fP (the value of
-\fIcapname\fP is returned on standard output);
-a value of \fB1\fP is set if \fIcapname\fP
+\fIcap-code\fP is defined for this terminal \fItype\fP (the value of
+\fIcap-code\fP is returned on standard output);
+a value of \fB1\fP is set if \fIcap-code\fP
is not defined for this terminal \fItype\fP
(nothing is written to standard output).
.TP
.I integer
a value of \fB0\fP is always set,
-whether or not \fIcapname\fP is defined for this terminal \fItype\fP.
-To determine if \fIcapname\fP is defined for this terminal \fItype\fP,
+whether or not \fIcap-code\fP is defined for this terminal \fItype\fP.
+To determine if \fIcap-code\fP is defined for this terminal \fItype\fP,
the user must test the value written to standard output.
A value of \fB\-1\fP
-means that \fIcapname\fP is not defined for this terminal \fItype\fP.
+means that \fIcap-code\fP is not defined for this terminal \fItype\fP.
.TP
.I other
\fBreset\fP or \fBinit\fP may fail to find their respective files.
-In that case, the exit code is set to 4 + \fBerrno\fP.
+In that case, the exit status is set to 4 + \fBerrno\fP.
.RE
.PP
-Any other exit code indicates an error; see the DIAGNOSTICS section.
+Any other exit status indicates an error;
+see section \*(``DIAGNOSTICS\*('' below.
.SH DIAGNOSTICS
-\fB@TPUT@\fP prints the following error messages and sets the corresponding
exit
-codes.
+\fB@TPUT@\fP prints the following error messages and sets the
+corresponding exit statuses.
.PP
.ne 15
.TS
l l.
-exit code error message
+exit status error message
=
\fB0\fP T{
-(\fIcapname\fP is a numeric variable that is not specified in the
-\fBterminfo\fP(5) database for this terminal type, e.g.
+(\fIcap-code\fP is a numeric variable that is not specified in the
+\fB\%terminfo\fP(5) database for this terminal type, e.g.
\fB@TPUT@ \-T450 lines\fP and \fB@TPUT@ \-Thp2621 xmc\fP)
T}
\fB1\fP no error message is printed, see the \fBEXIT STATUS\fP section.
\fB2\fP usage error
-\fB3\fP unknown terminal \fItype\fP or no \fBterminfo\fP database
-\fB4\fP unknown \fBterminfo\fP capability \fIcapname\fP
+\fB3\fP unknown terminal \fItype\fP or no \fI\%term\%info\fP database
+\fB4\fP unknown \fI\%term\%info\fP capability \fIcap-code\fP
\fB>4\fP error occurred in \-S
=
.TE
@@ -376,7 +389,7 @@ .SH PORTABILITY
This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
two important areas:
.bP
-\fB@TPUT@\fP \fIcapname\fP writes to the standard output.
+\fB@TPUT@\fP \fIcap-code\fP writes to the standard output.
That need not be a regular terminal.
However, the subcommands which manipulate terminal modes
may not use the standard output.
@@ -396,17 +409,18 @@ .SH PORTABILITY
If it is not able to open a terminal, e.g., when running in \fBcron\fP(1),
\fB@TPUT@\fP will return an error.
.bP
-AT&T \fBtput\fP guesses the type of its \fIcapname\fP operands by seeing if
-all of the characters are numeric, or not.
+AT&T \fBtput\fP guesses the type of its \fIcap-code\fP operands by
+seeing if all of the characters are numeric,
+or not.
.IP
-Most implementations which provide support for \fIcapname\fP operands
+Most implementations which provide support for \fIcap-code\fP operands
use the \fBtparm\fP function to expand parameters in it.
That function expects a mixture of numeric and string parameters,
requiring \fB@TPUT@\fP to know which type to use.
.IP
This implementation uses a table to determine the parameter types for
-the standard \fIcapname\fP operands, and an internal library
-function to analyze nonstandard \fIcapname\fP operands.
+the standard \fIcap-code\fP operands, and an internal library
+function to analyze nonstandard \fIcap-code\fP operands.
.IP
Besides providing more reliable operation than AT&T's utility,
a portability problem is introduced by this analysis:
@@ -418,7 +432,7 @@ .SH PORTABILITY
specifically for OpenBSD.
.PP
This implementation (unlike others) can accept both \fItermcap\fP
-and \fIterminfo\fP names for the \fIcapname\fP feature,
+and \fIterminfo\fP names for the \fIcap-code\fP feature,
if
\fItermcap\fP support is compiled in.
However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
@@ -449,14 +463,15 @@ .SH PORTABILITY
documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
There are a few interesting observations to make regarding that:
.bP
-In this implementation, \fBclear\fP is part of the \fIcapname\fP support.
+In this implementation,
+\fBclear\fP is part of the \fIcap-code\fP support.
The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
capabilities.
.bP
Other implementations of \fBtput\fP on
SVr4-based systems such as Solaris, IRIX64 and HP-UX
as well as others such as AIX and Tru64
-provide support for \fIcapname\fP operands.
+provide support for \fIcap-code\fP operands.
.bP
A few platforms such as FreeBSD recognize termcap names rather
than terminfo capability names in their respective \fBtput\fP commands.
@@ -470,8 +485,8 @@ .SH PORTABILITY
support the full set of capability names, the reasoning for documenting
only a few may not be apparent.
.bP
-X/Open Curses Issue 7 documents \fBtput\fP differently, with \fIcapname\fP
-and the other features used in this implementation.
+X/Open Curses Issue 7 documents \fBtput\fP differently,
+with \fIcap-code\fP and the other features used in this implementation.
.bP
That is, there are two standards for \fBtput\fP:
POSIX (a subset) and X/Open Curses (the full implementation).
@@ -479,9 +494,12 @@ .SH PORTABILITY
and the terminal capabilities database.
.bP
While it is certainly possible to write a \fBtput\fP program
-without using curses,
-none of the systems which have a curses implementation provide
-a \fBtput\fP utility which does not provide the \fIcapname\fP feature.
+without using
+.I curses,
+no system with a
+.I curses
+implementation provides a \fBtput\fP utility that does not also supply
+the \fIcap-code\fP feature.
.PP
X/Open Curses Issue 7 (2009) is the first version to document utilities.
However that part of X/Open Curses does not follow existing practice
@@ -490,21 +508,21 @@ .SH PORTABILITY
.I curses
behavior).
.bP
-It assigns exit code 4 to \*(``invalid operand\*('',
+It assigns exit status 4 to \*(``invalid operand\*('',
which may be the same as \fIunknown capability\fP.
For instance, the source code for Solaris' xcurses uses the term
\*(``invalid\*('' in this case.
.bP
-It assigns exit code 255 to a numeric variable that is not specified in
+It assigns exit status 255 to a numeric variable that is not specified in
the terminfo database.
That likely is a documentation error,
confusing the \fB\-1\fP written to the standard output for an absent
-or cancelled numeric value versus an (unsigned) exit code.
+or cancelled numeric value versus an (unsigned) exit status.
.PP
-The various Unix systems (AIX, HP-UX, Solaris) use the same exit-codes
+The various Unix systems (AIX, HP-UX, Solaris) use the same exit statuses
as \fI\%ncurses\fP.
.PP
-NetBSD curses documents different exit codes which do not correspond
+NetBSD curses documents different exit statuses which do not correspond
to either \fI\%ncurses\fP or X/Open.
.SH HISTORY
The \fBtput\fP command was begun by Bill Joy in 1980.
@@ -589,7 +607,7 @@ .SH EXAMPLES
prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP
.TP 5
\fB@TPUT@ hc\fP
-Set exit code to indicate if the current terminal is a hard copy terminal.
+Set exit status to indicate if the current terminal is a hard copy terminal.
.TP 5
\fB@TPUT@ cup 23 4\fP
Send the sequence to move the cursor to row 23, column 4.
@@ -598,29 +616,29 @@ .SH EXAMPLES
Send the terminfo string for cursor-movement, with no parameters substituted.
.TP 5
\fB@TPUT@ longname\fP
-Print the long name from the \fBterminfo\fP database for the
+Print the long name from the \fI\%term\%info\fP database for the
type of terminal specified in the environmental
variable \fITERM\fP.
-.PP
-.RS 5
-\fB@TPUT@ \-S <<!\fP
-.br
-\fB> clear\fP
-.br
-\fB> cup 10 10\fP
-.br
-\fB> bold\fP
-.br
-\fB> !\fP
-.RE
.TP 5
-\&
-This example shows \fB@TPUT@\fP processing several capabilities
-in one invocation.
+\fB@TPUT@ \-S\fP
+The \fB\-S\fP option can be profitably used with a shell
+\*(``here document\*(''.
+.IP
+.EX
+$ \fB@TPUT@ \-S <<!\fP
+> \fBclear\fP
+> \fBcup 10 10\fP
+> \fBbold\fP
+> \fB!\fP
+.EE
+.IP
+We see \fB@TPUT@\fP processing several capabilities in one invocation.
It clears the screen,
-moves the cursor to position 10, 10
-and turns on bold (extra bright) mode.
-The list is terminated by an exclamation mark (\fB!\fP) on a line by itself.
+moves the cursor to position
+(10, 10)
+and turns on bold
+(extra bright)
+mode.
.SH SEE ALSO
\fB\%@CLEAR@\fP(1),
\fB\%stty\fP(1),
--
2.30.2
signature.asc
Description: PGP signature
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [PATCH 22/52] man/tput.1: Revise.,
G. Branden Robinson <=