[groff] 06/08: [docs]: Revise .color, .cp, .linetabs, .vpt.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 717d574052557e6a28befe28bfd990f2a599fa18
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Feb 3 22:36:58 2024 -0600

    [docs]: Revise .color, .cp, .linetabs, .vpt.
    
    * doc/groff.texi (Tabs and Fields): Notate argument to `linetabs`
      request as optional.
    * man/groff.7.man (Request short reference) <linetabs>:
    * man/groff_diff.7.man (New requests) <linetabs>: Clarify that line-tabs
      activation is on a per-environment basis.
    
    * man/groff.7.man (Request short reference) <linetabs, vpt>: Document
      that the argument can be any integer, not just zero.
    
    Recast generally.
---
 doc/groff.texi       | 59 ++++++++++++++++++++++++++--------------------------
 man/groff.7.man      | 44 +++++++++++++++++++++++++++------------
 man/groff_diff.7.man | 51 +++++++++++++++++++++++++++------------------
 3 files changed, 92 insertions(+), 62 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 8d2e7c1c5..b39181d48 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9377,16 +9377,16 @@ character is associated with the environment 
(@pxref{Environments}).
 Only a single character of @var{c} is recognized; any excess is ignored.
 @endDefreq
 
-@DefreqList {linetabs, n}
+@DefreqList {linetabs, [@Var{b}]}
 @DefregListEndx {.linetabs}
 @cindex tab, line-tabs mode
 @cindex line-tabs mode
 @cindex mode, line-tabs
-If @var{n} is missing or non-zero, activate @dfn{line-tabs}; deactivate
-it otherwise (the default).  Active line-tabs cause GNU @code{troff}
-to compute tab distances relative to the start of the output line
-rather than relative to the horizontal drawing position corresponding to
-the start of the input line.
+Activate line-tabs in the environment if the expression @var{b} is
+non-zero; deactivate them otherwise.  They are inactive by default, and
+activated if @var{b} is omitted.  When line-tabs are active, tab stops
+are computed relative to the start of the pending output line instead of
+the drawing position corresponding to the start of the input line.
 
 @Example
 .ta 1i 3i
@@ -9403,9 +9403,8 @@ c
     @result{} a         b                   c
 @endExample
 
-Line-tabs activation is associated with the environment
-(@pxref{Environments}).  The read-only register @code{.linetabs}
-interpolates@tie{}1 if line-tabs are active, and 0 otherwise.
+The read-only register @code{.linetabs} interpolates@tie{}1 if line-tabs
+are active, and 0 otherwise.
 @endDefreq
 
 @menu
@@ -12322,15 +12321,16 @@ rules (lines), and geometric objects like circles and 
polygons are
 drawn, and the @dfn{fill color}, which can be used to paint the interior
 of a closed geometric figure.
 
-@DefreqList {color, [@Var{n}]}
+@DefreqList {color, [@Var{b}]}
 @DefregListEndx {.color}
-If @var{n} is missing or non-zero, enable the output of color-related
-device-independent output commands (this is the default); otherwise,
-disable them.  This request sets a global flag; it does not produce an
+Enable output of color-related device-independent output commands if the
+expression @var{b} is non-zero; disable it otherwise.  It is enabled by
+default, and if @var{b} is omitted.  This request modifies the
+formatter's internal state; it does not produce a
 token (@pxref{Gtroff Internals}).
 
-The read-only register @code{.color} is@tie{}1 if colors are enabled,
-0@tie{}otherwise.
+The read-only register @code{.color} interpolates@tie{}1 if color
+support is enabled, 0@tie{}otherwise.
 
 Color can also be disabled with the @option{-c} command-line option.
 @endDefreq
@@ -14662,17 +14662,16 @@ a certain location on the output page or in a 
diversion.  Its
 applications include setting page headers and footers, body text in
 multiple columns, and footnotes.
 
-@DefreqList {vpt, [@Var{flag}]}
+@DefreqList {vpt, [@Var{b}]}
 @DefregListEndx {.vpt}
 @cindex enabling vertical position traps (@code{vpt})
 @cindex vertical position traps, enabling (@code{vpt})
 @cindex vertical position trap enable register (@code{.vpt})
-Enable vertical position traps if @var{flag} is non-zero or absent;
-disable them otherwise.  Vertical position traps are those set by the
-@code{wh} request or by @code{dt} within a diversion.  The parameter
-that controls whether vertical position traps are enabled is global.
-Initially, vertical position traps are enabled.  The current value is
-stored in the @code{.vpt} read-only register.
+Enable vertical position traps if the expression @var{b} is non-zero;
+disable them otherwise.  They are enabled by default, and if @var{b} is
+omitted.  Vertical position traps are those set by the @code{wh} request
+or by @code{dt} within a diversion.  Vertical position trap enablement
+is global.  Its status is stored in the @code{.vpt} read-only register.
 
 @cindex page break, prevented by @code{vpt}
 @cindex break, page, prevented by @code{vpt}
