Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

Alejandro Colomar
2022-08-20T12:41:25Z

[-- Attachment #1.1: Type: text/plain, Size: 3902 bytes --]

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@gmail.com>
>
> 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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]