[PATCH 09/40] man/tput.1: Correct and simplify exit status discussion.

[G. Branden Robinson]

Content:
* The claim about "tput -S" accumulating a count of erroneous input
  lines and adding their sum to an exit status of 4 does not document
  ncurses tput(1) behavior.
* Fewer sorts of diagnostics are emitted than claimed, and are
  self-explanatory in any case; drop "DIAGNOSTICS" section and reference
  to it.
* Present exit status information in two tables; one for "normal"
  (non-S) operation, and one presenting changes when "-S" is used.

Style:
* Present material more economically, and stop table widths from
  overrunning line length on conservative old 65n man(7) environments.
* Set column headings in titlecase for consistency with other tables in
  ncurses man pages.

Markup:
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references.

Fixes:
.../share/man/man1/tput.1:385: warning: table wider than line length minus 
indentation
---
 man/tput.1 | 88 +++++++++++++++++++-----------------------------------
 1 file changed, 31 insertions(+), 57 deletions(-)

diff --git a/man/tput.1 b/man/tput.1
index 48ad00c9d..7f2e0758f 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -104,7 +104,7 @@ .SH DESCRIPTION
 (for example,
 using \fB$?\fP in \fIsh\fP(1))
 to be sure it is \fB0\fP;
-see sections \*(``EXIT STATUS\*('' and \*(``DIAGNOSTICS\*('' below.
+see section \*(``EXIT STATUS\*('' below.
 For a complete list of
 .I cap-codes,
 see \fB\%terminfo\fP(5).
@@ -336,65 +336,39 @@ .SS "Terminal Size"
 @TPUT@ ignores the environment variables by calling \fBuse_tioctl(TRUE)\fP,
 relying upon the operating system (or finally, the terminal database).
 .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 status to 4 plus the
-number of lines with errors.
-If no errors are found, the exit status is \fB0\fP.
-No indication of which line failed can be given so
-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 status depends on the type of \fIcap-code\fP:
-.RS 3
-.TP
-.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
-\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 \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 \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 status is set to 4 + \fBerrno\fP.
-.RE
+Normally,
+one should interpret \fB\%@TPUT@\fP's exit statuses as follows.
+.PP
+.if n .ne 3
+.if t .ne 2
+.TS
+Lb Lb
+Lb Lx.
+Status Meaning When \-S Not Specified
+_
+0      Boolean or string capability present
+1      Boolean or numeric capability absent
+2      usage error or no terminal type specified
+3      unrecognized terminal type
+4      unrecognized capability code
+>4     system error (4 + \fBerrno\fP)
+.TE
 .PP
-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 statuses.
+When the
+.B \-S
+option is used,
+some statuses change meanings.
 .PP
-.ne 15
+.if n .ne 4
+.if t .ne 3
 .TS
-l l.
-exit status    error message
-=
-\fB0\fP        T{
-(\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 \fI\%term\%info\fP database
-\fB4\fP        unknown \fI\%term\%info\fP capability \fIcap-code\fP
-\fB>4\fP       error occurred in \-S
-=
+Lb Lb
+Lb Lx.
+Status Meaning When \-S Specified
+_
+0      all operands interpreted
+1      unused
+4      some operands not interpreted
 .TE
 .SH FILES
 .TP
-- 
2.30.2

signature.asc
Description: PGP signature