[PATCH 21/40] man/tput.1: Revise (10/10) (EXAMPLES).

[G. Branden Robinson]

Content:
* Weaken advice to always call "tput init" in a shell startup file.
  This hasn't been necessary on most *nix systems for a long time;
  shells, ssh(1), getty(8), and whatever systemd replaces getty with
  seem reliable at taking care of this, and few terminal sessions are
  hosted over serial lines nowadays.
* Add example of "tput cnorm", as I have occasionally found it useful
  over the years when recovering my terminal sessions from a bad state.
* Change "cup 0 0" example to "cup home"; the latter capability is
  widely supported and it's convenient to let parameterized examples
  come up later in the series.
* Take the opportunity to illustrate the distinction between capability
  _names_ and capability _codes_ in the "clear" example.
* Revise "smso"/"rmso" example to use less misleading shell variable
  names.
* Revise follow-up to same example to use printf(1) instead of a
  non-portable (System V-ish) application of echo(1).

Style:
* Set follow-up to "smso"/"rmso" example as a (monospaced) example using
  the `EX`/`EE` macros.  Also inset it with `RS` and `RE`.
* Recast.
* Set user input and system output in different faces in "tput -S"
  example.  See groff_man_style(7).

Markup:
* Drop explicit paragraph tag width specification; all of the examples
  break after tag anyway.
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross (and topic self-)references.
* Quote multi-word arguments to font macros; McIlroy man(7) and its
  descendants have a six-argument limit.
* Replace use of groff special character escape sequences with existing
  strings for quotation.
---
 man/tput.1 | 152 ++++++++++++++++++++++++++++++++---------------------
 1 file changed, 92 insertions(+), 60 deletions(-)

diff --git a/man/tput.1 b/man/tput.1
index f699bf13e..4612dd238 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -881,77 +881,109 @@ .SH HISTORY
 standard error for \fB\%@TSET@\fP and
 standard output for \fB\%@TPUT@\fP.
 .SH EXAMPLES
-.TP 5
-\fB@TPUT@ init\fP
+.TP
+.B "@TPUT@ init"
 Initialize the terminal according to the type of
-terminal in the environment variable \fITERM\fP.
-This command should be included in everyone's .profile after
-the environment variable \fITERM\fP has been exported,
-as illustrated on the \fBprofile\fP(5) manual page.
-.TP 5
-\fB@TPUT@ \-T5620 reset\fP
-Reset an AT&T 5620 terminal, overriding the type of
-terminal in the environment variable \fITERM\fP.
-.TP 5
-\fB@TPUT@ cup 0 0\fP
-Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP
-(the upper left corner of the screen, usually known as the \*(``home\*(''
-cursor position).
-.TP 5
-\fB@TPUT@ clear\fP
-Echo the clear-screen sequence for the current terminal.
-.TP 5
-\fB@TPUT@ cols\fP
-Print the number of columns for the current terminal.
-.TP 5
-\fB@TPUT@ \-T450 cols\fP
-Print the number of columns for the 450 terminal.
-.TP 5
-\fBbold=\(ga@TPUT@ smso\(ga offbold=\(ga@TPUT@ rmso\(ga\fP
-Set the shell variables \fBbold\fP, to begin stand-out mode
-sequence, and \fBoffbold\fP, to end standout mode sequence,
-for the current terminal.
-This might be followed by a
-prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP
-.TP 5
-\fB@TPUT@ hc\fP
-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.
-.TP 5
-\fB@TPUT@ cup\fP
-Send the terminfo string for cursor-movement, with no parameters substituted.
-.TP 5
-\fB@TPUT@ longname\fP
-Print the long name from the \fI\%term\%info\fP database for the
-type of terminal specified in the environment
-variable \fITERM\fP.
-.TP 5
-\fB@TPUT@ \-S\fP
-The \fB\-S\fP option can be profitably used with a shell
-\*(``here document\*(''.
+terminal in the
+.I TERM
+environment variable.
+If the system does not reliably initialize the terminal upon login,
+this command can be included in
+.I \%$HOME/.profile
+after exporting the
+.I TERM
+environment variable.
+.TP
+.B "@TPUT@ \-T5620 reset"
+Reset an AT&T 5620 terminal,
+overriding the terminal type in the
+.I TERM
+environment variable.
+.TP
+.B "@TPUT@ cnorm"
+Set cursor to normal visibility.
+.TP
+.B "@TPUT@ home"
+Move the cursor to row 0,
+column 0:
+the upper left corner of the screen,
+usually known as the \*(``home\*('' cursor position.
+.TP
+.B "@TPUT@ clear"
+Clear the screen:
+write the
+.B \%clear_screen
+capability's value to the standard output stream.
+.TP
+.B "@TPUT@ cols"
+Report the number of columns used by the current terminal type.
+.TP
+.B "@TPUT@ \-Tadm3a cols"
+Report the number of columns used by an ADM-3A terminal.
+.TP
+.B "strong=\(ga@TPUT@ smso\(ga normal=\(ga@TPUT@ rmso\(ga"
+Set shell variables to capability values:
+.B strong
+and
+.BR normal ,
+to begin and end,
+respectively,
+stand-out mode for the terminal.
+One might use these to present a prompt.
+.IP
+.EX
+.RS 14
+printf "${strong}Username:${normal} "
+.RE
+.EE
+.TP
+.B "@TPUT@ hc"
+Indicate via exit status whether the terminal is a hard copy device.
+.TP
+.B "@TPUT@ cup 23 4"
+Move the cursor to row 23,
+column 4.
+.TP
+.B "@TPUT@ cup"
+Report the value of the
+.B \%cursor_address
+.RB ( cup )
+capability
+(used for cursor movement),
+with no parameters substituted.
+.TP
+.B "@TPUT@ longname"
+Report the
+.I \%term\%info
+database's description of the terminal type specified in the
+.I TERM
+environment variable.
+.TP
+.B "@TPUT@ \-S"
+Process multiple capabilities.
+The
+.B \-S
+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
+.RB $\  "@TPUT@ \-S <<!"
+.RB >\  clear
+.RB >\  "cup 10 10"
+.RB >\  bold
+.RB >\  !
 .EE
 .IP
-We see \fB@TPUT@\fP processing several capabilities in one invocation.
-It clears the screen,
+The foregoing
+clears the screen,
 moves the cursor to position
 (10, 10)
 and turns on bold
 (extra bright)
 mode.
-.TP 5
-.B @TPUT@ clear cup 10 10 bold
+.TP
+.B "@TPUT@ clear cup 10 10 bold"
 Perform the same actions as the foregoing
-.RB \%\[lq] @TPUT@
-.BR \-S \[rq]
+.RB \%\*(`` "@TPUT@ \-S" \*(''
 example.
 .SH SEE ALSO
 \fB\%@CLEAR@\fP(1),
-- 
2.30.2

signature.asc
Description: PGP signature