[ This is a reply to Branden, but some of the questions here are directed at Bernhard ]
On Wed, Nov 19, 2025 at 3:42 AM G. Branden Robinson < [email protected]> wrote: > Here's take two of my proposed man page changes. > Thanks. I have imported these as a local branch and, I hope later this week, will take a closer look at them with a view to applying them. Among other reasons, that "closer look" is needed for my education, so that I don't subsequently reintroduce the goofs corrected in these patches. I haven't looked in about 10 years to be honest, but there is a surprising lack of how-to documentation on how, in detail, to write manual pages. Some years back I received patches from Eric Raymond correcting things like command option synopsis information, and was at the time surprised that there was so little published guidance (beyond, for example, man-pages(7)). I believe that at the time he was trying to make some corrections to all the manpages customarily installed in both Debian and Red Hat, in order to ensure they could all be automatically converted to Docbook format. Though I have heard nothing subsequently about that effort, as far as I recall. I was very happy to see that much of the guidance has also ended up in the manual page source itself, directed at people making changes. Thanks for taking care of this. I haven't tried yet to discover whether CHECKSTYLE highlights any of the guidance I had (previously) no idea about, but certainly I think that much of that we could usefully use as lint-checks locally here in findutils, even if not more generally. For example, - Using \*(~~ where appropriate (I'm going to have to look up what that means, though) - Ensuring that paragraph markers are preceded by empty requests (which I understand is a style issue, but locally in findutils we can be prescriptive about it) - Avoiding .PP - Preferring things like \(lq over ASCII characters for greater portability - Doing sensible things like with things like \(ha - Eliminating avoidable uses of \fR and similar in favour of .R ... .B where feasible (this lint check might be tricky to automate) - Enforce conventions for how to typeset files, command names, command examples; this is something Texinfo does reasonably well (with e.g. @file, @samp, and so forth), but I had introduced inconsistent typesetting in the manpage by not settling (in my mind or in some kind of check) clear expectations for how to render things like /tmp, find, "find /foo -print" and so on. Getting this right is taxing on the memory (for me at least) but I'm not sure if it's feasible to introduce local macros or some other local (within e.g. find.1, xargs.1 etc) mechanism to help the humans (or this human) get this consistently right. - Hyphenation protection for command and file names (which might require a good solution to the previous item) - Good solutions for quoted commands might also allow us to detect places within them where \& might be needed but is absent. - Avoiding \(en in things that are obviously not ranges One of the most welcome discoveries from your patch was " tab(|);". This makes editing these tables much easier, thanks. There are a number of places where we define macros and workarounds for portability issues, and others where we avoid things like .SY in order not to have to provide a local definition. Another option here would be for use to have a single "preamble" which we insert into the manual pages (using the Makefile to generate the foo.1 files from some input). I hereby license all of these patches under CC0 1.0 Universal. > > https://creativecommons.org/publicdomain/zero/1.0/legalcode > > Because with git these patches each have their own independent existence also,* I will copy the above declaration into the git log message of each of your patches before applying/merging them*. I trust that this is OK. The other change I expect to make is a few small tweaks to line up the format of the change log messages with the style used in https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html; we do this because a ChangeLog file is produced from the git log and included in the output tarball as part of "make dist". This is done by some automation provided by gnulib. The changes I expect to make are small and would typically look like this: Before: xargs.1: fix markup nit Consistently use empty request before paragraphing macros to aid document maintainers. This was already done, inconsistently. ... find: improve table formatting in manual page Possibly several (unchanged) paragraphs of exposition here. * Simplify "XY" table definition (see groff's tbl(1) man page). This simpler definition has the same result (and is more adaptable in the event the text of the table is revised). After: xargs: fix markup nit in xargs.1 * xargs.1: Consistently use empty request before paragraphing macros to aid document maintainers. This was already done, inconsistently. ... find: improve table formatting in manual page Possibly several (unchanged) paragraphs of exposition here. * find/find.1 (EXPRESSION) Simplify "XY" table definition (see groff's tbl(1) man page). This simpler definition has the same result (and is more adaptable in the event the text of the table is revised). (Bernhard, if you don't feel it's necessary to follow the GNU Project's ChangeLog style guidance so closely, please say so; I don't think anybody would expect ChangeLog entries to be machine-parseable, after all, so perhaps this last change is not really necessary). Thanks, James.
