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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3549 bytes --]

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@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.

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]