Hi Alex! At 2022-08-20T13:57:15+0200, Alejandro Colomar wrote: [migrating `TH` 4th argument to something like "Linux man-pages 5.13"] > 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. Yes. I endorse the above reasoning. > 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). Maybe the glory of seeing "Linux 6.0" in the footer of the bpf-helpers man page will inspire more kernel developers to follow that page's example. > 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> Looks reasonable to me, at a glace. > 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?). You've got a license named for you in SPDX now--you're stuck with it. ;) > 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. I would add " (in preparation)" to the string, and have the script that finalizes a release strip that out. But even if you go with the garrulous output of "git describe", I have good news. In groff 1.23, overlong header and footer material is abbreviated with an ellipsis. (This was an educational experience in string processing with groff.) Regards, Branden
Attachment:
signature.asc
Description: PGP signature
