weird but successful *roff comment syntax (was: [PATCH] man/man2/seccomp_unotify.2: Document SECCOMP_IOCTL_NOTIF_SET_FLAGS and SECCOMP_USER_NOTIF_FD_SYNC_WAKE_UP)

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4849 bytes --]

[looping in groff list]

Hi Alex,

At 2026-05-18T12:24:25+0200, Alejandro Colomar wrote:
> > +.\"
> > +.SS SECCOMP_IOCTL_NOTIF_SET_FLAGS
> > +The
> > +.B SECCOMP_IOCTL_NOTIF_SET_FLAGS
> > +operation (available since Linux 6.6)
> > +\." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b
> 
> Typo; you meant .\"
> It's also repeated below.
> 
> Interestingly, this seems to also hide it as a comment, although
> troff(1) prints a warning saying that something is wrong:
> 
> 	alx@devuan:~/tmp$ cat comment.man 
> 	.TH comment 7 2026-05-18 experiments
> 	.SH Name
> 	comment \- trying different comments
> 	.SH Description
> 	Here goes one comment:
> 	.\" foo
> 	Comment ended.
> 	.P
> 	Here goes another comment?
> 	\." bar
> 	Comment ended.
> 	alx@devuan:~/tmp$ groff -Tutf8 -man -rCHECKSTYLE=3 -rLL=64n -ww comment.man 
> 	troff:comment.man:10: warning: name '"' not defined
> 	comment(7)      Miscellaneous Information Manual      comment(7)
> 
> 	Name
> 	     comment - trying different comments
> 
> 	Description
> 	     Here goes one comment: Comment ended.
> 
> 	     Here goes another comment?  Comment ended.
> 
> 	experiments                2026‐05‐18                 comment(7)
> 
> I'm curious about what happens in the roff(7) language for this to
> work as a comment.

Strictly, that input line is not treated as a comment.  The formatter
treats the line

  \." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b

as a call of an undefined macro named '"'.  Yes, just the double quote.
In *roff, any printable character is valid in an identifier.

https://www.gnu.org/software/groff/manual/groff.html.node/Identifiers.html

(Using the *roff escape character in an identifier name requires a trick
or two, though.)

Arguments to undefined macros are discarded.  To be Hermes Conrad-grade
correct, not by the formatter itself, but by the automatically created
empty macro definition that does nothing with them.

https://www.gnu.org/software/groff/manual/groff.html.node/Writing-Macros.html

The input therefore operates much like the following.

  ."

Why didn't the leading backslash break this?

5.24.2 Copy Mode
----------------

...
 -- Escape sequence: \.
     '\.' quotes the control character.  It is used to permit nested
     macro definitions to end without a named macro call to conclude
     them.  Without a syntax for quoting the control character, this
     would not be possible.

          .de m1
          foo
          .  de m2
          bar
          \\..
          ..
          .m1
          .m2
              => foo bar
...

https://www.gnu.org/software/groff/manual/groff.html.node/Copy-Mode.html

(If you attempt a nested macro definition in a man(7) document, I cannot
offer any guarantee of your safety when Ingo Schwarze finds out.)

Because I endeavor always to reach greater heights of explanatory
precision, I must acknowledge that `\.` is not a true escape sequence.
It is _quotation_ syntax.  In a grammar that possesses context,
"escaping" and "quoting" move in opposite directions through nested
contextual scopes.  The founders of Unix pulled a sly trick on us all by
routinely using the same item of punctuation for both operations, like a
gear selector for an automatic transmission that uses the same position
for "drive" and "reverse".

But that's okay.  If you get something wrong while driving the PDP-11
Unixmobile, your car will either explode, stop, or an electrical relay
will loudly clunk and a giant amber "?" will appear on your otherwise
instrument-free dashboard.

In any case your journey is over.

In the patch you quoted, the line

  \." commit 48a1084a8b7423642b5f17ca6202f6f277c5392b

did _not_ occur in a copy mode context, so the formatter quietly
discarded the backslash and interpreted '.' as the control character
just as it does in "interpretation mode".

Should this discard be so quiet?  I think not.

I spitballed a relevant idea in Savannah #62776.[1]  In comment #27,
Dave Kemper helpfully summarized several that I had, some of which are
now at risk of being lost since the ticket is closed.  (Some have since
been implemented and are expected in 1.25.)

We see the following.

  `\.` encountered in interpretation mode (comment #17)

In fact, in *roff there are so many ways to "do nothing" that in 1970s
Bell Labs CSRC documents, and on into the next decade before groff
showed up, you'll find a variety of approaches to commenting.

You can see another once-popular approach to commenting in rn(1).

https://www.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Tahoe/usr/src/new/rn/rn.1

GNU troff, especially with warnings dialed up, is much more critical of
its input.

Regards,
Branden

[1] https://savannah.gnu.org/bugs/?62776

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]