gbranden pushed a commit to branch master
in repository groff.
commit 066c8a1efe833b8695c683317afd65a78cf4ad5e
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Dec 21 14:06:01 2025 -0600
[doc,man]: Fix Savannah #67372.
* doc/groff.texi.in (Delimiters):
* man/groff.7.man (Delimiters): Clarify what makes an escape sequence
ineligible for use as a delimiter--not its parameterization, but its
own use of delimiters. Relatedly, document the clever hack (dirty
trick?) GNU eqn and tbl use to surround arbitrary user input with
delimiters that are nigh upon guaranteed not to collide with that
input.
Fixes <https://savannah.gnu.org/bugs/?67372>. I hope.
---
ChangeLog | 12 ++++++++++++
doc/groff.texi.in | 25 ++++++++++++-------------
man/groff.7.man | 24 ++++++++++++------------
3 files changed, 36 insertions(+), 25 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index e6efdaafc..619a1cef1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2025-12-21 G. Branden Robinson <[email protected]>
+
+ * doc/groff.texi.in (Delimiters):
+ * man/groff.7.man (Delimiters): Clarify what makes an escape
+ sequence ineligible for use as a delimiter--not its
+ parameterization, but its own use of delimiters. Relatedly,
+ document the clever hack (dirty trick?) GNU eqn and tbl use to
+ surround arbitrary user input with delimiters that are nigh upon
+ guaranteed not to collide with that input.
+
+ Fixes <https://savannah.gnu.org/bugs/?67372>. I hope.
+
2025-12-21 G. Branden Robinson <[email protected]>
[troff]: Split `TOKEN_SPECIAL_CHAR` token type into two, leaving
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 072444b02..31f418394 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -7968,19 +7968,8 @@ see below.
@cindex @code{\r}, as delimiter
@cindex @code{\t}, as delimiter
@cindex @code{\u}, as delimiter
-The following escape sequences don't take arguments
+The following escape sequences are not themselves delimited,
and thus are allowed as delimiters:
-@c That explanation is kind of BS; it's actually because their token
-@c types aren't shared with ones that are parameterized in input.
-@c Allowing `\0`, `\^`, and `\|` also allows the delimited `\h`, which
-@c presumably was not intentional. Allowing special characters as
-@c delimiters, which very much _was_ deliberate (see their use in tbl
-@c and eqn) also allows the delimited `\C`, which is a wart that makes
-@c the foregoing "thus" a lie. But expecting the reader to have a
-@c command of GNU troff's token types, which _should_ be a mere
-@c implementation detail, is a tall order. We can fix this by
-@c introducing separate token types for _delimited_ special characters
-@c and _delimited_ horizontal motions.
@code{\@key{SPC}},
@code{\%},
@code{\|},
@@ -8012,7 +8001,17 @@ and
@code{\u}.
However,
we discourage using them this way;
-they can make the input confusing to read.
+they can make the input confusing to read.@footnote{The
+GNU
+@cite{eqn@r{(1)}}
+and
+@cite{tbl@r{(1)}}
+preprocessors use parameterized but non-delimited special characters
+escape sequences
+@code{\(}
+and
+@code{\[}
+to bracket portions of their output.}
@cindex @code{\D}, delimiters allowed by
@cindex @code{\h}, delimiters allowed by
diff --git a/man/groff.7.man b/man/groff.7.man
index 0c90aab5e..5c967fa3f 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1861,19 +1861,8 @@ see below.
.br
.ne 3v
.P
-The following escape sequences don't take arguments
+The following escape sequences are not themselves delimited,
and thus are allowed as delimiters:
-.\" That explanation is kind of BS; it's actually because their token
-.\" types aren't shared with ones that are parameterized in input.
-.\" Allowing `\0`, `\^`, and `\|` also allows the delimited `\h`, which
-.\" presumably was not intentional. Allowing special characters as
-.\" delimiters, which very much _was_ deliberate (see their use in tbl
-.\" and eqn) also allows the delimited `\C`, which is a wart that makes
-.\" the foregoing "thus" a lie. But expecting the reader to have a
-.\" command of GNU troff's token types, which _should_ be a mere
-.\" implementation detail, is a tall order. We can fix this by
-.\" introducing separate token types for _delimited_ special characters
-.\" and _delimited_ horizontal motions.
.BI \[rs] space\c
,
.BR \[rs]% ,
@@ -1909,6 +1898,17 @@ However,
we discourage using them this way;
they can make the input confusing to read.
.
+(The
+.MR @g@eqn @MAN1EXT@
+and
+.MR @g@tbl @MAN1EXT@
+preprocessors use parameterized but non-delimited special characters
+escape sequences
+.B \[rs](
+and
+.B \[rs][
+to bracket portions of their output.)
+.
.
.br
.ne 3v
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
