[PATCH 4/9] man/clear.1: Migrate macro usage conventions.

[G. Branden Robinson]

* Drop page-local `NS` and `NE` macro definitions in favor of more
  widely used `EX` and `EE` macros.

  groff_man(7):

       .EX
       .EE    Begin and end example.  After .EX, filling is disabled and
              a constant‐width (monospaced) font is selected.  Calling
              .EE enables filling and restores the previous font.

              These macros are extensions introduced in Ninth Edition
              Unix.  Systems running that troff, or those from
              Documenter’s Workbench, Heirloom Doctools, or Plan 9 troff
              support them.  To be certain your page will be portable to
              systems that do not, copy their definitions from the
              an-ext.tmac file of a groff installation.

  Also use `PP` and `IP` to achieve the vertical separation formerly
  implied by `NS`, and `RS`/`RE` to manage horizontal position performed
  by `NS` and `NE`.

* Drop page-local `bP` macro in favor of ".IP \(bu 4" on the first
  occurrence, and ".IP \(bu" on subsequent ones.

  groff_man(7):

   Horizontal and vertical spacing
       The indentation argument accepted by .IP, .TP, and the deprecated
       .HP is a number plus an optional scaling unit, as is .RS’s inset‐
       amount.  If no scaling unit is given, the man package assumes
       “n”.  An indentation specified in a call to .IP, .TP, or the
       deprecated .HP persists until (1) another of these macros is
       called with an indentation argument, or (2) .SH, .SS, or .P or
       its synonyms is called; these clear the indentation entirely.

No difference in formatted output per the following procedure.

groff -dAD=l -rHY=0 -man -Tutf8 -P -cbou man/clear.1 >| clear.old
[apply this patch]
groff -dAD=l -rHY=0 -man -Tutf8 -P -cbou man/clear.1 >| clear.new
diff -u clear.{old,new}
---
 man/clear.1 | 84 +++++++++++++++++++++++++++++++++--------------------
 1 file changed, 53 insertions(+), 31 deletions(-)

diff --git a/man/clear.1 b/man/clear.1
index bd561d88..5fc54a15 100644
--- a/man/clear.1
+++ b/man/clear.1
@@ -34,22 +34,36 @@
 .ie \n(.g .ds CW CR
 .el       .ds CW CW
 .\}
-.\" these would be fallbacks for DS/DE,
-.\" but groff changed the meaning of the macros.
-.de NS
-.ie n  .sp
-.el    .sp .5
-.ie n  .in +4
-.el    .in +2
-.nf
-.ft \*(CW
+.
+.nr mE 0 \" in an example (EX/EE)?
+.
+.\" Start example.
+.if !\n(.g \{\
+.de EX
+.  br
+.  if !\\n(mE \{\
+.    nr mF \\n(.f
+.    nr mP \\n(PD
+.    nr PD 1v
+.    nf
+.    ft \\*(CW
+.    nr mE 1
+.  \}
 ..
-.de NE
-.fi
-.ft R
-.ie n  .in -4
-.el    .in -2
+.\}
+.
+.\" End example.
+.if !\n(.g \{\
+.de EE
+.  br
+.  if \\n(mE \{\
+.    ft \\n(mF
+.    nr PD \\n(mP
+.    fi
+.    nr mE 0
+.  \}
 ..
+.\}
 .
 .ie \n(.g \{\
 .ds `` \(lq
@@ -65,10 +79,6 @@
 .el   .ds '  '
 .\}
 .
-.de bP
-.ie n  .IP \(bu 4
-.el    .IP \(bu 2
-..
 .ds n 5
 .SH NAME
 \fB\%@CLEAR@\fP \-
@@ -113,17 +123,23 @@ .SH HISTORY
 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.,
-.NS
+.PP
+.RS 4
+.EX
 /usr/bin/tput ${1:+\-T$1} clear 2> /dev/null
 exit
-.NE
+.EE
+.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:
-.NS
+.PP
+.RS 4
+.EX
 exec tput clear
-.NE
+.EE
+.RE
 .PP
 The remainder of the script in each case is a copyright notice.
 .PP
@@ -131,35 +147,41 @@ .SH HISTORY
 BSD \fBclear\fP command (with terminfo, of course).
 .PP
 The \fBE3\fP extension came later:
-.bP
+.IP \(bu 4
 In June 1999, \fBxterm\fP provided an extension to the standard control
 sequence for clearing the screen.
 Rather than clearing just the visible part of the screen using
-.NS
+.IP
+.RS 8
+.EX
 printf \*'\e033[2J\*'
-.NE
+.EE
+.RE
 .IP
 one could clear the \fIscrollback\fP using
-.NS
+.IP
+.RS 8
+.EX
 printf \*'\e033[\fB3\fPJ\*'
-.NE
+.EE
+.RE
 .IP
 This is documented in \fIXTerm Control Sequences\fP as a feature originating
 with \fBxterm\fP.
-.bP
+.IP \(bu
 A few other terminal developers adopted the feature, e.g., PuTTY in 2006.
-.bP
+.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.
-.bP
+.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.
-.bP
+.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
-- 
2.30.2

signature.asc
Description: PGP signature