@@ -17479,16 +17478,18 @@ respectively, named @samp{[}.  In GNU @code{troff}, 
however, the
 compatibility mode, GNU @code{troff} interprets names in the traditional
 way; they thus can be two characters long at most.
 
-@DefreqList {cp, [@Var{n}]}
+@DefreqList {cp, [@Var{b}]}
 @DefregListEndx {.C}
-If @var{n} is missing or non-zero, turn on compatibility mode;
-otherwise, turn it off.
+Enable AT&T @command{troff} compatibility mode if the expression
+@var{b} is non-zero; disable it otherwise.  It is disabled by default,
+and enabled if @var{b} is omitted.  In compatibility mode, long names
+are not recognized, and the incompatibilities they cause do not arise.
 
-The read-only register @code{.C} is@tie{}1 if compatibility mode is on,
-0@tie{}otherwise.
+The read-only register @code{.C} interpolates@tie{}1 if compatibility
+mode is enabled, 0@tie{}otherwise.
 
-Compatibility mode can be also turned on with the @option{-C}
-command-line option.
+Compatibility mode is also enabled by the @option{-C} command-line
+option.
 @endDefreq
 
 @DefreqList {do, name}
diff --git a/man/groff.7.man b/man/groff.7.man
index 48d77631c..0028e054a 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2809,15 +2809,16 @@ requests.
 .REQ .color
 Enable output of color-related device-independent output commands.
 .
+It is enabled by default.
+.
 .TPx
-.REQ .color n
+.REQ .color b
 If
-.I n
+.I b
 is zero,
 disable output of color-related device-independent output commands;
 otherwise,
 enable them.
-.\" XXX: Should probably interpret negative values as false.
 .
 .TPx
 .REQ .composite "c1 c2"
@@ -2837,14 +2838,20 @@ loop.
 .
 .TPx
 .REQ .cp
-Enable compatibility mode.
+Enable AT&T
+.I troff \" AT&T
+compatibility mode.
+.
+It is disabled by default.
 .
 .TPx
-.REQ .cp n
+.REQ .cp b
 If
-.I n
+.I b
 is zero,
-disable compatibility mode,
+disable AT&T
+.I troff \" AT&T
+compatibility mode,
 otherwise enable it.
 .
 .TPx
@@ -3573,12 +3580,17 @@ in the register
 .
 .TPx
 .REQ .linetabs
-Enable line-tabs mode
-(calculate tab positions relative to beginning of output line).
+Activate line-tabs in the environment.
+.
+It is disabled by default.
 .
 .TPx
-.REQ .linetabs\~0
-Disable line-tabs mode.
+.REQ .linetabs b
+If
+.I b
+is zero,
+deactivate line-tabs in the environment,
+otherwise enable them.
 .
 .TPx
 .REQ .lf n
@@ -4561,9 +4573,15 @@ preserving font information.
 .REQ .vpt
 Enable vertical position traps.
 .
+They are enabled by default.
+.
 .TPx
-.REQ .vpt\~0
-Disable vertical position traps.
+.REQ .vpt b
+If
+.I b
+is zero,
+disable vertical position traps,
+otherwise enable them.
 .
 .TPx
 .REQ .vs
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 1bc8cb788..27e9e7eaf 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2122,24 +2122,29 @@ See
 .
 .TP
 .BR .color\~ [\c
-.IR n ]
+.IR b ]
 If
-.I n
+.I b
 is non-zero or missing,
-enable colors
-(the default),
+enable output of color-related device-independent output commands,
 otherwise disable them.
 .
+It is enabled by default.
+.
 .
 .TP
 .BR .cp\~ [\c
-.IR n ]
+.IR b ]
 If
-.I n
+.I b
 is non-zero or missing,
-enable compatibility mode,
+enable AT&T
+.I troff \" AT&T
+compatibility mode,
 otherwise disable it.
 .
+It is disabled by default.
+.
 In compatibility mode,
 long names are not recognized,
 and the incompatibilities they cause do not arise.
@@ -2964,21 +2969,21 @@ is read in copy mode.
 .
 .
 .TP
-.BI .linetabs\~ n
+.BR .linetabs\~ [\c
+.IR b ]
 If
-.I n
+.I b
 is non-zero or missing,
-enable line-tabs mode,
-otherwise disable it
-(the default).
+activate line-tabs in the environment,
+otherwise disable it.
+.
+They are inactive by default.
 .
-In this mode,
-tab stops are computed relative to the start of the pending output line,
+When line-tabs are active,
+tab stops are computed relative to the start of the pending output line
 instead of the drawing position corresponding to the start of the input
 line.
 .
-Line-tabs mode is a property of the environment.
-.
 .
 .TP
 .BR .lsm\~ [\c
@@ -3689,14 +3694,18 @@ is retained.
 .
 .
 .TP
-.BI .vpt\~ n
+.BR .vpt\~ [\c
+.IR b ]
 If
-.I n
+.I b
 is non-zero or missing,
-enable vertical position traps
-(the default),
+enable vertical position traps,
 otherwise disable them.
 .
+They are enabled by default.
+.
+.
+.IP
 Vertical position traps are those set by the
 .BR ch ,
 .BR wh ,
@@ -3704,6 +3713,8 @@ and
 .B dt
 requests.
 .
+Vertical position trap enablement is global.
+.
 .
 .TP
 .BR .warn\~ [\c