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

[Quentin Monnet <quentin@isovalent.com>]

On 02/08/2022 11:59, Alejandro Colomar wrote:
> Hi Quentin,
> 
> On 8/2/22 12:28, Quentin Monnet 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
>>> found style problems; aborting
>>
>> Not sure I understand this last one. Isn't "7" a valid man section?
> 
> It is a valid section.  I don't understand it either.  Maybe groff(1)
> has gone crazy after so many errors.  I'll report a bug to groff.
> 
>>
>>> 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 "" "" ""
>>> ]
>>>
>>>
>>> I don't know if you can fix that, or if it's a limitation of the
>>> generator?  I can live with it, but it would be nice if it could be
>>> fixed.  It provides the headers and footers of the manual page.
>>
>> I had never really looked into completing this line before, but it seems
>> that Docutils/rst2man has a few (albeit not much documented) docinfo
>> elements available to complete _some_ of these fields. We currently have
>> ":Manual section: 7" in the generated page. I can generate a page close
>> to the result above with:
>>
>>      :Manual section: 7
>>      :Manual group: Linux Programmer's Manual
>>      :Version: Linux
>>      :Date: 2022-08-02
>>
>> With these fields, I get:
>>
>>      .TH BPF-HELPERS 7 "2022-08-03" "Linux" "Linux Programmer's Manual"
>>
>> Caveats: First, we get additional double quotes around the date, not
>> sure if this matters.
> 
> Nah, quotes are only for spaces (they are ignored in this case).  You're
> fine with or without them.
> 
>>
>> Second: “Version” does not seem a relevant field name in that case, but
>> this is apparently the only option that we have to insert a value at
>> this location [0]. Apparently the manpage writer for Docutils assumes
>> that this line contains a version number [1].
> 
> That field seems to be different, depending on who you ask.
> 
> In most cases, it's a "project and version" (see for example the groff
> warning text).
> 
> But in the linux man-pages, since we cover many projects and versions,
> we just say which project we're documenting (to avoid having to update
> the version every time, I guess).
> 
> See man-pages(7):
> [
>    Title line
>        The first command in a man page should be a TH command:
> 
>               .TH title section date source manual
> 
>        The arguments of the command are as follows:
> 
>        [...]
> 
>        source The source of the  command,  function,  or  system
>               call.
> 
>               For those few man‐pages pages in Sections 1 and 8,
>               probably you just want to write GNU.
> 
>               For  system  calls, just write Linux.  (An earlier
>               practice was to write the version  number  of  the
>               kernel  from which the manual page was being writ‐
>               ten/checked.  However, this was never done consis‐
>               tently, and so was probably worse  than  including
>               no  version number.  Henceforth, avoid including a
>               version number.)
> 
>               For library calls that are part of glibc or one of
>               the other common GNU libraries, just use GNU C Li‐
>               brary, GNU, or an empty string.
> 
>               For Section 4 pages, use Linux.
> 
>               In cases of doubt, just write Linux, or GNU.
> 
>        [...]
> ]
> 
> So, just saying ':Version: Linux' would be fine.
> 
>>
>> Third: The date should of course be updated when generating the page. I
>> found that rst2man has a "--date" option, but it does not insert it at
>> the location we want. Instead, it would probably be a matter of adding a
>> sed command to the pipeline, something along:
>>
>>      $ ./scripts/bpf_docs.py helpers | \
>>          sed -e "s/__DATE__/$(date -I)/" | \
>>          rst2man | man -l -
> 
> The date, yeah, I can add it to the pipeline.
> BTW, I reported a bug to rst2man (I CCd you, so you probably already
> know :)).
> 
>>
>> If it looks better for the man-pages repo, I can send a patch for the
>> man-page template in bpf_docs.py to set ":Manual group:" and
>> ":Version:". I can also ask on the docutils mailing list if there is a
>> cleaner way to proceed, without falling back to this ":Version:" field.
> 
> Yeah, please patch :Manual group:.  Also patch :Version: (I think we can
> live with it), although of course feel free to ask about better
> alternatives to it.
> 
> But don't patch :Date: yet.  Let's see what they answer to the bug
> report.  (And if you want, you can wait for the bug report to resolve to
> patch everything at once, of course.)

Thanks for the precisions, and for opening the bug!
OK, I'll follow the discussion on the bug and wait to see how it goes.
I've set a reminder to myself to update the other info in a few weeks if
nothing happens by then.

Thanks,
Quentin