[PATCH 066/177] man/tput.1: Fix markup nit.

[G. Branden Robinson]

Favor man(7) font style macros over *roff font selection escape
sequences, except for man page cross references (because man/make_sed.sh
recognizes only certain patterns when rewriting such cross references)
and terms in the "NAME" section (because the generated edit_man.sh
script expects font selection escape sequences when scraping terms
thence to gather names for man page aliases).

Ensure that whatever `@TPUT@` expands to is protected from hyphenation.
---
 man/tput.1 | 155 ++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 107 insertions(+), 48 deletions(-)

diff --git a/man/tput.1 b/man/tput.1
index 83d2d6c7a..b096f838d 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -64,7 +64,8 @@ .SH SYNOPSIS
 .PP
 \fB@TPUT@\fP [\fB\-v\fP] \fB\-V\fP
 .SH DESCRIPTION
-\fB\%@TPUT@\fP uses the
+.B \%@TPUT@
+uses the
 .I \%term\%info
 library and database to make terminal-specific capabilities and
 information available to the shell,
@@ -84,7 +85,8 @@ .SH DESCRIPTION
 the result depends upon the capability's type.
 .TP 9 \" "Boolean" + 2n
 Boolean
-\fB\%@TPUT@\fP sets its exit status to
+.B \%@TPUT@
+sets its exit status to
 .B 0
 if the terminal possesses
 .IR cap-code ,
@@ -93,7 +95,8 @@ .SH DESCRIPTION
 if it does not.
 .TP
 numeric
