Hi Quentin, On 8/2/22 12:28, Quentin Monnet wrote:
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; abortingNot sure I understand this last one. Isn't "7" a valid man section?
It is a valid section. I don't understand it either. Maybe groff(1) has gone crazy after so many errors. I'll report a bug to groff.
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.
Nah, quotes are only for spaces (they are ignored in this case). You're fine with or without them.
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].
That field seems to be different, depending on who you ask.In most cases, it's a "project and version" (see for example the groff warning text).
But in the linux man-pages, since we cover many projects and versions, we just say which project we're documenting (to avoid having to update the version every time, I guess).
See man-pages(7):
[
Title line
The first command in a man page should be a TH command:
.TH title section date source manual
The arguments of the command are as follows:
[...]
source The source of the command, function, or system
call.
For those few man‐pages pages in Sections 1 and 8,
probably you just want to write GNU.
For system calls, just write Linux. (An earlier
practice was to write the version number of the
kernel from which the manual page was being writ‐
ten/checked. However, this was never done consis‐
tently, and so was probably worse than including
no version number. Henceforth, avoid including a
version number.)
For library calls that are part of glibc or one of
the other common GNU libraries, just use GNU C Li‐
brary, GNU, or an empty string.
For Section 4 pages, use Linux.
In cases of doubt, just write Linux, or GNU.
[...]
]
So, just saying ':Version: Linux' would be fine.
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 -
The date, yeah, I can add it to the pipeline.BTW, I reported a bug to rst2man (I CCd you, so you probably already know :)).
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.
Yeah, please patch :Manual group:. Also patch :Version: (I think we can live with it), although of course feel free to ask about better alternatives to it.
But don't patch :Date: yet. Let's see what they answer to the bug report. (And if you want, you can wait for the bug report to resolve to patch everything at once, of course.)
Cheers, Alex
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
-- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
