[PATCH 9/9] man/clear.1: Revise content.

[G. Branden Robinson]

...with some formatting tweaks too.

* Reorganize.  Discuss specific terminfo capabilities a bit later, and
  more orthogonally, naming both of the relevant ones instead of only
  the newfangled `E3`.
* Introduce (flog?) "user-defined capabilities", now 24 years old.
* Favor active voice over passive.
* Favor present tense over future.
* Favor English words over Latin abbreviations.
* Favor pronomial adjectives with explicit nouns over demonstrative
  pronouns.
* Set tagged paragraph indentation in option list sufficient to prevent
  a break after "-T type".
* Consistently refer to environment variables as such.
* Move stray introduction to "OPTIONS" section to its proper place.
* Update history and annotate relevant URLs (to TUHS) in comments.
* More explicitly discuss termcap and terminfo distinction in
  implementations.
* More clearly distinguish AT&T commercial Unix from Eighth Edition
  Unix, a Bell Labs (research) effort.
* Set "xterm" in italics, like "ncurses", "termcap", and "terminfo".
* Consistently refer to "scrollback buffer".  Don't set it in italics.
* Quote title of "XTerm Control Sequences" instead of italicizing it.
* Don't confuse developers with programs.
* Be clearer with pronouns and their antecedents.
---
 man/clear.1 | 117 ++++++++++++++++++++++++++++------------------------
 1 file changed, 62 insertions(+), 55 deletions(-)

diff --git a/man/clear.1 b/man/clear.1
index 47f5dae9..79acd25d 100644
--- a/man/clear.1
+++ b/man/clear.1
@@ -91,44 +91,47 @@ .SH SYNOPSIS
 .PP
 .B "@CLEAR@ \-V"
 .SH DESCRIPTION
