Hi Branden, On 8/20/22 14:20, G. Branden Robinson wrote:
Hi Alex! At 2022-08-20T13:57:15+0200, Alejandro Colomar wrote: [migrating `TH` 4th argument to something like "Linux man-pages 5.13"]
[...]
Agree. LIBRARY seems much more appropriate for that purpose.Yes. I endorse the above reasoning.
Great. I'll get rid of the scripts for appending a COLOPHON. Should I keep the static part of the COLOPHON in a REPORTING BUGS section?And an even more general question? Should a manual page state the COPYRIGHT, AUTHORS, and REPORTING BUGS of the software it documents, or of the page itself, or both?
Ingo, I'm also interested in hearing you about this.
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.
That could help! :) Maybe we will see a future man9 section, even if autogenerated.
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.
I'll use "Linux man-pages (unreleased)" for the repo pages, just to be more similar to Debian's changelog format. I don't like inventing stuff if I don't need to. Does it make sense to you?
Having a fixed string there will be good, since that way I won't disturb the script updating the last-modified date.
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.)
Don't you like git-describe(1)? I like it. I'll check if it fits a normal terminal, and if so, I think I'll use it. If not, I'll think about it a bit more.
So, I'll have the Makefile produce this stuff, for both `make install` and `make dist`, and it will be produced in generated pages, but never modify repo ones.
Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
