[PATCH 19/40] man/tput.1: Revise (8/10) (PORTABILITY).

[G. Branden Robinson]

Content:
* Add forward cross reference to "HISTORY" section for ncurses 6.1
  tput/tset changes.
* Refer to the relevant standard as "X/Open Curses", not just "X/Open",
  since X/Open produces multiple standards.

Style:
* Recast.
* Set file name literals in italics instead of quoting them.
* Quote phrases from standards instead of italicizing them.
* Spell names of BSD distributions canonically.
* Spell out "baud" instead of abbreviating it.
* Favor "ncurses" over "this implementation" (where not repetitious).
* Set "termcap" and "terminfo" in italics.

Markup:
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references.
* Protect "@TPUT@", operand literals, and man page topics from
  hyphenation.
* Prevent break within "System V".
---
 man/tput.1 | 369 ++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 267 insertions(+), 102 deletions(-)

diff --git a/man/tput.1 b/man/tput.1
index 235f3d570..6bb55457f 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -427,121 +427,274 @@ .SH FILES
 .I \*d
 compiled terminal description database
 .SH PORTABILITY
-This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
-two important areas:
-.bP
-\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.
+Over time
+.I \%ncurses
+\fB\%@TPUT@\fP
+has differed from that of System\ V in two important respects,
+one now mostly historical.
+.bP
+\%\*(``\fB@TPUT@\fP
+.IR cap-code \*(''
+writes to the standard output,
+which need not be a terminal device.
+However,
+the operands that manipulate terminal modes might not use the standard
+output.
 .IP
-The AT&T implementation's \fBinit\fP and \fBreset\fP commands
-use the BSD (4.1c) \fBtset\fP source, which manipulates terminal modes.
-It successively tries standard output, standard error, standard input
-before falling back to \*(``/dev/tty\*('' and finally just assumes
-a 1200Bd terminal.
-When updating terminal modes, it ignores errors.
+System\ V
+.BR tput 's
+.B init
+and
+.B \%reset
+operands use logic from 4.1cBSD
+.BR tset ,
+manipulating terminal modes.
+It checks the same file descriptors
+(and
+.IR \%/dev/tty )
+for association with a terminal device as
+.I \%ncurses
+now does,
+and if none are,
+finally assumes a 1200 baud terminal.
+When updating terminal modes,
+it ignores errors.
 .IP
-Until changes made after \fI\%ncurses\fP 6.0,
-\fB@TPUT@\fP did not modify terminal modes.
-\fB@TPUT@\fP now uses a similar scheme,
-using functions shared with \fB@TSET@\fP
-(and ultimately based on the 4.4BSD \fBtset\fP).
-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 \fIcap-code\fP operands by
-seeing if all of the characters are numeric,
-or not.
+Until
+.I \%ncurses
+6.1
+(see section \*(``HISTORY\*('' below),
+\fB\%@TPUT@\fP did not modify terminal modes.
+It now employs a scheme similar to System\ V,
+using functions shared with \fB\%@TSET@\fP
+(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.
+.bP
+System\ V
+.B tput
+assumes that the type of a
+.I cap-code
+operand is numeric if all the characters of its value are decimal
+numbers;
+if they are not,
+it treats
+.I cap-code
+as a string capability.
 .IP
-Most implementations which provide support for \fIcap-code\fP operands
-use the \fBtparm\fP function to expand parameters in it.
+Most implementations that provide support for
+.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 \fB\%@TPUT@\fP to know which type to use.
 .IP
-This implementation uses a table to determine the parameter types for
-the standard \fIcap-code\fP operands, and an internal library
-function to analyze nonstandard \fIcap-code\fP operands.
+.I \%ncurses
+\fB\%@TPUT@\fP
+uses a table to determine the parameter types for
+the standard
+.I cap-code
+operands,
+and an internal function to analyze nonstandard
+.I cap-code
+operands.
 .IP
-Besides providing more reliable operation than AT&T's utility,
-a portability problem is introduced by this analysis:
+While more reliable than System\ V's utility,
+a portability problem is introduced by this analysis.
 An OpenBSD developer adapted the internal library function from
-\fI\%ncurses\fP to port NetBSD's termcap-based \fBtput\fP to terminfo.
-That had been modified to interpret multiple commands on a line.
+.I \%ncurses
+to port NetBSD's
+.IR termcap -based
+.B tput
+to
+.I \%term\%info,
+and modified it to interpret multiple
+.I cap-codes
+(and parameters)
+on the command line.
 Portable applications should not rely upon this feature;
-\fI\%ncurses\fP provides it to support applications written
-specifically for OpenBSD.
+.I \%ncurses
+offers it to support applications written specifically for OpenBSD.
 .PP
-This implementation (unlike others) can accept both \fItermcap\fP
-and \fIterminfo\fP names for the \fIcap-code\fP feature,
+This implementation,
+unlike others,
+accepts both
+.I termcap
+and
+.I \%term\%info
+.I cap-codes
 if
-\fItermcap\fP support is compiled in.
-However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
-ambiguities in this case (and the \fIterminfo\fP name is assumed):
-.bP
-The \fItermcap\fP name \fBdl\fP corresponds to
-the \fIterminfo\fP name \fBdl1\fP (delete one line).
-.br
-The \fIterminfo\fP name \fBdl\fP corresponds to
-the \fItermcap\fP name \fBDL\fP (delete a given number of lines).
-.bP
-The \fItermcap\fP name \fBed\fP corresponds to
-the \fIterminfo\fP name \fBrmdc\fP (end delete mode).
-.br
-The \fIterminfo\fP name \fBed\fP corresponds to
-the \fItermcap\fP name \fBcd\fP (clear to end of screen).
+.I termcap
+support is compiled in.
+In that case,
+however,
+the predefined
+.I termcap
+and
+.I \%term\%info
+codes have two
+ambiguities;
+.I \%ncurses
+assumes the
+.I \%term\%info
+code.
+.bP
+The
+.I cap-code
+.B dl
+means
+.B \%delete_line
+to
+.I termcap
+but
+.B \%parm_delete_line
+to
+.I \%term\%info.
+.I termcap
+uses the code
+.B DL
+for
+.BR \%parm_delete_line .
+.I \%term\%info
+uses the code
+.B dch1
+for
+.BR \%delete_line .
+.bP
+The
+.I cap-code
+.B ed
+means
+.B \%exit_delete_mode
+to
+.I termcap
+but
+.B \%clr_eos
+to
+.I \%term\%info.
+.I termcap
+uses the code
+.B cd
+for
+.BR \%clr_eos .
+.I \%term\%info
+uses the code
+.B rmdc
+for
+.BR \%exit_delete_mode .
 .PP
-The \fBlongname\fP and \fB\-S\fP options, and the parameter-substitution
-features used in the \fBcup\fP example,
+The
+.B \%longname
+operand,
+.B \-S
+option,
+and the parameter-substitution features used in the
+.B cup
+example below,
 were not supported in
 AT&T/USL
 .I curses
 before SVr4 (1989).
-Later, 4.3BSD-Reno (1990) added support for \fBlongname\fP,
+Later,
+4.3BSD-Reno (1990) added support for
+.BR \%longname ,
 .\" longname was added in October 1989.
-and NetBSD (1994) added support for the parameter-substitution features.
+and in 1994,
+NetBSD added support for the parameter-substitution features.
 .PP
-IEEE Std 1003.1/The Open Group  Base Specifications Issue 7 (POSIX.1-2008)
-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 \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 \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.
-Since 2010, NetBSD's \fBtput\fP uses terminfo names.
-Before that, it (like FreeBSD) recognized termcap names.
+IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+(POSIX.1-2008)
+documents only the
+.BR clear ,
+.BR init ,
+and
+.B \%reset
+operands.
+A few observations of interest arise from that selection.
+.bP
+.I \%ncurses
+supports
+.B clear
+as it does any other standard
+.I cap-code.
+The others
+.RB ( init
+and
+.BR \%longname )
+do not correspond to terminal capabilities.
+.bP
+The
+.B tput
+on SVr4-based systems such as Solaris,
+IRIX64,
+and HP-UX,
+as well as others such as AIX and Tru64,
+also support standard
+.I cap-code
+operands.
+.bP
+A few platforms such as FreeBSD recognize
+.I termcap
+names rather than
+.I \%term\%info
+capability names in their respective
+.B tput
+commands.
+Since 2010,
+NetBSD's
+.B tput
+uses
+.I \%term\%info
+names.
+Before that,
+it
+(like FreeBSD)
+recognized
+.I termcap
+names.
 .IP
-Beginning in 2021, FreeBSD uses the \fI\%ncurses\fP \fBtput\fP,
-configured for both terminfo (tested first) and termcap (as a fallback).
+Beginning in 2021,
+FreeBSD uses
+.I \%ncurses
+.BR tput ,
+configured for both
+.I \%term\%info
+(tested first)
+and
+.I termcap
+(as a fallback).
 .PP
-Because (apparently) \fIall\fP of the certified Unix systems
-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 \fIcap-code\fP and the other features used in this implementation.
+Because (apparently) all
+.I certified
+Unix systems support the full set of capability codes,
+the reason for documenting only a few may not be apparent.
+.bP
+X/Open Curses Issue 7 documents
+.B tput
+differently,
+with
+.I cap-code
+and the other features used in this implementation.
 .bP
-That is, there are two standards for \fBtput\fP:
+That is,
+there are two standards for
+.BR tput :
 POSIX (a subset) and X/Open Curses (the full implementation).
-POSIX documents a subset to avoid the complication of including X/Open Curses
-and the terminal capabilities database.
+POSIX documents a subset to avoid the complication of including
+X/Open Curses and the terminal capability database.
 .bP
-While it is certainly possible to write a \fBtput\fP program
-without using
+While it is certainly possible to write a
+.B tput
+program 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.
+implementation provides a
+.B tput
+utility that does not also support standard
+.I cap-codes.
 .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
@@ -551,21 +704,33 @@ .SH PORTABILITY
 behavior).
 .bP
 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 status 255 to a numeric variable that is not specified in
-the terminfo database.
+which may have the same meaning as \*(``unknown capability\*(''.
+For instance,
+the source code for
+Solaris
+.I xcurses
+uses the term \*(``invalid\*('' in this case.
+.bP
+It assigns exit status 255 to a numeric variable that is not specified
+in the
+.I \%term\%info
+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 status.
+mistaking the \*(``\-1\*('' written to the standard output to indicate
+an absent or cancelled numeric capability for an (unsigned) exit status.
 .PP
-The various Unix systems (AIX, HP-UX, Solaris) use the same exit statuses
-as \fI\%ncurses\fP.
+The various System\ V implementations
+(AIX,
+HP-UX,
+Solaris)
+use the same exit statuses as
+.I \%ncurses.
 .PP
-NetBSD curses documents different exit statuses which do not correspond
-to either \fI\%ncurses\fP or X/Open.
+NetBSD
+.I curses
+documents exit statuses that correspond to neither
+.I \%ncurses
+nor X/Open Curses.
 .SH HISTORY
 The \fBtput\fP command was begun by Bill Joy in 1980.
 The initial version only cleared the screen.
-- 
2.30.2

signature.asc
Description: PGP signature