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@xxxxxxxxx/t/#m8e689a822e03f6e2530a0d6de9d128401916c5de
[2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1016527
Cc: Alejandro Colomar <alx.manpages@xxxxxxxxx>
Reported-by: Alejandro Colomar <alx.manpages@xxxxxxxxx>
Signed-off-by: Quentin Monnet <quentin@xxxxxxxxxxxxx>
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:
OpenPGP_signature
Description: OpenPGP digital signature
