Re: [PATCH] Automate man-page linting

On 11/15/25 20:03, James Youngman wrote:
> Two patches attached; the second automates the kinds of lint checks
> Branden recommended.  The first fixes a problem that the new lint
> check would have objected to.

Sorry, I'm a bit confused.

 > [PATCH 1/2] Fix some lint problems in the find manual page.

This overlaps with Branden's patches, doesn't it?
   * [PATCH 01/40] Fix troff error in find(1).
   * [PATCH 02/40] Replace UTF-8 character sequence in find(1)


 > Subject: [PATCH 2/2] [maint] Stricter manpage checks.

And I would rather like to wait with enforcing a stricter check until the
fixes for the man pages are in.  Otherwise, 'make check' would fail.

 >+	messages="$( ${GROFF} -t -z -ww -rCHECKSTYLE=2 -man ${srcdir}/${manpage} 2>&1 )"
__________________________________________^^^^^^^^^^^^

Is there a reason you used value 2 here?
The original suggestion was using 3:

 >>    groff -C -t -z -ww -rCHECKSTYLE=3 -man $(CHECKABLEMANS)

Furthermore, the patch introduces a syntax-check failure itself:

   makefile_at_at_check
   find/Makefile.am:644: 	env GROFF=@GROFF@ $(top_srcdir)/build-aux/man-lint.sh $(srcdir) $(man_MANS)
   locate/Makefile.am:1087: 	env GROFF=@GROFF@ $(top_srcdir)/build-aux/man-lint.sh $(srcdir) $(man_MANS)
   xargs/Makefile.am:1338: 	env GROFF=@GROFF@ $(top_srcdir)/build-aux/man-lint.sh $(srcdir) $(man_MANS)
   maint.mk: use $(...), not @...@
   make: *** [maint.mk:1296: sc_makefile_at_at_check] Error 1


Finally, I would be very happy if we'd consistently use a more complete commit message style
which clarifies the questions what, why, where and how more precisely.
Also prepending the SUBJECT line with a classification like "maint:", "build:", "find:",
"doc:" etc is very helpful IMO.
The mailing list URLs <https://lists.gnu.org/archive/html/bug-findutils>
can be abbreviated to <https://lists.gnu.org/r/bug-findutils>/

E.g. I would phrase the commit message for the 2nd patch like this:

     maint: use stricter manpage checks

     From a suggestion by G. Branden Robinson [1] to use
       `groff -t -z -ww -rCHECKSTYLE=3 -man ...`
     Let's use CHECKSTYLE=2 here, because ....FIXME...

     * build-aux/man-lint.sh: Use the above stricter check.
     * configure.ac: Allow to configure GROFF.
     * find/Makefile.am: Move manpage checks from dist-hook to check-local.
     Use configure-time GROFF tool for linting.
     * locate/Makefile.am: Likewise.
     * xargs/Makefile.am: Likewise.

     [1] https://lists.gnu.org/r/bug-findutils/2025-11/msg00004.html

Have a nice day,
Berny