gbranden pushed a commit to branch master
in repository groff.
commit 25bc12108df3f7a9a26a979d7ceefcf20e725943
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun May 4 08:14:03 2025 -0500
[doc,man/*]: Clarify behavior of asciify request.
---
doc/groff.texi.in | 22 +++++++++++++++++-----
man/groff_diff.7.man | 16 ++++++++++++----
2 files changed, 29 insertions(+), 9 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 7f7e94043..dbda92e25 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16346,11 +16346,23 @@ following sets register@tie{}@code{n} to@tie{}1.
.x
@endExample
-@code{asciify} cannot return all items in a diversion to their source
-equivalent: nodes such as those produced by the @code{\N} escape
-sequence will remain nodes, so the result cannot be guaranteed to be a
-pure string. @xref{Copy Mode}. Glyph parameters such as the type face
-and size are not preserved; use @code{unformat} to achieve that.
+@code{asciify}
+cannot return all nodes in a diversion to their source equivalents:
+those produced by indexed characters
+(@code{\N}),
+for example,
+remain nodes,
+so the result cannot be guaranteed to be a character sequence
+as a macro or string is.
+@c TODO: We _could_ store the integer argument to the `\N` escape
+@c sequence in the node data, enabling such reversal.
+Give the diversion name as an argument to the
+@code{pm}
+request to inspect its contents and node list.
+Glyph parameters such as the type face and size are not preserved;
+use
+@code{unformat}
+to achieve that.
@endDefreq
@Defreq {unformat, div}
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 4f792b750..b896390cb 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1828,11 +1828,19 @@ request.
.
.IP
.B \%asciify
-cannot return all items in a diversion to their source equivalent:
-nodes such as those produced by
-.BR \[rs]N ,
+cannot return all nodes in a diversion to their source equivalents:
+those produced by indexed characters
+.RB ( \[rs]N ),
+for example,
remain nodes,
-so the result cannot be guaranteed to be a pure string.
+so the result cannot be guaranteed to be a character sequence
+as a macro or string is.
+.\" TODO: We _could_ store the integer argument to the `\N` escape
+.\" sequence in the node data, enabling such reversal.
+.
+Give the diversion name as an argument to the
+.B pm
+request to inspect its contents and node list.
.
Glyph parameters such as the type face and size are not preserved;
use
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
