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

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- 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 --]