-\fB\%@TPUT@\fP writes
+.B \%@TPUT@
+writes
 .IR cap-code 's
 decimal value to the standard output stream if defined
 .RB ( \-1
@@ -101,13 +104,16 @@ .SH DESCRIPTION
 followed by a newline.
 .TP
 string
-\fB\%@TPUT@\fP writes
+.B \%@TPUT@
+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
+the application should test
+.B \%@TPUT@ "'s"
+exit status
 to be sure it is 0;
 see section \*(``EXIT STATUS\*('' below.
 .SS Operands
@@ -116,7 +122,8 @@ .SS Operands
 .IR cap-code ,
 a capability code from the terminal database,
 or a parameter thereto.
-Three others are specially recognized by \fB\%@TPUT@\fP:
+Three others are specially recognized by
+.BR \%@TPUT@ ":"
 .BR init ,
 .BR \%reset ,
 and
@@ -131,18 +138,23 @@ .SS Operands
 If
 .I cap-code
 is of string type and takes parameters,
-\fB\%@TPUT@\fP interprets arguments following
+.B \%@TPUT@
+interprets arguments following
 .I cap-code
 as the parameters,
 up to the (fixed) quantity the capability requires.
 .IP
 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 \fB\%tparm\fP(3X) to perform the
+.B \%@TPUT@
+uses a table to decide which to pass as strings.
+Normally
+.B \%@TPUT@
+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.
+.B \%@TPUT@
+writes the string without performing the substitution.
 .TP
 .B init
 initializes the terminal.
@@ -152,7 +164,8 @@ .SS Operands
 .RS
 .TP 5
 (1)
-\fB\%@TPUT@\fP retrieves the terminal's mode settings.
+.B \%@TPUT@
+retrieves the terminal's mode settings.
 It successively tests the file descriptors corresponding to
 .RS
 .bP
@@ -168,15 +181,18 @@ .SS Operands
 .IP
 to obtain terminal settings.
 Having retrieved them,
-\fB\%@TPUT@\fP remembers which descriptor to use for further updates.
+.B \%@TPUT@
+remembers which descriptor to use for further updates.
 .TP
 (2)
 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.
+.B \%@TPUT@
+updates the operating system's notion of them.
 .TP
 (3)
-\fB\%@TPUT@\fP updates the terminal modes.
+.B \%@TPUT@
+updates the terminal modes.
 .RS
 .bP
 Any delays specified in the entry
@@ -198,10 +214,12 @@ .SS Operands
 detailed in subsection \*(``Tabs and Initialization\*('' of
 \fB\%terminfo\fP(5),
 are present,
-\fB\%@TPUT@\fP writes them to the standard output stream.
+.B \%@TPUT@
+writes them to the standard output stream.
 .TP
 (5)
-\fB\%@TPUT@\fP flushes the standard output stream.
+.B \%@TPUT@
+flushes the standard output stream.
 .RE
 .IP
 If an entry lacks the information needed for an activity above,
@@ -213,7 +231,8 @@ .SS Operands
 .RS
 .TP 5
 (1)
-\fB\%@TPUT@\fP sets the the terminal modes to a \*(``sane\*('' state,
+.B \%@TPUT@
+sets the the terminal modes to a \*(``sane\*('' state,
 .RS
 .bP
 enabling canonical (\*(``cooked\*('') and echo modes,
@@ -228,9 +247,11 @@ .SS Operands
 .TP 5
 (2)
 If any reset capabilities are defined for the terminal type,
-\fB\%@TPUT@\fP writes them to the output stream.
+.B \%@TPUT@
+writes them to the output stream.
 Otherwise,
-\fB\%@TPUT@\fP uses any defined initialization capabilities.
+.B \%@TPUT@
+uses any defined initialization capabilities.
 Reset capabilities are detailed in subsection
 \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
 .RE
@@ -253,7 +274,8 @@ .SS Operands
 .IP
 If the terminal database is present and an entry for the user's terminal
 type exists,
-\fB\%@TPUT@\fP reports its description to the standard output stream,
+.B \%@TPUT@
+reports its description to the standard output stream,
 without a trailing newline.
 See \fB\%terminfo\fP(5).
 .PP
@@ -267,7 +289,9 @@ .SS Operands
 redirection,
 since the terminal modes are altered via \fB\%ioctl\fP(2).
 .SS Aliases
-If \fB\%@TPUT@\fP is invoked via link with any of the names
+If
+.B \%@TPUT@
+is invoked via link with any of the names
 .BR clear ,
 .BR init ,
 or
@@ -277,7 +301,9 @@ .SS Aliases
 For example,
 executing a link named
 .B \%reset
-that points to \fB\%@TPUT@\fP has the same effect as
+that points to
+.B \%@TPUT@
+has the same effect as
 .RB \%\*(`` "@TPUT@ \%reset" \*(''.
 .PP
 This feature was introduced by
@@ -300,7 +326,8 @@ .SS "Terminal Size"
 Besides the pseudo-capabilities
 (such as
 .BR init ),
-\fB\%@TPUT@\fP treats the
+.B \%@TPUT@
+treats the
 .B lines
 and
 .B cols
@@ -309,7 +336,8 @@ .SS "Terminal Size"
 it may call \fB\%setupterm\fP(3X) to obtain the terminal size.
 .bP
 First,
-\fB\%@TPUT@\fP attempts to obtain these capabilities from the terminal
+.B \%@TPUT@
+attempts to obtain these capabilities from the terminal
 database.
 This generally fails for terminal emulators,
 which lack a fixed window size and thus omit the capabilities.
@@ -329,7 +357,8 @@ .SS "Terminal Size"
 If the
 .B \-T
 option is given,
-\fB\%@TPUT@\fP ignores the environment variables by calling
+.B \%@TPUT@
+ignores the environment variables by calling
 .BR \%use_tioctl(TRUE) ,
 relying upon the operating system
 (or,
@@ -338,8 +367,11 @@ .SS "Terminal Size"
 .SH OPTIONS
 .TP 9n \" "-T type" + 2n
 .B \-S
-retrieves more than one capability per invocation of \fB\%@TPUT@\fP.
-The capabilities must be passed to \fB\%@TPUT@\fP from the standard
+retrieves more than one capability per invocation of
+.BR \%@TPUT@ "."
+The capabilities must be passed to
+.B \%@TPUT@
+from the standard
 input stream instead of from the command line
 (see section \*(``EXAMPLES\*('' below).
 Only one
@@ -355,7 +387,8 @@ .SH OPTIONS
 (see section \*(``EXIT STATUS\*('' below).
 .IP
 Some capabilities use string parameters rather than numeric ones.
-\fB\%@TPUT@\fP employs a built-in table and the presence of parameters
+.B \%@TPUT@
+employs a built-in table and the presence of parameters
 in its input to decide how to interpret them,
 and whether to use \fB\%tparm\fP(3X).
 .TP
@@ -374,13 +407,16 @@ .SH OPTIONS
 are also ignored.
 .TP
 .B \-v
-causes \fB\%@TPUT@\fP to operate verbosely,
+causes
+.B \%@TPUT@
+to operate verbosely,
 reporting warnings.
 .TP
 .B \-V
 reports the version of
 .I \%ncurses
-associated with \fB\%@TPUT@\fP,
+associated with
+.BR \%@TPUT@ ","
 and exits with a successful status.
 .TP
 .B \-x
@@ -389,7 +425,9 @@ .SH OPTIONS
 from attempting to clear the scrollback buffer.
 .SH EXIT STATUS
 Normally,
-one should interpret \fB\%@TPUT@\fP's exit statuses as follows.
+one should interpret
+.BR \%@TPUT@ "'s"
+exit statuses as follows.
 .PP
 .if n .ne 3
 .if t .ne 2
@@ -423,7 +461,8 @@ .SH EXIT STATUS
 4      some operands not interpreted
 .TE
 .SH ENVIRONMENT
-\fB@TPUT@\fP reads one environment variable.
+.B \%@TPUT@
+reads one environment variable.
 .TP 8n \" "TERM" + 2n + adjustment for PDF
 .I TERM
 denotes the terminal type.
@@ -442,11 +481,11 @@ .SH FILES
 .SH PORTABILITY
 Over time
 .I \%ncurses
-\fB\%@TPUT@\fP
+.B \%@TPUT@
 has differed from that of System\ V in two important respects,
 one now mostly historical.
 .bP
-\%\*(``\fB@TPUT@\fP
+.RB \%\*(`` @TPUT@
 .IR cap-code \*(''
 writes to the standard output,
 which need not be a terminal device.
@@ -477,15 +516,18 @@ .SH PORTABILITY
 .I \%ncurses
 6.1
 (see section \*(``HISTORY\*('' below),
-\fB\%@TPUT@\fP did not modify terminal modes.
+.B \%@TPUT@
+did not modify terminal modes.
 It now employs a scheme similar to System\ V,
-using functions shared with \fB\%@TSET@\fP
+using functions shared with
+.B \%@TSET@
 (and ultimately based on 4.4BSD
 .BR tset ).
 If it is not able to open a terminal
 (for instance,
 when run by \fIcron\fP(1)),
-\fB\%@TPUT@\fP exits with an error status.
+.B \%@TPUT@
+exits with an error status.
 .bP
 System\ V
 .B tput
@@ -502,10 +544,12 @@ .SH PORTABILITY
 .I cap-code
 operands use the \fB\%tparm\fP(3X) function to expand its parameters.
 That function expects a mixture of numeric and string parameters,
-requiring \fB\%@TPUT@\fP to know which type to use.
+requiring
+.B \%@TPUT@
+to know which type to use.
 .IP
 .I \%ncurses
-\fB\%@TPUT@\fP
+.B \%@TPUT@
 uses a table to determine the parameter types for
 the standard
 .I cap-code
@@ -831,7 +875,8 @@ .SH HISTORY
 .PP
 The origin of
 .I \%ncurses
-\fB\%@TPUT@\fP lies outside both System\ V and BSD,
+.B \%@TPUT@
+lies outside both System\ V and BSD,
 in Ross Ridge's
 .I \%mytinfo
 package,
@@ -856,13 +901,19 @@ .SH HISTORY
 Before
 .I \%ncurses
 6.1 (2018),
-its \fB\%@TSET@\fP and \fB\%@TPUT@\fP utilities differed.
+its
+.B \%@TSET@
+and
+.B \%@TPUT@
+utilities differed.
 .bP
-\fB\%@TSET@\fP was more effective,
+.B \%@TSET@
+was more effective,
 resetting the terminal's modes and special input characters.
 .bP
 On the other hand,
-\fB\%@TSET@\fP's repertoire of terminal capabilities for resetting the
+.BR \%@TSET@ "'s"
+repertoire of terminal capabilities for resetting the
 terminal was more limited;
 it had only equivalents of
 .B \%reset_1string
@@ -872,11 +923,14 @@ .SH HISTORY
 and
 .B \%reset_file
 .RB ( rf ),
-and not the tab stop and margin update features of \fB\%@TPUT@\fP.
+and not the tab stop and margin update features of
+.BR \%@TPUT@ "."
 .PP
 The
 .B \%reset
-program is traditionally an alias for \fB\%@TSET@\fP due to its ability
+program is traditionally an alias for
+.B \%@TSET@
+due to its ability
 to reset the terminal's modes and special input characters.
 .PP
 As of
@@ -886,7 +940,9 @@ .SH HISTORY
 Two minor differences remain.
 .bP
 When issuing a reset,
-the \fB\%@TSET@\fP program
+the
+.B \%@TSET@
+program
 checks whether the device appears to be a pseudoterminal
 (as might be used by a terminal emulator program),
 and,
@@ -896,8 +952,11 @@ .SH HISTORY
 The two programs write the terminal initialization strings
 to different streams;
 that is,
-standard error for \fB\%@TSET@\fP and
-standard output for \fB\%@TPUT@\fP.
+standard error for
+.B \%@TSET@
+and
+standard output for
+.BR \%@TPUT@ "."
 .SH EXAMPLES
 .TP
 .B "@TPUT@ init"
-- 
2.30.2

signature.asc
Description: PGP signature