[groff] 08/10: [docs]: Revise register auto-increment discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a0b589e0827514e15f7a73915a009d711b3bc624
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Nov 10 22:47:15 2021 +1100

    [docs]: Revise register auto-increment discussion.
---
 doc/groff.texi  | 47 +++++++++++++++++++++++-----------------
 man/groff.7.man | 67 ++++++++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 74 insertions(+), 40 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 7846329..ebb4e5b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6726,24 +6726,33 @@ interpreted even in copy mode (@pxref{Copy Mode}).
 
 @c ---------------------------------------------------------------------
 
+@codequotebacktick on
+@codequoteundirected on
+
 @node Auto-increment, Assigning Register Formats, Interpolating Registers, 
Registers
 @subsection Auto-increment
-@cindex auto-increment
-@cindex increment, automatic
-
-Number registers can also be auto-incremented and auto-decremented.  The
-increment or decrement value can be specified with a third argument to
-the @code{nr} request.
+@cindex auto-incrementation of a register
+@cindex incrementation, automatic, of a register
+@cindex decrementation, automatic, of a register
+
+Registers can also be incremented or decremented by a configured amount
+at the time they are interpolated.  The value of the increment is
+specified with a third argument to the @code{nr} request, and a special
+interpolation syntax is used to alter and then retrieve the register's
+value.  Together, these features are called
+@dfn{auto-increment}.@footnote{A negative auto-increment can be
+considered an ``auto-decrement''.}
 
 @Defreq {nr, ident value incr}
 @cindex @code{\R}, difference to @code{nr}
-Set register @var{ident} to @var{value}; the increment for
-auto-incrementing is set to @var{incr}.  The @code{\R} escape doesn't
-support this notation.
+Set register @var{ident} to @var{value} and its auto-incrementation
+amount to to @var{incr}.  The @code{\R} escape doesn't support this
+notation.
 @endDefreq
 
-To activate auto-incrementing, the escape @code{\n} has a special syntax
-form.
+Auto-incrementation is not @emph{completely} automatic; the @code{\n}
+escape sequence never alters the value of a register.  To apply
+auto-incrementation to a register, use interpolate it with @samp{\n�}.
 
 @DefescList {\\n, +, i, }
 @DefescItem {\\n, -, i, }
@@ -6751,11 +6760,11 @@ form.
 @DefescItem {\\n, -(, id, }
 @DefescItem {\\n, +[, ident, ]}
 @DefescListEnd {\\n, -[, ident, ]}
-Before interpolating, increment or decrement @var{ident} (one-character
-name@tie{}@var{i}, two-character name @var{id}) by the auto-increment
-value as specified with the @code{nr} request (or the @code{\R} escape).
-If no auto-increment value has been specified, these syntax forms are
-identical to @code{\n}.
+Increment or decrement @var{ident} (one-character
+name@tie{}@var{i}, two-character name @var{id}) by the register's
+auto-incrementation value and then interpolate the new register value.
+If @var{ident} has no auto-incrementation value, interpolate as with
+@code{\n}.
 @endDefesc
 
 For example,
@@ -6783,15 +6792,13 @@ produces
 @cindex value, incrementing without changing the register
 To change the increment value without changing the value of a register,
 assign the register's value to itself by interpolating it, and specify
-the desired increment normally.
+the desired increment normally.  Apply an increment of @samp{0} to
+disable auto-incrementation of the register.
 
 @Example
 .nr a \na 10
 @endExample
 
-@codequotebacktick on
-@codequoteundirected on
-
 @c ---------------------------------------------------------------------
 
 @node Assigning Register Formats, Built-in Registers, Auto-increment, Registers
diff --git a/man/groff.7.man b/man/groff.7.man
index e5afa71..41f111c 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4429,39 +4429,66 @@ and aliasing
 .SH Registers
 .\" ====================================================================
 .
-Registers are variables that store a value.
-.
-In groff,
-most registers store numerical values
+Most registers store numerical values
 (see section \[lq]Numerical Expressions\[rq] above),
-but some can also hold a string value.
+but some
+(predefined,
+read-only ones)
+interpolate text.
 .
+Each register has a name.
 .
-.P
-Each register is given a name.
-Arbitrary registers can be defined and set with the
+A register is defined and assigned with the
 .request .nr
-request.
+request or the
+.esc R
+escape sequence;
+its value is interpolated with the
+.esc n
+escape sequence.
 .
 .
 .P
-The value stored in a register can be retrieved by the escape sequences
-introduced by
-.esc n .
+Registers can also be incremented or decremented by a configured amount
+at the time they are interpolated.
+.
+The value of the increment is specified with a third argument to the
+.request .nr
+request,
+and a special interpolation syntax,
+.BI \[rs]n \[+-]
+is used to alter and then retrieve
+the register's value.
+.
+Together,
+these features are called
+.IR auto-increment .
+.
+(A negative auto-increment can be
+considered an \[lq]auto-decrement\[rq].)
 .
 .
 .P
-Most useful are predefined registers.
+Many predefined registers are available.
 .
-In the following the notation
+In the following presentation,
+the register interpolation syntax
+.BI \[rs]n[ name ]
+is used to refer to a register
 .I name
-is used to refer to
-.register name
-to make clear that we speak about registers.
+to clearly distinguish it from a string or request
+.IR name .
 .
-Please keep in mind that the
-.esc[] n ""
-decoration is not part of the register name.
+The register name space is separate from that used for requests,
+macros,
+strings,
+and diversions.
+.
+Bear in mind that the symbols
+.B \[rs]n[]
+are
+.I not
+part of the register name.
 .
 .
 .\" ====================================================================