Re: 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)

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

On 2026-05-18T06:24:19-0500, G. Branden Robinson wrote:
> [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

Thanks!  :-)


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>

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