Re: bpf-helpers.7: .TH line is... meh (was: [PATCH] bpf_doc.py: Use SPDX-License-Identifier)

[G. Branden Robinson]

Hi Alex,

At 2022-08-02T13:07:29+0200, Alejandro Colomar wrote:
> On 8/2/22 12:28, Quentin Monnet wrote:
> > On 01/08/2022 23:13, Alejandro Colomar wrote:
> > > 
> > > I've been running a linter on the man-pages, and had this
> > > triggered from bpf-helpers.7:
> > > 
> > > [
> > > $ make lint V=1
> > > LINT (groff)    tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch
> > > groff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww  -z
> > > man7/bpf-helpers.7
> > > an.tmac:man7/bpf-helpers.7:3: style: .TH missing third argument; suggest
> > > document modification date in ISO 8601 format (YYYY-MM-DD)
> > > an.tmac:man7/bpf-helpers.7:3: style: .TH missing fourth argument;
> > > suggest package/project name and version (e.g., "groff 1.23.0")
> > > an.tmac:man7/bpf-helpers.7:3: style: .TH missing fifth argument and
> > > second argument '7' not a recognized manual section; specify volume title
> > 
> > Not sure I understand this last one. Isn't "7" a valid man section?

Yes--yes, it is.

Repeating one line of the above...

> > > found style problems; aborting

I would prefix this diagnostic with something informative.  I make this
request somewhat selfishly because I don't want people to think it comes
from groff itself.  I do recognize it as the "landmine" hack I suggested
to you some time ago.  :)

> > > make: *** [lib/lint-man.mk:49:
> > > tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch] Error 1
> > > 
> > > ]
> > > 
> > > See what a normal .TH line looks like, and what bpf-helpers.7 has:
> > > 
> > > [
> > > $ grep ^.TH man2/bpf.2
> > > .TH BPF 2 2021-08-27 "Linux" "Linux Programmer's Manual"
> > > $ grep ^.TH man7/bpf-helpers.7
> > > .TH BPF-HELPERS 7 "" "" ""
> > > ]
> 
> That seems like a non-legitimate warning.  May it be a bug in
> groff(1)? It also may be that due to the many other issues, groff(1)
> already went (legitimately) crazy,

No, I don't think groff's man(7) is in a disordered state, it is just
that one of the recent changes is, like its author, a little bit _too_
irascible.

> but I'm reporting it in case there's a small bug somewhere.

Indeed, I can reproduce the problem with this similar and trivially
short specimen.

$ cat EXPERIMENTS/going-crazy.man
.TH bpf\-helpers 7 "" "" ""
.SH Name
bpf\-helpers \- put a programming language in the kernel
$ ./build/test-groff -Tascii -man -rCHECKSTYLE=3 EXPERIMENTS/going-crazy.man
an.tmac:EXPERIMENTS/going-crazy.man:1: style: .TH missing third argument; 
suggest document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:EXPERIMENTS/going-crazy.man:1: style: .TH missing fourth argument; 
suggest package/project name and version (e.g., "groff 1.23.0")
an.tmac:EXPERIMENTS/going-crazy.man:1: style: .TH missing fifth argument and 
second argument '7' not a recognized manual section; specify volume title
bpf-helpers(7)                                                  bpf-helpers(7)

Name
       bpf-helpers - put a programming language in the kernel

                                                                bpf-helpers(7)

We can see that the center header, and left and center footer texts, are
blanked out as the `TH` call with explicitly blank arguments directs.
The page otherwise renders normally.

I'll have a look and see what I can do.

Regards,
Branden

signature.asc
Description: PGP signature