gbranden pushed a commit to branch master
in repository groff.
commit 7ffd75ebd27fed200141cc17b825a215f23ace2a
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat May 10 08:50:37 2025 -0500
doc/*,man/*: Correct `pm` request description.
The `pm` request does not, as a matter of fact, report the "sizes" of
macros, strings, and diversions "in bytes". That claim is true only of
"pure" macros and strings that contain only character sequences, and
even then only to the extent that we ignore other properties of macros
and strings besides what is internally referred to as their "contents".
(All such properties are now visible using the `.pm name` syntax.)
The traditional description of this GNU troff macro was thus misleading
in two ways.
1. It undercounted the actual storage requirement--which is what we
tend to measure in bytes--of even the simplest of these objects,
such as empty macro definitions or one-character string definitions.
(It came closest to telling the truth about the built-in `.T`
string, which has no file name or line number data to track; but
even it has a node list; see next item.)
2. It was wildly inaccurate for diversions in general. GNU troff
represents a diversion internally as a "node list". A node list is
a linked list, and even a singly-linked list stores a pointer with
every node. A "node" is itself an object in a class hierarchy in
GNU troff, and these classes vary widely in their own storage
requirements, which the program does not attempt to measure, let
alone report. Further, GNU troff always maintains both a "contents"
datum and a "node list" for every macro, string, and diversion. The
presence of a node is marked by a null character in the "contents"
groff string, which is a sequence of bytes. Because macros,
strings, and diversions are interchangeable ("punnable") in some
contexts, all have both "contents" and a "node list", even though
the node list of a macro or string is usually empty.
It seems more useful to document the truth than to change how `pm`
works; I expect few groff users concern themselves with the storage
requirements of their documents' strings, macros, and diversions at the
granularity of an individual byte. What is likely of more interest is
the length of the list of objects (nodes or characters) the string,
macro, or diversion contains. The elements of this list are what get
counted by the `length` request, removed by the `chop` request, and
transformed by the `asciify` and `unformat` requests.
In the future, if/when we implement an iterator for these objects, the
aforementioned elements will be the unit of iteration. See
<https://savannah.gnu.org/bugs/?62264>.
---
doc/groff.texi.in | 4 ++--
man/groff.7.man | 2 +-
man/groff_diff.7.man | 2 +-
3 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index ff19dcbe7..5cab00eee 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -18129,7 +18129,7 @@ or,
without arguments,
the names of all defined macros,
strings,
-and diversions and their sizes in bytes.
+and diversions and their lengths in characters or nodes.
@endDefreq
@Defreq {pnr, [@Var{reg} @r{@dots{}}]}
@@ -18988,7 +18988,7 @@ and an argument reduces the report to a sum of the
above in the same
units.
GNU
@command{troff} @c GNU
-reports the sizes in bytes if given no arguments,
+reports ther lengths in characters or nodes if given no arguments,
and otherwise dumps
the @acronym{JSON}-encoded name and contents of each named argument.
diff --git a/man/groff.7.man b/man/groff.7.man
index 7ce28e669..78d8aa200 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4263,7 +4263,7 @@ Report,
to the standard error stream,
the names of all defined macros,
strings,
-and diversions and their sizes in bytes.
+and diversions and their lengths in characters or nodes.
.
.TPx
.REQ .pm "name \fR\&.\|.\|.\&\fP"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 9a60c80bf..a245058d4 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -6448,7 +6448,7 @@ units.
.
GNU
.I troff \" GNU
-reports the sizes in bytes if given no arguments,
+reports their lengths in characters or nodes if given no arguments,
and otherwise dumps
the JSON-encoded name and contents of each named argument.
.
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
