On 23/08/2022 13:26, Alejandro Colomar wrote: > 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> Wow, I'm two days late! > > 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)? 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
