[PATCH 13/42] find.1: access " character somewhat portably

"G. Branden Robinson" <[email protected]> Tue, 18 Nov 2025 21:45:58 -0600
Newsgroups	gmane.comp.gnu.findutils.bugs
Message-ID	<20251119034558.sgtkfdusydtpu5cx@illithid>
The `\(dq` special character escape sequence is not universally
portable.  Indirect it through a string definition.  (GNU Bash also uses
this technique.[1])

Unfortunately, `"` is one of the worst-behaved and least-accessible
characters in AT&T troff; a pleasant Dr. Jekyll when used on text lines,
its Mr. Hyde persona erupts when used in macro calls, and is wholly
unpredictable to non-experts when appearing in request arguments.[2]
_Some_ AT&T troffs offer `\(dq` on _some_ output devices.  AT&T troff
also has no mechanism for a document to define its own special character
escape sequences.  GNU troff offers `\(dq` on all output devices.

[1] https://github.com/bminor/bash/blob/a8a1c2fac029404d3f42cd39f5a20f24b6e4fe4b/doc/bash.1#L26

[2] "For the (neutral) double quote, you have recourse to an obscure
    syntactical feature of AT&T troff.  Because a double quote can begin
    a macro argument, the formatter keeps track of whether the current
    argument was started thus, and doesn’t require a space after the
    double quote that ends it.  In the argument list to a macro, a
    double quote that isn’t preceded by a space doesn’t start a macro
    argument.  If not preceded by a double quote that began an argument,
    this double quote becomes part of the argument.  Furthermore, within
    a quoted argument, a pair of adjacent double quotes becomes a
    literal double quote."

    https://www.gnu.org/software/groff/manual/groff.html.node/Calling-Macros.html
---
 find/find.1 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/find/find.1 b/find/find.1
index b9c06804..c1ad25fc 100644
--- a/find/find.1
+++ b/find/find.1
@@ -1,5 +1,12 @@
 '\" t
 .TH FIND 1 2025-10-12 findutils \" -*- nroff -*-
+.ie \n(.g \{\
+.  ds " \(dq
+.\}
+.el \{\
+.  \" \*" is not usable in macro arguments on AT&T troff.
+.  ds " ""\" two adjacent quotes and no space before this comment
+.\}
 .SH NAME
 find \- search for files in a directory hierarchy
 .SH SYNOPSIS
@@ -983,7 +990,7 @@ .SS "TESTS"
 so, for example,
 .in +4n
 .nf
-find .\& \-path \(dq./sr*sc\(dq
+find .\& \-path \*"./sr*sc\*"
 .fi
 .in
 will print an entry for a directory called
@@ -1943,7 +1950,7 @@ .SH "UNUSUAL FILENAMES"
 .IP "\-ls, \-fls"
 Unusual characters are always escaped.  White space, backslash, and
 double quote characters are printed using C-style escaping (for
-example `\ef', `\e\(dq').  Other unusual characters are printed using an
+example `\ef', `\e\*"').  Other unusual characters are printed using an
 octal escape.  Other printable characters (for
 .B \-ls
 and
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)