.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: 5206 bytes --]

Hi Branden,

On 8/20/22 07:43, G. Branden Robinson wrote:
> At 2022-08-19T20:03:23+0200, Jakub Wilk wrote:
>> * G. Branden Robinson <g.branden.robinson@gmail.com>, 2020-09-30 20:12:
>>> +\(bu Do I ever need to use an empty macro argument ("")?
>>> +Probably not.
>>
>> FWIW, man-pages(7) says it's OK to use empty string for the 4th
>> argument of .TH:
>>
>> "For library calls that are part of glibc or one of the other common
>> GNU libraries, just use GNU C Library, GNU, or an empty string."
>>
>> There used to be a lot of such .TH calls; now there's only a few left:
> 
> In my opinion it would benefit readers of the Linux man-pages if the
> fourth argument to `TH` were what it is in many other man pages: an
> identifier for the name and version number of the release originating
> them.  In every page it would be clear what version of the man-pages was
> being viewed.  Little sophistication would be demanded of the user to
> check the Web to determine the relative age of the pages, independently
> of the modification date of the particular page.  Such usage would be
> congruent with the argument's purpose in AT&T and BSD Unix, where this
> datum was "7th Edition", "System III", or "4.2 Berkeley Distribution",
> or similar.

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.

And this helps remove the COLOPHON section (or at least, we don't need 
to autogenerate it, since the version number now comes in .TH, and the 
COLOPHON is static; so I can even move it to a smaller REPORTING BUGS 
section).

> 
>> $ grep -r '[.]TH .*""' man*/
>> man7/posixoptions.7:.TH POSIXOPTIONS 7 2021-08-27 "" "Linux Programmer's Manual"
>> man7/bpf-helpers.7:.TH BPF-HELPERS 7 "" "" ""
>> man8/zdump.8:.TH ZDUMP 8 2020-04-27 "" "Linux System Administration"
>> man8/zic.8:.TH ZIC 8 2020-08-13 "" "Linux System Administration"
> 
> The replacement fifth arguments above seem pointless, and in the case of
> bpf-helpers(7), downright unhelpful.
> 
>         .TH title section [footer‐middle] [footer‐inside] [header‐middle]
> [...]
>                If section is a simple integer between 1 and 9
>                (inclusive), there is no need to specify header‐middle;
>                an.tmac will supply text for it.
> 
> However, I realize that bpf-helpers(7) is generated from another format,
> and so code would have to be written to more usefully populate 2 of the
> 3 blank fields.  (I would leave the third unspecified instead of making
> it explicitly empty.)

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


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>


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?).  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.

Cheers,

Alex
-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]