Re: [PATCH] Automate man-page linting

On Sat, Nov 15, 2025 at 8:13 PM Bernhard Voelker
<[email protected]> wrote:
>
> 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?

Possibly, but the only likely conflict is a small change to find.1,
and that doesn't conflict with current `master` as far as I can see.

> 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.

"make check" doesn't fail with these patches applied on current
"master", at least it didn't fail when I ran that test today.

>  >+     messages="$( ${GROFF} -t -z -ww -rCHECKSTYLE=2 -man ${srcdir}/${manpage} 2>&1 )"
> __________________________________________^^^^^^^^^^^^
>
> Is there a reason you used value 2 here?

Yes, it was the value used in the patch that Branden pointed to as the
example: https://gitlab.com/procps-ng/procps/-/merge_requests/276/diffs?commit_id=503f7a7ffe42e7c5119f6ecd944693e0fdd0762a
(via https://gitlab.com/procps-ng/procps/-/merge_requests/276).


> The original suggestion was using 3:
>
>  >>    groff -C -t -z -ww -rCHECKSTYLE=3 -man $(CHECKABLEMANS)

I was just going by the example patch to procps.   If 3 is the
recommendation, let's use that.

> 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

I had assumed that "make distcheck" would run syntax-checks where
feasible.  My mistake, but fixed now.

> 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.

I'm amenable to codifying whatever you think most useful.

Though I would like to avoid more literal forms of duplication.  By
which I mean that the comment should explain the motivation for the
change where needed, but if a comment is needed to explain the code
itself, then it should be added to the code itself, as part of the
patch.

But you're right, I forgot the ChangeLog-style part of the body.  My
mistake, switching between too many disparate projects :)   I will fix
and re-send.

James.