[groff] 04/10: doc/groff.texi: Update register format discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 24a0ea01af8d0a0d9f6fd8c2d1cd25c186ec431e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Oct 29 13:48:07 2021 +1100

    doc/groff.texi: Update register format discussion.
    
    * Rename subsection/node from "Assigning Formats" to "Assigning
      Register Formats".
    * Recast subsection introduction.  Note applications of non-default
      formats.
    * Consistently refer to the default register interpolation format as
      "Arabic [number] format" and Arabic numerals as such (cf. "Roman
      numerals".  Drop usage of "decimal", an inapposite classification
      given that non-Arabic formats don't employ a place-value system.
    * Explicitly discuss handling of nonpositive values.
    * Note that assigning a format to a nonexistent register creates it.
    * Note that interpolating the format a nonexistent register doesn't
      create it.
    * Enrich example: illustrate use of alternative Arabic numerals in
      format assignments and handling of negative values.
    * Speak more precisely about handling of Roman formats.  Fix erroneously
      ordered reference to Unicode code points.
    * Say "numeral" instead of "number" in appropriate contexts.
    * Condense the two Arabic list items into one.
    * Stop hyphenating "uppercase" and "lowercase".
---
 doc/groff.texi | 119 +++++++++++++++++++++++++++++----------------------------
 1 file changed, 60 insertions(+), 59 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index d00264e..7a8dfdf 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -5725,8 +5725,8 @@ Return@tie{}1 if @var{anything} is a valid numeric 
expression; or@tie{}0
 if @var{anything} is empty or not a valid numeric expression.
 @endDefesc
 
-Registers interpolated in expressions must be in a decimal format if
-used as operands to an arithmetic operator; @xref{Assigning Formats}.
+A register interpolation used as an operand in an expression must have
+an Arabic format; @xref{Assigning Register Formats}.
 @cindex space characters, in expressions
 @cindex expressions, and space characters
 Due to the way arguments are parsed, spaces are not allowed in
@@ -6457,7 +6457,7 @@ details of formatting parameters.
 * Setting Registers::
 * Interpolating Registers::
 * Auto-increment::
-* Assigning Formats::
+* Assigning Register Formats::
 * Built-in Registers::
 @end menu
 
@@ -6657,7 +6657,7 @@ assignments) are possible.
 
 @c ---------------------------------------------------------------------
 
-@node Auto-increment, Assigning Formats, Interpolating Registers, Registers
+@node Auto-increment, Assigning Register Formats, Interpolating Registers, 
Registers
 @subsection Auto-increment
 @cindex auto-increment
 @cindex increment, automatic
@@ -6725,82 +6725,84 @@ the desired increment normally.
 
 @c ---------------------------------------------------------------------
 
-@node Assigning Formats, Built-in Registers, Auto-increment, Registers
-@subsection Assigning Formats
+@node Assigning Register Formats, Built-in Registers, Auto-increment, Registers
+@subsection Assigning Register Formats
 @cindex assigning formats (@code{af})
 @cindex formats, assigning (@code{af})
 
-When a (writable) register is interpolated, its value is replaced with a
-representation of a number.  A variety of formats are available.
+A writable register's value can be interpolated in several number
+formats.  By default, conventional Arabic numerals are used.
+Other formats see use in sectioning and outlining schemes and
+alternative page numbering arrangements.
 
-@Defreq {af, reg format}
-Set the format used to interpolate a register.  The first argument
-@var{reg} is the name of the register to be affected, and the second
-argument @var{format} is the format.  Valid formats are as follows.
+@Defreq {af, reg fmt}
+Use number format @var{fmt} when interpolating register @var{reg}.
+Valid number formats are as follows.
 
 @table @code
-@item 0
-Decimal Arabic numbers 0, 1, 2, 3,@tie{}@enddots{}  This is the default
-format.
-
-@item 0@dots{}0
-Decimal Arabic numbers zero-padded on the left if necessary to at least
-as many digits as specified (interpolations never truncate a register
-value).  @samp{00} would interpolate register values as 01, 02,
-03,@tie{}@enddots{}
-
-Any decimal digit is equivalent to @samp{0}; GNU @code{troff} simply
-counts the digits specified.  Zeroes represent decimal Arabic formats
-when the @code{\g} escape sequence is used; see below.
+@item 0@r{@dots{}}
+Arabic numerals 0, 1, 2, and so on.
+Any decimal digit is equivalent to @samp{0}; the formatter merely counts
+the digits specified.  Multiple Arabic numerals in @var{fmt} cause
+interpolations to be zero-padded on the left if necessary to at least as
+many digits as specified (interpolations never truncate a register
+value).  A register with format @samp{00} interpolates values 1, 2, 3 as
+@samp{01}, @samp{02}, @samp{03}.  The default format for all writable
+registers is @samp{0}.
 
 @item I
 @cindex Roman numerals
 @cindex numerals, Roman
-Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
+Uppercase Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
 
 @item i
-Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
+Lowercase Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
 
 @item A
-Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
+Uppercase letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
 
 @item a
-Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
+Lowercase letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
 @end table
 
-Omitting the register format causes a warning of type @samp{missing};
-@xref{Debugging}.  Specifying a nonexistent format is an error.
+Omitting @var{fmt} causes a warning of type @samp{missing}; see
+@ref{Debugging}.  Specifying an unrecognized format is an error.
+
+Zero values are interpolated as @samp{0} in non-Arabic formats.
+Negative quantities are prefixed with @samp{-} irrespective of format.
+In Arabic formats, the sign supplements the field width.  If @var{reg}
+doesn't exist, it is created with a zero value.
 
 @Example
 .nr a 10
-.af a 1           \" the default format
+.af a 0           \" the default format
 \na,
 .af a I
 \na,
-.af a a
+.af a 321
+.nr a (-\na)
 \na,
-.af a 001
+.af a a
 \na
-    @result{} 10, X, j, 010
+    @result{} 10, X, -010, -j
 @endExample
 
-@cindex Roman numerals, maximum and minimum
-@cindex maximum values of Roman numerals
-@cindex minimum values of Roman numerals
-The largest number representable for the @samp{i} and @samp{I} formats
-is 39999 (or @minus{}39999); @acronym{AT&T} @code{troff} uses @samp{z}
-and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
-GNU @code{troff}.  Currently, the correct glyphs of Roman numeral five
-thousand and Roman numeral ten thousand (Unicode code points
-@code{U+2182} and @code{U+2181}, respectively) are not used.
-
-If @var{reg} doesn't exist, it is created and assigned a zero value.
+@cindex Roman numerals, extrema (maximum and minimum)
+@cindex extreme values representable with Roman numerals
+@cindex maximum value representable with Roman numerals
+@cindex minimum value representable with Roman numerals
+The representable extrema in the @samp{i} and @samp{I} formats
+correspond to Arabic �39,999.  GNU @code{troff} uses @samp{w} and
+@samp{z} to represent 5,000 and 10,000 in Roman numerals, respectively,
+following the convention of @acronym{AT&T} @code{troff}---currently, the
+correct glyphs for Roman numerals five thousand (@code{U+2181}) and ten
+thousand (@code{U+2182}) are not used.
 
 @cindex read-only register, changing format
 @cindex changing format, and read-only registers
-Assigning the format of a read-only register is an error.  It is
-necessary to copy the read-only register's value to, and assign a format
-to, a writable register.
+Assigning the format of a read-only register is an error.  Instead, copy
+the read-only register's value to, and assign the format of, a writable
+register.
 @endDefreq
 
 @DefescList {\\g, , r, }
@@ -6809,19 +6811,18 @@ to, a writable register.
 @cindex format of register (@code{\g})
 @cindex register, format (@code{\g})
 Interpolate the format of the register @var{reg} (one-character
-name@tie{}@var{r}, two-character name @var{rg}).  If the register is not
-defined, nothing is interpolated.
-
-@samp{\ga} after the previous example would interpolate @samp{000}.
+name@tie{}@var{r}, two-character name @var{rg}).  Zeroes represent
+Arabic formats.  If @var{reg} is not defined, @var{reg} is not created
+and nothing is interpolated.
 @endDefesc
 
 @cindex register format, in expressions
 @cindex expressions, and register format
-GNU @code{troff}'s input parser understands only decimal Arabic formats
-(including leading zeroes).  The Roman or alphabetic formats cannot be
-used as operands to arithmetic operators in expressions
-(@pxref{Expressions}).  For instance, it may be desirable to test the
-page number independently of its format.
+GNU @code{troff}'s input parser understands only Arabic numerals.  The
+Roman numeral or alphabetic formats cannot be used as operands to
+arithmetic operators in expressions (@pxref{Expressions}).  For
+instance, it may be desirable to test the page number independently of
+its format.
 
 @Example
 .af % i \" front matter
@@ -6843,7 +6844,7 @@ page number independently of its format.
 
 @c ---------------------------------------------------------------------
 
-@node Built-in Registers,  , Assigning Formats, Registers
+@node Built-in Registers,  , Assigning Register Formats, Registers
 @subsection Built-in Registers
 @cindex built-in registers
 @cindex registers, built-in