-\fB\%@CLEAR@\fP clears your terminal's screen if this is possible,
-including the terminal's scrollback buffer
-(if the extended \*(``E3\*('' capability is defined).
-\fB\%@CLEAR@\fP looks in the environment for the terminal type
-given by the environment variable \fBTERM\fP,
-and then in the
-\fIterminfo\fP database to determine how to clear the screen.
+\fB\%@CLEAR@\fP clears your terminal's screen and its scrollback buffer,
+if any.
+\fB\%@CLEAR@\fP retrieves the terminal type from the environment
+variable \fBTERM\fP,
+then consults the \fIterminfo\fP terminal capability database entry for
+that type to determine how to perform these actions.
 .PP
-\fB\%@CLEAR@\fP writes to the standard output.
-You can redirect the standard output to a file (which prevents
-\fB\%@CLEAR@\fP from actually clearing the screen),
-and later \fBcat\fP the file to the screen, clearing it at that point.
+The capabilities to clear the screen and scrollback buffer are named
+\*(``clear\*('' and \*(``E3\*('', respectively.
+The latter is a \fIuser-defined capability\fP,
+applying an extension mechanism introduced in \fIncurses\fP 5.0 (1999).
 .SH OPTIONS
-.TP 5
+\fB\%@CLEAR@\fP recognizes the following options.
+.TP 9 \" "-T type" + 2n
 .B \-T \fItype\fP
-indicates the \fItype\fP of terminal.
-Normally this option is
-unnecessary, because the default is taken from the environment
-variable \fBTERM\fP.
-If \fB\-T\fP is specified, then the shell
-variables \fBLINES\fP and \fB\%COLUMNS\fP will also be ignored.
+produces instructions suitable for the terminal \fItype\fP.
+Normally,
+this option is unnecessary,
+because the terminal type is inferred from the environment variable
+\fBTERM\fP.
+If this option is specified,
+\fB\%@CLEAR@\fP ignores the environment variables \fBLINES\fP and
+\fB\%COLUMNS\fP as well.
 .TP
 .B \-V
-reports the version of \fIncurses\fP which was used in this program,
-and exits.
-The options are as follows:
+reports the version of \fIncurses\fP associated with this program and
+exits with a successful status.
 .TP
 .B \-x
-do not attempt to clear the terminal's scrollback buffer
-using the extended \*(``E3\*('' capability.
+prevents \fB\%@CLEAR@\fP from attempting to clear the scrollback buffer.
 .SH HISTORY
-A \fBclear\fP command appeared in 2.79BSD dated February 24, 1979.
-Later that was provided in Unix 8th edition (1985).
+A \fBclear\fP command using the \fItermcap\fP database and library
+appeared in 2BSD (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/clear.c
+Eighth Edition Unix (1985) later included it.
 .PP
-AT&T adapted a different BSD program (\fBtset\fP) to make
-a new command (\fBtput\fP),
-and used this to replace the \fBclear\fP command with a shell script
-which calls \fBtput clear\fP, e.g.,
+The commercial Unix arm of AT&T adapted a different BSD program
+(\fBtset\fP) to make a new command,
+\fBtput\fP,
+and replaced the \fBclear\fP program with a shell script that called
+\*(``\fBtput clear\fP\*(''.
 .PP
 .RS 4
 .EX
@@ -138,8 +141,10 @@ .SH HISTORY
 .RE
 .PP
 In 1989, when Keith Bostic revised the BSD \fBtput\fP command
-to make it similar to the AT&T \fBtput\fP,
-he added a shell script for the \fBclear\fP command:
+to make it similar to AT&T's \fBtput\fP,
+he added a \fBclear\fP shell script as well.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/\
+.\"   tput/clear.sh
 .PP
 .RS 4
 .EX
@@ -149,15 +154,14 @@ .SH HISTORY
 .PP
 The remainder of the script in each case is a copyright notice.
 .PP
-The \fIncurses\fP \fBclear\fP command began in 1995 by adapting the
-original BSD \fBclear\fP command
-(with \fIterminfo\fP, of course).
-.PP
-The \fBE3\fP extension came later:
+In 1995,
+\fIncurses\fP's \fBclear\fP began by adapting BSD's original \fBclear\fP
+command to use \fIterminfo\fP.
+The \fBE3\fP extension came later.
 .IP \(bu 4
-In June 1999, \fBxterm\fP provided an extension to the standard control
+In June 1999, \fIxterm\fP provided an extension to the standard control
 sequence for clearing the screen.
-Rather than clearing just the visible part of the screen using
+Rather than clearing only the visible with
 .IP
 .RS 8
 .EX
@@ -165,7 +169,7 @@ .SH HISTORY
 .EE
 .RE
 .IP
-one could clear the \fIscrollback\fP using
+one could clear the scrollback buffer using
 .IP
 .RS 8
 .EX
@@ -173,29 +177,32 @@ .SH HISTORY
 .EE
 .RE
 .IP
-This is documented in \fIXTerm Control Sequences\fP as a feature
-originating with \fBxterm\fP.
+\*(``XTerm Control Sequences\fP\*('' documents this feature as
+originating with \fIxterm\fP.
 .IP \(bu
-A few other terminal developers adopted the feature,
-e.g., PuTTY in 2006.
+A few other terminal emulators adopted it,
+such as PuTTY in 2006.
 .IP \(bu
 In April 2011, a Red Hat developer submitted a patch to the Linux
 kernel, modifying its console driver to do the same thing.
-The Linux change, part of the 3.0 release, did not mention \fBxterm\fP,
-although it was cited in the Red Hat bug report (#683733)
-which led to the change.
+Documentation of this change,
+appearing in Linux 3.0,
+did not mention \fIxterm\fP,
+although that program was cited in the Red Hat bug report (#683733)
+motivating the feature.
 .IP \(bu
-Again, a few other terminal developers adopted the feature.
-But the
-next relevant step was a change to the \fBclear\fP program in 2013
-to incorporate this extension.
+Subsequently,
+more terminal developers adopted the feature.
+The next relevant step was to change the \fIncurses\fP \fBclear\fP
+program in 2013 to incorporate this extension.
 .IP \(bu
-In 2013, the \fBE3\fP extension was overlooked in \fB\%@TPUT@\fP with
-the \*(``clear\*('' parameter.
-That was addressed in 2016 by reorganizing \fB\%@TPUT@\fP to share
-its logic with \fB\%@CLEAR@\fP and \fB\%@TSET@\fP.
+In 2013,
+the \fBE3\fP capability was not exercised by
+\*(``\fB\%@TPUT@ clear\fP\*(''.
+That oversight was addressed in 2016 by reorganizing \fB\%@TPUT@\fP to
+share its logic with \fB\%@CLEAR@\fP and \fB\%@TSET@\fP.
 .SH PORTABILITY
-Neither IEEE Std 1003.1/The Open  Group  Base  Specifications  Issue  7
+Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
 (POSIX.1-2008) nor X/Open Curses Issue 7 documents @TSET@ or @RESET@.
 .PP
 The latter documents \fBtput\fP,
-- 
2.30.2

signature.asc
Description: PGP signature