[groff] 04/08: Update documentation of .pm request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 964c4bc9dcc282d70ef85975fb8fe65982de03f3
Author: G. Branden Robinson <address@hidden>
AuthorDate: Tue May 5 06:34:59 2020 +1000

    Update documentation of .pm request.
    
    groff(7) was just plain wrong, documenting classical behavior instead
    (and omitting mention of strings and diversions).  Correct it.
    
    groff_diff(7) now documents the difference between AT&T troff and
    groff.
    
    The Texinfo manual was accurate but did not mention the implementation
    difference in the relevant section.  I moved it and recast some wording.
---
 doc/groff.texi       | 18 +++++++++---------
 man/groff.7.man      | 13 ++++++++-----
 man/groff_diff.7.man | 18 ++++++++++++++++++
 3 files changed, 35 insertions(+), 14 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 75b08a5..0503a89 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14002,15 +14002,10 @@ defined environments (both named and numbered) on 
@code{stderr}.
 @Defreq {pm, }
 @cindex dumping symbol table (@code{pm})
 @cindex symbol table, dumping (@code{pm})
-Print the entire symbol table on @code{stderr}.  Names of all defined
-macros, strings, and diversions are print together with their size in
-bytes.  Since @code{gtroff} sometimes adds nodes by itself, the returned
-size can be larger than expected.
-
-This request differs from Unix @code{troff}: @code{gtroff} reports the
-sizes of diversions, ignores an additional argument to print only the
-total of the sizes, and the size isn't returned in blocks of 128
-characters.
+Report, to the standard error stream, the names of all defined macros,
+strings, and diversions with their sizes in bytes.  Since @code{gtroff}
+sometimes adds nodes by itself, the returned sizes can be larger than
+expected.
 @endDefreq
 
 @Defreq {pnr, }
@@ -14489,6 +14484,11 @@ indicators and thus @samp{.ps 10u} sets the point size 
to
 10@tie{}points, whereas in GNU @code{troff} it sets the point size to
 10@tie{}scaled points.  @xref{Fractional Type Sizes}.
 
+@cindex @code{pm} request, incompatibilities with @acronym{AT&T} @code{troff}
+The @code{pm} request differs from @acronym{AT&T} @code{troff}:
+@code{gtroff} reports the sizes of macros, strings, and diversions in
+bytes and ignores an argument to report only the sum of the sizes.
+
 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
diff --git a/man/groff.7.man b/man/groff.7.man
index 962295e..d7edc8b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2199,11 +2199,14 @@ Change page length to
 .
 .TPx
 .REQ .pm
-Print macro names and sizes (number of blocks of 128 bytes).
-.
-.TPx
-.REQ .pm "t"
-Print only total of sizes of macros (number of 128 bytes blocks).
+Report,
+to the standard error stream,
+the names and sizes in bytes of
+defined
+macros,
+strings,
+and
+diversions.
 .
 .TPx
 .REQ .pn "\[+-]N"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index ca0d26e..9eb00ff 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4038,6 +4038,24 @@ See subsection \[lq]Fractional point sizes\[rq] above.
 .
 .P
 In
+.RI AT&T\~ troff
+the
+.B .pm
+request reports
+macro,
+string,
+and
+diversion
+sizes in units of 128-byte blocks,
+and an argument reduces the report to a sum of the above in the same
+units.
+.
+.I groff
+ignores any arguments and reports the sizes in bytes.
+.
+.
+.P
+In
 .IR groff ,
 there is a fundamental difference between unformatted input
 characters, and formatted output characters (glyphs).