scripts/bpf: Fix attributes for bpf-helpers(7) man page
PATCH 1/1 scripts/bpf: Fix attributes for bpf-helpers(7) man page
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/[email protected]/t/#m8e689a822e03f6e2530a0d6de9d128401916c5de
[2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1016527
--- scripts/bpf_doc.py | 2 ++ 1 file changed, 2 insertions(+)
scripts/bpf_doc.py +2 -0
@@ -378,6 +378,8 @@ list of eBPF helper functions ------------------------------------------------------------------------------- :Manual section: 7 +:Manual group: Linux Programmer's Manual +:Version: Linux DESCRIPTION ===========
Signature · 1 line
2.25.1
Hi Quentin,
Quoted 30 lines · Quentin Monnet
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.pyand 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.
Quoted 7 lines
[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/[email protected]/t/#m8e689a822e03f6e2530a0d6de9d128401916c5de
[2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1016527Cc Alejandro Colomar <[email protected]>Reported-by Alejandro Colomar <[email protected]>Signed-off-by Quentin Monnet <[email protected]>
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 list of eBPF helper functions · line 381
Quoted 13 lines
--- scripts/bpf_doc.py | 2 ++ 1 file changed, 2 insertions(+)scripts/bpf_doc.py +1
-0@@ -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.
scripts/bpf_doc.py list of eBPF helper functions · line 382
Quoted 1 line
scripts/bpf_doc.py +1
-0+: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)?
scripts/bpf_doc.py list of eBPF helper functions · line 385
Quoted 3 lines
scripts/bpf_doc.py +0
-0DESCRIPTION ===========
Cheers,
Alex
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
Quoted 43 lines · Alejandro Colomar
Hi Quentin,
Quoted 36 lines · Quentin Monnet
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.pyand 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/[email protected]/t/#m8e689a822e03f6e2530a0d6de9d128401916c5de
[2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1016527Quoted 3 lines
Cc Alejandro Colomar <[email protected]>Reported-by Alejandro Colomar <[email protected]>Signed-off-by Quentin Monnet <[email protected]>
Quoted 5 lines
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>
Wow, I'm two days late!
Quoted 32 lines
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).Quoted 9 lines
---
scripts/bpf_doc.py| 2 ++1 file changed, 2 insertions(+)scripts/bpf_doc.py +0
-0@@ -378,6 +378,8 @@ list of eBPF helper functionsQuoted 4 lines
-------------------------------------------------------------------------------
:Manual section: 7
+:Manual group: Linux Programmer's ManualRemove "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".
Quoted 8 lines
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.
Quoted 1 line
+: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)?
So if I understand correctly, running bpf_doc.py should currently produce the following string:
.TH BPF-HELPERS 7 "" "Linux (5.19.0)" ""
Is this what you expect?
I can make the script call "make kernelversion" to produce the above. I'm not 100% convinced it should be the role of that script vs. when copying it (we risk having some inaccuracies, for example I generated the above from the bpf-next, so it doesn't really correspond to 5.19), but maybe it's easier that way and avoids adding another script in the middle of the generation so OK.
Thanks,
Quentin
Hi Quentin,
Quoted 1 line · Quentin Monnet
Wow, I'm two days late!
;-)
[...]
Quoted 10 lines
Quoted 3 lines
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)?
So if I understand correctly, running
bpf_doc.pyshould currently produce the following string:.TH BPF-HELPERS 7 "" "Linux (5.19.0)" ""Is this what you expect?
Almost. I expect:
.TH BPF-HELPERS 7 "" "Linux 5.19.0"
Notice the differences:
- No 5th empty field "".
- No parentheses in the version string.
But since you're not in control of the last field, and it's just a bug in rst2man, an empty 5th arg as you suggested is the best you can provide. I'll file the bug.
As for the parentheses in the version, I wouldn't put them; I only put them in the man-pages unreleased string, to make it clear that it's a version, but in the final version I remove them.
See:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/version.mk>
and
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/dist.mk#n33>
Quoted 7 lines
I can make the script call "make kernelversion" to produce the above. I'm not 100% convinced it should be the role of that script vs. when copying it (we risk having some inaccuracies, for example I generated the above from the bpf-next, so it doesn't really correspond to 5.19), but maybe it's easier that way and avoids adding another script in the middle of the generation so OK.
I like it that way. Moreover, I'll always run this script from a release tag from Linus' repo, so the version should match exactly the code.
Anyway, and I think this affects many projects out there have the same issue:
The versioning should always be correct. git-describe(1) should be preferred, or in absence of that, a generic (unreleased) string should be used. Describing any commit after v5.18 and before v5.19-rc1 to be '5.18.0' is plain wrong/misleading. The Makefile should probably autogenerate that info from git-describe(1). See how the Linux man-pages do it (in the links above you can see it) for example.
Cheers,
Alex
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
Quoted 24 lines · Alejandro Colomar
Hi Quentin,
Quoted 1 line · Quentin Monnet
Wow, I'm two days late!
;-)
[...]
Quoted 11 lines
Quoted 4 lines
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)?
So if I understand correctly, running
bpf_doc.pyshould currently produce the following string:.TH BPF-HELPERS 7 "" "Linux (5.19.0)" ""
Is this what you expect?
Almost. I expect:
.TH BPF-HELPERS 7 "" "Linux 5.19.0"
Quoted 7 lines
Notice the differences:
- No 5th empty field "".
- No parentheses in the version string.But since you're not in control of the last field, and it's just a bug in rst2man, an empty 5th arg as you suggested is the best you can provide.
Agreed
Quoted 5 lines
I'll file the bug.
As for the parentheses in the version, I wouldn't put them; I only put them in the man-pages unreleased string, to make it clear that it's a version, but in the final version I remove them.
OK, I wasn't sure. Thanks for the details.
Quoted 20 lines
See:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/version.mk>
and
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/dist.mk#n33>Quoted 7 lines
I can make the script call "make kernelversion" to produce the above. I'm not 100% convinced it should be the role of that script vs. when copying it (we risk having some inaccuracies, for example I generated the above from the bpf-next, so it doesn't really correspond to 5.19), but maybe it's easier that way and avoids adding another script in the middle of the generation so OK.
I like it that way. Moreover, I'll always run this script from a release tag from Linus' repo, so the version should match exactly the code.
Anyway, and I think this affects many projects out there have the same issue:
Quoted 6 lines
The versioning should always be correct. git-describe(1) should be preferred, or in absence of that, a generic (unreleased) string should be used. Describing any commit after v5.18 and before v5.19-rc1 to be '5.18.0' is plain wrong/misleading. The
Makefileshould probably autogenerate that info from git-describe(1). See how the Linux man-pages do it (in the links above you can see it) for example.
It's not really about how to do it, more that I don't want to have a hard dependency on git for the script. I want it to run just as well when there's no Git repo around. But I can try to run "git describe" and fall back on the Makefile (or on an empty version) if the command fails.
OK I'll prepare a new version, thanks for your help. Quentin
Hi Quentin,
Quoted 11 lines · Quentin Monnet
Quoted 6 lines
The versioning should always be correct. git-describe(1) should be preferred, or in absence of that, a generic (unreleased) string should be used. Describing any commit after v5.18 and before v5.19-rc1 to be '5.18.0' is plain wrong/misleading. The
Makefileshould probably autogenerate that info from git-describe(1). See how the Linux man-pages do it (in the links above you can see it) for example.It's not really about how to do it, more that I don't want to have a hard dependency on git for the script. I want it to run just as well when there's no Git repo around. But I can try to run "git describe" and fall back on the
Makefile(or on an empty version) if the command fails.
Yeah, I didn't mean it's a bug in the script, but seems to me like a bug in the kernel Makefile. If git fails because it's not present, there could be a fallback like "unknown-version". In the man-pages, when I prepare the tarball, with make dist, I hardcode the version in the pages. Maybe the kernel Makefile should have unreleased as the version in the git repo, and when a tarball is generated the Makefile should replace that unreleased version by the appropriate git version. Since git will not be found in the tarballs, that version will be used in that case. But when running from git, git-describe(1) should be preferred.
Quoted 2 lines
OK I'll prepare a new version, thanks for your help.
It's a pleasure!
Cheers,
Alex
Quoted 1 line
Quentin
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>