gbranden pushed a commit to branch master
in repository groff.
commit e12cb8803be5a63bf5b6f15e5801975c43c15797
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Jan 4 03:36:16 2026 -0600
[doc,man]: Revise `\!` and `\?` descriptions.
Migrate from "anything" to "character-sequence".
Also tweak style: favor active voice over passive.
Sync language between our Texinfo manual and man pages.
Also break input lines consistently between Texinfo and man pages.
Continues the long process of fixing Savannah #65976.
---
doc/groff.texi.in | 69 +++++++++++++++++++++++++++++++++++++---------------
man/groff.7.man | 30 ++++++++++++-----------
man/groff_diff.7.man | 8 +++---
3 files changed, 70 insertions(+), 37 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 4406caeab..b48c6ee45 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -18068,28 +18068,52 @@ respectively---lines that have been already stored in
the diversion
@endExample
@endDefreg
-@DefescList {\\!, , anything, }
-@DefescListEndx {\\?, , anything, \\?}
+@DefescList {\\!, , character-sequence, }
+@DefescListEndx {\\?, , character-sequence, \\?}
@cindex transparent output (@code{\!}, @code{\?})
@cindex output, transparent (@code{\!}, @code{\?})
-@dfn{Transparently} embed @var{anything} into the current diversion,
-preventing requests, macro calls, and escape sequences from being
-interpreted when read into a diversion. This is useful for preventing
-them from taking effect until the diverted text is actually output. The
-@code{\!} escape sequence transparently embeds input up to and including
-the end of the line. The @code{\?} escape sequence transparently embeds
-input, read in copy mode, until its own next occurrence on the input
-line.
+@dfn{Transparently}
+embed
+@var{character-sequence}
+into the current diversion,
+preventing the formatter from interpreting
+requests,
+macro calls,
+and escape sequences
+when reading them into a diversion.
+Doing so prevents them from taking effect
+until the diverted text is actually output.
+The
+@code{\!}
+escape sequence transparently embeds input
+up to and including the end of the line.
+The
+@code{\?}
+escape sequence transparently embeds input,
+read in copy mode,
+up to its own next occurrence on the input line.
@cindex @code{\?}, and copy mode
@cindex copy mode, and @code{\?}
@cindex mode, copy, and @code{\?}
@cindex @code{\!}, and copy mode
@cindex copy mode, and @code{\!}
@cindex mode, copy, and @code{\!}
-Use @code{\!} by itself to embed newlines in a diversion.
+Use
+@code{\!}
+by itself to embed newlines in a diversion.
@cindex @code{\?}, interpretation in copy mode
-Unlike @code{\!}, @code{\?} is interpreted even in copy mode
-(@pxref{Copy Mode}).
+Unlike
+@code{\!},
+@code{\?}
+is interpreted even in copy mode
+(@pxref{Copy Mode});
+consequently,
+comparands protected with
+@code{\?}
+need not even be valid
+GNU
+@command{troff} @c GNU
+syntax.
@Example
.nr x 1
@@ -18115,16 +18139,23 @@ Both escape sequences read the data in copy mode.
@cindex @code{\!}, in top-level diversion
@cindex top-level diversion, and @code{\!}
@cindex diversion, top-level, and @code{\!}
-If @code{\!} is used in the top-level diversion, its argument is
-embedded into GNU @command{troff}'s device-independent output. One of
-its applications is control of a postprocessor that transforms the data
-that are subsequently read by an output driver.
+If
+@code{\!}
+is used in the top-level diversion,
+its argument is embedded into
+GNU
+@command{troff}'s @c GNU
+device-independent output.
+One of its applications is control of a postprocessor
+that transforms the data that are subsequently read by an output driver.
@cindex @code{\?}, in top-level diversion
@cindex top-level diversion, and @code{\?}
@cindex diversion, top-level, and @code{\?}
-Using the @code{\?} escape sequence in the top-level diversion produces
-no output at all; its argument is simply ignored.
+Using the
+@code{\?}
+escape sequence in the top-level diversion produces no output at all;
+its argument is simply ignored.
@endDefesc
@cindex @code{\!}, and @code{output} request
diff --git a/man/groff.7.man b/man/groff.7.man
index 6fcf296b6..24a69b1a8 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5713,25 +5713,27 @@ prevent it from being otherwise hyphenated.
.
.
.TP
-.ESC !
-Transparent throughput.
+.ESC ! character-sequence
+.I Transparently
+embed
+.IR character-sequence ,
+up to and including the end of the line,
+into the current diversion,
+requests,
+macro calls,
+and escape sequences
+when reading them into a diversion.
.
-Read everything up to the next newline in copy mode and ignore it,
-but pass it through to
-(1) an enclosing diversion,
-or
-(2) if appearing in the top-level diversion,
-GNU
-.I troff \" GNU
-output.
+Doing so prevents them from taking effect
+until the diverted text is actually output.
.
.
.TP
-.ESC? anything
+.ESC? character-sequence
Transparently embed
-.IR anything ,
-read in copy mode,
-in a diversion,
+.IR character-sequence ,
+up to its own next occurrence on the input line,
+into a diversion,
or unformatted as an output comparand in a conditional expression.
.
Ignored in the top-level diversion.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 5a65a5045..f52d369ee 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1577,9 +1577,9 @@ The remainder of the word is subject to hyphenation as
normal.
.
.
.TP
-.BI \[rs]? anything \[rs]?
+.BI \[rs]? character-sequence \[rs]?
Suppress formatting of
-.I anything.
+.I character-sequence.
.
This feature has two applications.
.
@@ -1621,8 +1621,8 @@ Unlike
.BR \[rs]! ,
.B \[rs]?\&
is interpreted even in copy mode,
-and
-.I anything
+and a
+.I character-sequence
in the top-level diversion
is not sent to device-independent output.
.
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
