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>
---
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
+:Version: Linux
DESCRIPTION
===========
--
2.25.1
