Hi Branden, On 8/20/22 07:43, G. Branden Robinson wrote:
At 2022-08-19T20:03:23+0200, Jakub Wilk wrote:* G. Branden Robinson <g.branden.robinson@xxxxxxxxx>, 2020-09-30 20:12:+\(bu Do I ever need to use an empty macro argument ("")? +Probably not.FWIW, man-pages(7) says it's OK to use empty string for the 4th argument of .TH: "For library calls that are part of glibc or one of the other common GNU libraries, just use GNU C Library, GNU, or an empty string." There used to be a lot of such .TH calls; now there's only a few left:In my opinion it would benefit readers of the Linux man-pages if the fourth argument to `TH` were what it is in many other man pages: an identifier for the name and version number of the release originating them. In every page it would be clear what version of the man-pages was being viewed. Little sophistication would be demanded of the user to check the Web to determine the relative age of the pages, independently of the modification date of the particular page. Such usage would be congruent with the argument's purpose in AT&T and BSD Unix, where this datum was "7th Edition", "System III", or "4.2 Berkeley Distribution", or similar.
I thought about it in the past... That field was the only thing that said where a function came from. If we removed GNU (or something else), how would someone know where does the function or whatever comes from??
I guess that's also why the colophon was appended to the pages by Michael. Since we couldn't use the 4th field for that, we had to have a COLOPHON section.
However, the addition of the LIBRARY section seems to fix this issue, and so now we have an even more precise way to determine where a given function comes from (including the library file name, and the linker option).
This gives me another argument for those who don't like to have a LIBRARY section for libc stuff (since -lc is unnecessary), and consider it noise.
Further, as the libc-related man pages in this project expand coverage to other libcs than GNU's, the alternatives to the empty string proferred in man-pages(7) seem less and less appropriate.
Agree. LIBRARY seems much more appropriate for that purpose.And this helps remove the COLOPHON section (or at least, we don't need to autogenerate it, since the version number now comes in .TH, and the COLOPHON is static; so I can even move it to a smaller REPORTING BUGS section).
$ grep -r '[.]TH .*""' man*/ man7/posixoptions.7:.TH POSIXOPTIONS 7 2021-08-27 "" "Linux Programmer's Manual" man7/bpf-helpers.7:.TH BPF-HELPERS 7 "" "" "" man8/zdump.8:.TH ZDUMP 8 2020-04-27 "" "Linux System Administration" man8/zic.8:.TH ZIC 8 2020-08-13 "" "Linux System Administration"The replacement fifth arguments above seem pointless, and in the case of bpf-helpers(7), downright unhelpful. .TH title section [footer‐middle] [footer‐inside] [header‐middle] [...] If section is a simple integer between 1 and 9 (inclusive), there is no need to specify header‐middle; an.tmac will supply text for it. However, I realize that bpf-helpers(7) is generated from another format, and so code would have to be written to more usefully populate 2 of the 3 blank fields. (I would leave the third unspecified instead of making it explicitly empty.)
For the date, I already reported a bug to rst2man(1). For the 4th field, I guess we should specify Linux kernel and version (so I should patch the kernel to pass that info to us).
Now that I'm convinced to fix the 4th argument as something like "Linux man-pages 5.13" for all pages, I'd like you to help on this.
The script for replacing them all was easy. I produced the following temporary commit in my tree:
All pages: Replace the 4th argument to .TH by "Linux man-pages <version>"
Scripted change:
$ find man* -type f \
|xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\)
\+"[^"]\+"/\1 "Linux man-pages 5.13"/'
$ find man* -type f \
|xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\) \+[^"
]\+/\1 "Linux man-pages 5.13"/'
Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx>
Now, we should decide what to put exactly in that field, and when/how to
generate it.
The project name, I think it's clear that it should be "Linux man-pages" (are there any voices against?). As the version, for releases it also seems clear: the version number; but what about unreleased pages?should I write a generic placeholder? Or maybe keep the last version number? Or maybe put the expected next version number (that's risky). Or put the git version (i.e., man-pages-5.19-rc1-173-g6620898d3)? The git version would be the most precise, but it's also the most complex to do: I'd need to modify the _installed_ pages, since of course I'm not going to edit the original pages with that info.
Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
