gbranden pushed a commit to branch master
in repository groff.
commit 03198e3eec2078539962144e03644b6fecd95733
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Mar 22 16:10:26 2026 -0500
[doc,man]: Revise `substring` request description.
* doc/groff.texi.in (Strings):
* man/groff.7.man (Request short reference):
* man/groff_diff.7.man (New requests): Refer to components of a string
as "elements" instead of "characters". While true in one sense, it's
misleading in another, and may become more so as GNU troff is
refactored to use Unicode internally. Specifically, strings can
already contain byte values that are invalid as input to the program;
the program uses them to represent tokens that input processing in
diverse respects. See "src/roff/troff/input.h".
* doc/groff.texi.in (Strings):
* man/groff_diff.7.man (New requests): Recast description of behavior
when the optional third argument is omitted. Document long-standing
fact that compatibility save and restore tokens, a concept introduced
in the `ds` request description, do not count for the purpose of
element index computation.
* doc/groff.texi.in (Strings): Break input lines in a roff-friendly way.
---
doc/groff.texi.in | 37 ++++++++++++++++++++++++++++++-------
man/groff.7.man | 2 ++
man/groff_diff.7.man | 32 ++++++++++++++++++++++++--------
3 files changed, 56 insertions(+), 15 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index e50d8b301..ed02ea864 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -15378,13 +15378,22 @@ for details on nodes inserted additionally by GNU
@code{troff}.
@Defreq {substring, str start [@Var{end}]}
@cindex substring (@code{substring})
-Replace the string named @var{str} with its substring bounded by the
-indices @var{start} and @var{end}, inclusively. The first character in
-the string has index@tie{}0. If @var{end} is omitted, it is implicitly
-set to the largest valid value (the string length minus one). Negative
-indices count backward from the end of the string:@: the last character
-has index@tie{}@minus{}1, the character before the last has
-index@tie{}@minus{}2, and so on.
+Replace the string named
+@var{str}
+with its substring bounded by the indices
+@var{start}
+and
+@var{end},
+inclusively.
+The first element of the string has index@tie{}0.
+An absent
+@var{end}
+argument implies the largest valid value
+(the string length minus one).
+Negative indices count backward from the end of the string:@:
+the last element has index@tie{}@minus{}1,
+the element before the last has index@tie{}@minus{}2,
+and so on.
@Example
.ds xxx abcdefgh
@@ -15397,6 +15406,20 @@ index@tie{}@minus{}2, and so on.
@endExample
@endDefreq
+Compatibility save and restore tokens do
+@emph{not}
+count for the purpose of index computation,
+even though they appear in string contents reported by the
+@code{pm}
+request and figure in the value computed by the
+@code{length}
+request.
+@c XXX: You can actually do the following, inadvisedly.
+@c Consequently,
+@c @code{substring}
+@c cannot be used to alter the compatibility mode associations
+@c of its elements.
+
@DefreqList {stringdown, str}
@DefreqListEndx {stringup, str}
@cindex case-transforming a string (@code{stringdown}, @code{stringup})
diff --git a/man/groff.7.man b/man/groff.7.man
index fae1fcffc..844ea7c04 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5192,6 +5192,8 @@ and
.IR end ,
inclusive.
.
+The first element of the string has index\~0.
+.
Negative indices count backward from the end of the string.
.
.TPx
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 2b3405cb1..a1f07c71e 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4462,18 +4462,34 @@ and
.IR end ,
inclusively.
.
-The first character in the string has index\~0.
+The first element of the string has index\~0.
+.
+An absent
+.I end
+argument implies the largest valid value
+(the string length minus one).
.
Negative indices count backward from the end of the string:
-the last character has index\~\-1,
-the character before the last has index\~\-2,
+the last element has index\~\-1,
+the element before the last has index\~\-2,
and so on.
.
-If
-.I end
-is omitted,
-.B \-1
-is implied.
+.
+.
+.IP
+Compatibility save and restore tokens do
+.I not
+count for the purpose of index computation,
+even though they appear in string contents reported by the
+.B pm
+request and figure in the value computed by the
+.RB \[lq] length \[rq]
+request.
+.\" XXX: You can actually do the following, inadvisedly.
+.\" Consequently,
+.\" .B \%substring
+.\" cannot be used to alter the compatibility mode associations
+.\" of its elements.
.
.
.TP
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
