Hi James, [rearranging] > TL;DR: thanks for improving our code, can we automate some of this?
BLUF: Yes, we can! :) At 2025-11-13T09:15:56+0000, James Youngman wrote: > Thanks Branden and Bjarni for your advice. > > I recognise many of the errors being corrected here as having been > perpetrated by me, unfortunately. That's understandable. Good documentation, like good software, is a demanding art. :) I think my most commonly typed phrase in groff commit messages must be "problem introduced by me in commit XXX". :-/ I get frustrated with Bjarni sometimes because, in my view, (A) his suggestions for revisions of man pages often confuse matters of correctness with matters of stylistic discretion, and (B) the tone of those messages implies a greater command of the subject matter than their content warrants. On the bright side, he no longer as readily characterizes errors or differences of style in programming or man page composition as a "[l]ack of professionalism, thinking, education, understanding, wisdom, consequences".[1] > Happily, many GNU tools have a kind of linting mechanism built into > the maintainer workflows. We normally describe them as "syntax > checks", though they aren't only that. [snip] > Some of the *roff antipatterns mentioned in this thread are, I think, > areas where backsliding (by me, for example) is a risk. Is there a > way to automate some subset of these checks on a system where groff is > already installed (and there is no access to the groff source tree)? > If yes, then (for example) where we find that *roff is actually groff, > then we could perform some of these checks as part of the maintainers' > workflow. In a word, yes. For instance, here's an MR I recently pitched to the procps-ng team. https://gitlab.com/procps-ng/procps/-/merge_requests/276 Contributing to bash and ncurses has taught me things about portable man(7) composition, and I keep learning new things that I've never seen documented anywhere, like the fact that, in tbl, 'x' as a column modifier was supported by DWB 3.3 troff (Heirloom Doctools called it a "GNU extension")--but it sometimes reported spurious diagnostics about it when the modifier was used in multiple table regions. Or the apparent fact that using `\%` at the beginning of a word to suppress its hyphenation (contrast its usual purpose _within_ a word to mark a hyphenation point) _is_, as best I can determine so far, a GNU troff extension (supported by Heirloom Doctools troff and mandoc(1)). For projects like findutils that, as bash and ncurses do, demand portability to what we might charitably call older troffs, an existing resource will be enriched in the forthcoming groff 1.24: more warnings about use of (some) GNU troff syntactical features that aren't portable to AT&T troff. These warnings are issued only in "compatibility mode". [2] https://www.gnu.org/software/groff/manual/groff.html.node/Compatibility-Mode.html So if you had a Makefile rule like the one I proposed for procps-ng above, you might add something like the following. check-man-portability: groff -C -t -z -ww -rCHECKSTYLE=3 -man $(CHECKABLEMANS) (procsps-ng itself doesn't need this because it supports only the Linux kernel, and almost no GNU/Linux systems exclusively use a legacy troff.) "mandoc -T lint" can also be helpful; because mandoc(1)'s architecture is radically different from any troff's, it has an easier time catching some infelicities than a macro package does. When I do get around to submitting my batch of proposed revisions to the findutils man pages, please demand clarification on any point requiring it, and push back on any change you're reluctant to make--that will mean either that I've failed to adequately motivate a "correctness" change, or that I've failed to appreciate an element of "house style" in your project, which might benefit from being documented (or which I need my attention drawn to an existing exhibit thereof). Regards, Branden [1] https://lists.gnu.org/archive/html/groff/2015-03/msg00033.html https://lists.gnu.org/archive/html/groff/2018-02/msg00037.html https://lists.gnu.org/archive/html/groff/2020-05/msg00018.html Eventually, it seems Colin Watson managed to persuade where others had failed (or neglected to attempt). https://lists.gnu.org/archive/html/groff/2020-05/msg00019.html (And, yes, brevity is a virtue that I, too, struggle to practice.) [2] https://lists.gnu.org/archive/html/groff-commit/2025-11/msg00010.html https://lists.gnu.org/archive/html/groff-commit/2020-10/msg00040.html In fact, this discussion has prompted me to update the wording of the second of these, which shipped in groff 1.23.0 (July 2023). Here's the ChangeLog entry pending in my working copy. 2025-11-13 G. Branden Robinson <[email protected]> * src/roff/troff/input.cpp (is_conditional_expression_true): Tweak wording of syntax warning thrown only in compatibility mode. Say that the conditional expression operator is "not portable to AT&T troff", for parallel phrasing with the escape sequence warning added in commit 589a724eca, 2 November, and because a person authoring or formatting a document presumably knows whether they're using compatibility mode. (If they don't know, they can find out with `.tm compatibility mode is \n(.C`.) Prompted by discussion with James Youngman.
signature.asc
Description: PGP signature
