gbranden pushed a commit to branch master
in repository groff.
commit da3fe510205d4a276bc77a9c9948d0d075385bd1
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Sun Jun 22 23:08:47 2025 -0500
doc/*,man/*: Document `length` request pitfall.
Fixes <https://savannah.gnu.org/bugs/?67231>.
Also fix incorrect metasyntactic variable reference.
Also sync input line breaks between our Texinfo manual and groff_diff(7).
---
ChangeLog | 8 ++++++++
doc/groff.texi.in | 36 +++++++++++++++++++++++++++++++++---
man/groff_diff.7.man | 32 +++++++++++++++++++++++++++++++-
3 files changed, 72 insertions(+), 4 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index aba828805..d03a9879c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2025-06-22 G. Branden Robinson <g.branden.robin...@gmail.com>
+
+ * doc/groff.texi.in (Strings) <length>:
+ * man/groff_diff.7.man (New requests) <length>: Document
+ pitfall.
+
+ Fixes <https://savannah.gnu.org/bugs/?67231>.
+
2025-06-21 G. Branden Robinson <g.branden.robin...@gmail.com>
* doc/GMPfront.t.in: Rename this...
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 4be413467..3afb4d33d 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -13373,15 +13373,23 @@ can be manipulated through renaming, removal, and
aliasing (@code{rn},
@cindex @code{length} request, and copy mode
@cindex copy mode, and @code{length} request
@cindex mode, copy, and @code{length} request
-Compute the number of characters in @var{contents} and store the count
-in the register @var{reg}. If @var{reg} doesn't exist, it is created.
+Compute the number of characters in
+@var{contents}
+and store the count in the register
+@var{reg}.
+If
+@var{reg}
+doesn't exist,
+GNU
+@command{troff} @c GNU
+creates it.
GNU
@command{troff} @c GNU
removes a leading neutral double quote
@samp{"}
from
-@var{length},
+@var{contents},
permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
@xref{Copy Mode}.
@@ -13403,6 +13411,28 @@ character.
See the discussion of the
@code{ds}
request above.
+
+@strong{Caution:@:}
+If you interpolate a macro or diversion in
+@var{contents}
+(@pxref{Punning Names}),
+the
+@code{length}
+request counts characters
+(or nodes)
+only up to the first newline,
+and leaves the rest on the input stream.
+In conventional circumstances,
+that means the remainder is interpreted,
+and may be formatted.
+To discover the length of any
+string,
+macro,
+or diversion,
+use the
+@code{pm}
+request.
+@xref{Debugging}.
@endDefreq
@Defreq {chop, object}
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index a9c73a51f..247f95a64 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3243,7 +3243,37 @@ and store the count in the register
If
.I reg
doesn't exist,
-it is created.
+GNU
+.I troff \" GNU
+creates it.
+.
+.
+.IP
+.I Caution:
+If you interpolate a macro or diversion in
+.I contents
+(see section \[lq]Punning Names\[rq] in
+.MR groff @MAN7EXT@ ),
+the
+.B length
+request counts characters
+(or nodes)
+only up to the first newline,
+and leaves the rest on the input stream.
+.
+In conventional circumstances,
+that means the remainder is interpreted,
+and may be formatted.
+.
+To discover the length of any
+string,
+macro,
+or diversion,
+use the
+.B pm
+request.
+.
+See section \[lq]Debugging\[rq] below.
.
.
.TP
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
