At 2022-08-19T20:03:23+0200, Jakub Wilk wrote:
> * G. Branden Robinson <g.branden.robinson@xxxxxxxxx>, 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.
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.
> $ 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.)
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
