gbranden pushed a commit to branch master
in repository groff.
commit 6cef63191013d1ce09cfe5ef2764fcf3fac72549
Author: G. Branden Robinson <[email protected]>
AuthorDate: Tue Sep 10 23:15:26 2024 -0500
[doc,man]: Revise discussion of \", \#, and \!.
---
doc/groff.texi.in | 31 +++++++++++++++++--------------
man/groff.7.man | 21 ++++++++++++---------
man/groff_diff.7.man | 5 ++---
3 files changed, 31 insertions(+), 26 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 8a2222838..c0b21c68b 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -464,7 +464,7 @@ Documentation License''.
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle version @VERSION@
-@subtitle August 2024
+@subtitle September 2024
@author Trent@tie{}A.@: Fisher
@author Werner Lemberg
@author G.@tie{}Branden Robinson
@@ -7368,19 +7368,22 @@ One of the most common forms of escape sequence is the
comment.@footnote{This claim may be more aspirational than descriptive.}
@Defesc {\\", , , }
-Start a comment. Everything up to the next newline is ignored.
+Start a comment; read everything up to the next newline in copy mode
+(@pxref{Copy Mode}) and discard it.
@cindex @code{\"}, interpretation in copy mode
-@code{\"} is interpreted even in copy mode, to discard the comment
-(@pxref{Copy Mode}).
+@code{\"} is interpreted even in copy mode.
-This may sound simple, but it can be tricky to keep the comments from
-interfering with the appearance of the output.
+It can be tricky to keep the comments from interfering with the
+appearance of the output.
@cindex @code{ds}, @code{ds1} requests, and comments
@cindex @code{as}, @code{as1} requests, and comments
If the escape sequence is to the right of some text or a request, that
-portion of the line is ignored, but spaces preceding it are processed
-normally by GNU @code{troff}. This affects only the @code{ds} and
-@code{as} requests and their variants.
+portion of the line is ignored, but GNU @command{troff} processes spaces
+preceding it normally. This affects requests that read the remainder of
+the control line as a single argument, including @code{ds}, @code{as},
+@code{tm}, and @code{char}; their variants; as well as @code{ab},
+@code{device}, @code{length}, @code{output}, @code{pi}, @code{pso},
+@code{rd}, @code{sy}, @code{write}, and @code{writec}.
@cindex tabs, before comments
@cindex comments, lining up with tabs
@@ -7415,12 +7418,12 @@ macro (namely @samp{''}).
@endDefesc
@Defesc {\\#, , , }
-Start a comment; everything up to and including the next newline is
-ignored. This @code{groff} extension was introduced to avoid the
-problems described above.
+Start a whole-line comment; read everything up to and including the next
+newline in copy mode (@pxref{Copy Mode}) and discard it. GNU
+@command{troff} introduced this extension to avoid the problems
+described above.
@cindex @code{\#}, interpretation in copy mode
-@code{\#} is interpreted even in copy mode, to discard the comment
-(@pxref{Copy Mode}).
+@code{\#} is interpreted even in copy mode.
@Example
Test
diff --git a/man/groff.7.man b/man/groff.7.man
index 14db5ac11..08bdb95bd 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4855,13 +4855,14 @@ Texinfo manual.
.TP
.ESC \[dq]
Comment;
-ignore everything up to the next newline.
+read everything up to the next newline in copy mode and discard it.
.
.
.TP
.ESC #
-Comment;
-ignore everything up to and including the next newline.
+Whole-line comment;
+read everything up to and including the next newline in copy mode and
+discard it.
.
.
.\" ========= strings =========
@@ -4983,14 +4984,16 @@ prevent it from being otherwise hyphenated.
.
.TP
.ESC !
-Transparent line.
+Transparent throughput.
.
-The remainder of the input line is interpreted
-(1) when the current diversion is read;
+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 in the top-level diversion,
-by the postprocessor
-(if any).
+(2) if appearing in the top-level diversion,
+GNU
+.I troff \" GNU
+output.
.
.
.TP
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index fce7af7a6..6af9357cc 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1210,9 +1210,8 @@ then restore it.
.
.TP
.B \[rs]#
-Ignore everything up to and including the next newline.
-.
-This escape sequence is interpreted even in copy mode.
+Read everything up to and including the next newline in copy mode and
+discard it.
.
.B \[rs]#
is like
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
