Re: [PATCH bpf-next] scripts/bpf: Fix attributes for bpf-helpers(7) man page

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3826 bytes --]

Hi Quentin,

On 8/23/22 10:47, Quentin Monnet wrote:
> The bpf-helpers(7) manual page shipped in the man-pages project is
> generated from the documentation contained in the BPF UAPI header, in
> the Linux repository, parsed by script/bpf_doc.py and then fed to
> rst2man.
> 
> After a recent update of that page [0], Alejandro reported that the
> linter used to validate the man pages complains about the generated
> document [1]. The header for the page is supposed to contain some
> attributes that we do not set correctly with the script. This commit
> updates some of them; please refer to the previous discussion for the
> meaning of those fields and the value we use (tl;dr: setting "Version"
> to "Linux" seems acceptable).
> 
> Before:
> 
>      $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
>      .TH BPF-HELPERS 7 "" "" ""
> 
> After:
> 
>      $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
>      .TH BPF-HELPERS 7 "" "Linux" "Linux Programmer's Manual"
> 
> Note that this commit does not update the date field. This date should
> ideally be updated when generating the page to the date of the last edit
> of the documentation (which we can maybe approximate to the last edit of
> the BPF UAPI header). There is a --date option in rst2man; it does not
> update that field, but Alejandro raised an issue about it [2] so it
> might do in the future. Anyway, we just leave the date empty for now.
> 
> [0] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/bpf-helpers.7?id=19c7f78393f2b038e76099f87335ddf43a87f039
> [1] https://lore.kernel.org/all/20220721110821.8240-1-alx.manpages@gmail.com/t/#m8e689a822e03f6e2530a0d6de9d128401916c5de
> [2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1016527
> 
> Cc: Alejandro Colomar <alx.manpages@gmail.com>
> Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
> Signed-off-by: Quentin Monnet <quentin@isovalent.com>

Heh, we very recently changed the .TH line in the Linux man-pages for 
consistency with tradition and most other manual pages out there):

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=7bd6328fd40871ad75cbc3b6aa5d4a4b70f53ac7>
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=45186a5da74285d72199744eb5d2888fe348f680>

So, we now omit the last (5th) argument to .TH,
and the Version one really contains a version now.
I'll comment below with what I think you should do.

An example may show it better:

$ grep ^.TH <man2/membarrier.2
.TH MEMBARRIER 2 2021-08-27 "Linux man-pages (unreleased)"

Of course, that '(unreleased)' is replaced by the actual version at the 
time of `make dist` (creating the tarball).


> ---
>   scripts/bpf_doc.py | 2 ++
>   1 file changed, 2 insertions(+)
> 
> diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py
> index dfb260de17a8..e66ef4f56e95 100755
> --- a/scripts/bpf_doc.py
> +++ b/scripts/bpf_doc.py
> @@ -378,6 +378,8 @@ list of eBPF helper functions
>   -------------------------------------------------------------------------------
>   
>   :Manual section: 7
> +:Manual group: Linux Programmer's Manual

Remove "Manual group" completely.  If we don't specify that, groff(1) 
(or mandoc(1)) will produce sane defaults.  For section 7, it uses 
"Miscellaneous Information Manual".

I will report a bug to rst2man(1) that it shouldn't leave the field as 
"" if not specified, but it should just not add the field at all if not 
specified.

> +:Version: Linux

You could append the version here.  Or maybe put a placeholder that the 
script should fill with information from the makefile or git-describe(1)?

>   
>   DESCRIPTION
>   ===========

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]