Follow-up Comment #20, bug #67372 (group groff): [comment #18 comment #18:] > To support (belated, retroactive) future design work on an ancient groff > feature that has been only partially designed and implemented for a long > time, i have run > > $ grep -ER '(^|[^\\])\\[*ABbCDFfgHhkLMmNnOoESsVvwXxYZ]\\' * > > on a few manual page trees.
Good stuff! This is valuable work. > The intent of the regex is to find real-world examples of escape sequences > that (optionally or mandatorily) take delimited arguments and that have the > beginning of another escape sequence right after the function character, but > only if this occurs after a non-backslash character or at the beginning of an > input line. The "but only" restriction is essential to suppress noise > because abuse of "\\" where the traditional "\e" or the modern "\[rs]" is > intended is extremely widespread (not so much in OpenBSD base, but almost > anywhere else). Yes. The fact that `\\` and `\.` aren't "true" escape sequences has been prominent on my mind this week thanks to this ticket. I've been trying to reason out how I would explain that that claim. For now, my thoughts are swirling around the idea that the *roff escape character works as we think of an escape character only during macro definition, or more precisely (and generally!) in "copy mode". When not in copy mode, the "escape character" is better thought of as a "special function introducer". Like Perl's leading `$`, `@`, and `%` sigils, *roff's escape character is a sign to the intepreter that what follows should be handled _differently_ than usual. And of course the specialness of *roff's "copy mode" rears its head again. Even in copy mode, the escape character is not a "true" escape character when followed by a subset of function selectors. Do you think anyone can tell that AT&T _troff_ was designed on an _ad hoc_ basis? ;-) > There are no matches in OpenBSD base, Xenocara, FreeBSD 14.2 base, or NetBSD > 10.1 base. That's excellent news. > But there are several hundred matches even in the few ports i happen to have > installed, so likely thousands in the ports tree as a whole. > > gnutls-serv(1) contains: > > [...] > .ie t \ > .ds B-Font [CB] > .ds I-Font [CI] > .ds R-Font [CR] > .el \ > .ds B-Font B > .ds I-Font I > .ds R-Font R > .TH gnutls-serv 1 "09 Jul 2025" "3.8.10" "User Commands" > .SH NAME > \f\*[B-Font]gnutls-serv\fP > \- GnuTLS server > .SH SYNOPSIS > \f\*[B-Font]gnutls-serv\fP > .\" Mixture of short (flag) options and long options > [\f\*[B-Font]\-flags\f[]] > [\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]] > [\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]] > [,,,] > > I don't think that code is doing what the manual page authors seem to hope it > would be doing, but it clearly intends to interpolate the "[" argument > delimiter into an \f sequence. Yes. > The same idiom is present in ocsptool(1), p11tool(1) and several other pages > in the gnutls package. So one project with some bad habits. That doesn't sound intractable. > Judging from > https://gitlab.com/gnutls/gnutls/-/blob/master/doc/manpages/Makefile.am , > they are using https://gitlab.com/gnutls/cligen to generate the man(7) code. > Apparently, not to be confused with https://github.com/clicon/cligen > nor with https://github.com/c-blake/cligen > nor with https://pypi.org/project/cligen/ . *snort* > But i'd be somewhat surprised if the gnutls folks were the only ones doing > something like that. No, but that means if we can correct the defect in "cligen"'s _man_(7) generation, it will percolate out over time and fix a whole class of problems among multiple projects. > I wouldn't expect much of the kind in mdoc(7) documents, but likely more in > man(7) documents. I agree. A benefit of _mdoc_(7)'s design is that it is so large and challenging to acquire that everyone who selects it for their macro language despairs of trying to learn the underlying formatter's language, and so they don't make rookie mistakes with *roff. ;-P _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?67372> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
signature.asc
Description: PGP signature
