[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 04/10: doc/groff.texi: Update register format discussion.
From: |
G. Branden Robinson |
Subject: |
[groff] 04/10: doc/groff.texi: Update register format discussion. |
Date: |
Sat, 30 Oct 2021 19:26:33 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 04/10: doc/groff.texi: Update register format discussion.,
G. Branden Robinson <=