On 01/08/2022 23:13, Alejandro Colomar wrote: > Hi Daniel, Hi Alejandro, I'm probably more familiar with this matter than Daniel, so let's see. > > On 7/22/22 00:50, patchwork-bot+netdevbpf@xxxxxxxxxx wrote: >> Hello: >> >> This patch was applied to bpf/bpf-next.git (master) >> by Daniel Borkmann <daniel@xxxxxxxxxxxxx>: >> >> On Thu, 21 Jul 2022 13:08:22 +0200 you wrote: >>> The Linux man-pages project now uses SPDX tags, >>> instead of the full license text. >>> >>> Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> >>> --- >>> scripts/bpf_doc.py | 22 +--------------------- >>> 1 file changed, 1 insertion(+), 21 deletions(-) >> >> Here is the summary with links: >> - bpf_doc.py: Use SPDX-License-Identifier >> https://git.kernel.org/bpf/bpf-next/c/5cb62b7598f2 >> >> You are awesome, thank you! > > Oh, what a nice bot :) > > > I've been running a linter on the man-pages, and had this triggered from > bpf-helpers.7: > > [ > $ make lint V=1 > LINT (groff) tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch > groff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww -z > man7/bpf-helpers.7 > an.tmac:man7/bpf-helpers.7:3: style: .TH missing third argument; suggest > document modification date in ISO 8601 format (YYYY-MM-DD) > an.tmac:man7/bpf-helpers.7:3: style: .TH missing fourth argument; > suggest package/project name and version (e.g., "groff 1.23.0") > an.tmac:man7/bpf-helpers.7:3: style: .TH missing fifth argument and > second argument '7' not a recognized manual section; specify volume title > found style problems; aborting Not sure I understand this last one. Isn't "7" a valid man section? > make: *** [lib/lint-man.mk:49: > tmp/lint/man7/bpf-helpers.7.lint-man.groff.touch] Error 1 > > ] > > See what a normal .TH line looks like, and what bpf-helpers.7 has: > > [ > $ grep ^.TH man2/bpf.2 > .TH BPF 2 2021-08-27 "Linux" "Linux Programmer's Manual" > $ grep ^.TH man7/bpf-helpers.7 > .TH BPF-HELPERS 7 "" "" "" > ] > > > I don't know if you can fix that, or if it's a limitation of the > generator? I can live with it, but it would be nice if it could be > fixed. It provides the headers and footers of the manual page. I had never really looked into completing this line before, but it seems that Docutils/rst2man has a few (albeit not much documented) docinfo elements available to complete _some_ of these fields. We currently have ":Manual section: 7" in the generated page. I can generate a page close to the result above with: :Manual section: 7 :Manual group: Linux Programmer's Manual :Version: Linux :Date: 2022-08-02 With these fields, I get: .TH BPF-HELPERS 7 "2022-08-03" "Linux" "Linux Programmer's Manual" Caveats: First, we get additional double quotes around the date, not sure if this matters. Second: “Version” does not seem a relevant field name in that case, but this is apparently the only option that we have to insert a value at this location [0]. Apparently the manpage writer for Docutils assumes that this line contains a version number [1]. Third: The date should of course be updated when generating the page. I found that rst2man has a "--date" option, but it does not insert it at the location we want. Instead, it would probably be a matter of adding a sed command to the pipeline, something along: $ ./scripts/bpf_docs.py helpers | \ sed -e "s/__DATE__/$(date -I)/" | \ rst2man | man -l - If it looks better for the man-pages repo, I can send a patch for the man-page template in bpf_docs.py to set ":Manual group:" and ":Version:". I can also ask on the docutils mailing list if there is a cleaner way to proceed, without falling back to this ":Version:" field. Regards, Quentin [0] https://repo.or.cz/docutils.git/blob/f031167579bdbe30781ea51d516d14db2cb5f60e:/docutils/writers/manpage.py#l377 [1] https://docutils.sourceforge.io/docs/user/manpage.html
