gbranden pushed a commit to branch master
in repository groff.
commit 76bb52ceb8783819153a28c7d04c7476f5494dc7
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Fri Mar 14 20:54:07 2025 -0500
[doc,man]: Clarify `.devicem` and `\Y` behavior.
Sync language and line breaks between our Texinfo manual and groff(7)
and groff_diff(7) man pages.
---
doc/groff.texi.in | 42 +++++++++++++++++++++++++++++++-----------
man/groff.7.man | 36 ++++++++++++++++++++----------------
man/groff_diff.7.man | 22 ++++++++++++----------
3 files changed, 63 insertions(+), 37 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 062b424fc..8e3fcd455 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -17107,23 +17107,43 @@ these produce warnings in category @samp{char}.
GNU
@command{troff}
-also permits the interpolation of macro contents
+also permits the interpolation of macro or string contents
as a device extension command.
@DefreqList {devicem, name}
@DefescItemx {\\Y, , n, }
@DefescItem {\\Y, (, nm, }
@DefescListEnd {\\Y, [, name, ]}
-The @code{devicem} request and @code{\Y} escape sequence are each
-approximately equivalent to @samp{\X'\*[@var{name}]'} (one-character
-name@tie{}@var{n}, two-character name @var{nm}). They differ from that
-construction in that the contents of the string or macro @var{name} are
-not interpreted; further, @var{name} may be a macro and thus contain
-newlines. (There is no way to embed a newline in the arguments to
-@code{device} or @code{\X}.) The inclusion of newlines requires an
-extension to the @acronym{AT&T} @command{troff} device-independen page
-description language; their presence confuses drivers that do not know
-about it (@pxref{Device Control Commands}).
+The
+@code{devicem}
+request and
+@code{\Y}
+escape sequence correspond to
+@samp{.device \*[@var{name}]}
+and
+@samp{\X'\*[@var{name}]'}
+(one-character
+name@tie{}@var{n},
+two-character name
+@var{nm}),
+respectively.
+They differ from their counterparts
+in that GNU
+@command{troff} @c GNU
+does not interpret the contents of the string or macro
+@var{name};
+further,
+@var{name}
+may be a macro and thus contain newlines.
+(There is no way to embed a newline in the arguments to
+@code{device}
+or
+@code{\X}.)
+The inclusion of newlines requires an extension to the @acronym{AT&T}
+@command{troff} @c AT&T
+device-independent page description language,
+and their presence confuses drivers that do not know about it
+(@pxref{Device Control Commands}).
@endDefesc
@DefreqList {tag, name}
diff --git a/man/groff.7.man b/man/groff.7.man
index fa1d38942..2eb25c7fc 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -8499,37 +8499,41 @@ or other postprocessor.
.P
GNU
.I troff \" GNU
-also permits the interpolation of macro contents as a device extension
-command.
+also permits the interpolation of macro or string contents
+as a device extension command.
.
The
.B devicem
-request
-and
+request and
.B \[rs]Y
-escape sequence are each approximately equivalent to
-.RB \[lq] \[rs]X\[aq]\c
-.IB name \[aq]\c
-\[rq].
+escape sequence correspond to
+.RB \[lq] ".device \[rs]*[\c"
+.IB name ]\c
+\[rq]
+and
+.RB \[lq] \[rs]X\[aq]\[rs]*[\c
+.IB name ]\c
+\[rq],
+respectively.
.
-They differ from that construction in that the contents of the string or
-macro
-.I name
-are not interpreted;
+They differ from their counterparts
+in that GNU
+.I troff \" GNU
+does not interpret the contents of the string or macro
+.IR name ;
further,
.I name
may be a macro and thus contain newlines.
.
-(There is no way to embed a newline
-in the arguments to
+(There is no way to embed a newline in the arguments to
.RB \[lq] device \[rq]
or
.BR \[rs]X .)
.
The inclusion of newlines requires an extension to the AT&T
.I troff \" AT&T
-device-independent page description language;
-their presence confuses drivers that do not know about it
+device-independent page description language,
+and their presence confuses drivers that do not know about it
(see subsection \[lq]Device control commands\[rq] of
.MR groff_out @MAN5EXT@ ).
.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 839083071..fd0020a63 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1252,25 +1252,27 @@ and so on.
.BI \[rs]Y( ma
.TQ
.BI \[rs]Y[ mac ]
-Interpolate a macro as a device extension command.
+Interpolate a macro or string as a device extension command.
.
As
.BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\c
,
-except the contents of
-.I mac
-are not interpreted,
-and
+except that GNU
+.I troff \" GNU
+does not interpret the contents of
+.IR mac ;
+further,
.I mac
can be a macro and thus contain newlines,
-whereas the argument to
-.B \[rs]X
-cannot.
+unlike the argument to
+.B \[rs]X .
.
This inclusion of newlines requires an extension to the AT&T
.I troff \" AT&T
-page description language,
-and confuses postprocessors that do not know about it.
+device-independent page description language,
+and their presence confuses drivers that do not know about it
+(see subsection \[lq]Device control commands\[rq] of
+.MR groff_out @MAN5EXT@ ).
.
.
.TP
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
