Hi Branden, On Tue, Jan 14, 2025 at 09:15:04AM -0600, G. Branden Robinson wrote: > Hi Alex, > > At 2025-01-14T14:19:49+0100, Alejandro Colomar wrote: > > > @@ -95,8 +95,8 @@ .SS Title line > > > The arguments of the command are as follows: > > > .TP > > > .I title > > > -The title of the man page, written in all caps (e.g., > > > -.IR MAN-PAGES ). > > > +The title of the man page, written in lowercase (e.g., > > > +.IR man-pages ). > > > > Actually, > > To try to bring order to the chaos and confusion surrounding this > subject, I use the term "identifier". For consistency with "TH" (title heading?), I think I prefer "title". > groff_man_style(7): > • What’s the difference between a man page topic and identifier? > > A single man page may document several related but distinct > topics. For example, printf(3) and fprintf(3) are often > presented together. Moreover, multiple programming languages > have functions named “printf”, and may document these in a man > page. The identifier is intended to (with the section) uniquely > identify a page on the system; it may furthermore correspond > closely to the file name of the document. > > The man(1) librarian makes access to man pages convenient by > resolving topics to man page identifiers. Thus, you can type > “man fprintf”, and other pages can refer to it, without knowing > whether the installed document uses “printf”, “fprintf”, or even > “c_printf” as an identifier. > > > the title should follow the name of the page. > > I don't understand how the "name" is distinct from the "title" in your > usage. Name is "SH Name"; title is TH's $1; filename is the file name. > > it should be sentence case, > > I wouldn't apply that term here. A man page identifier (the first > argument to `TH`) will not be a sentence. Nor will comprise multiple > words separated by spaces. Not because it strictly could not, but > because it would be impractical to do so, and might expose bugs in man > page indexers like makewhatis(8) and mandb(8). Agree. > > or upper case, > > I advise this only when the identifier would be shouted in other > contexts, like X(7). > > > if the name is something like UTF-8, > > (by which you mean "uses code points outside the Basic Latin range") Nope. I meant UTF-8(7): $ find man/ | grep -i utf-8 | xargs grep -A1 -e ^.SH.N -e ^.TH .TH UTF-8 7 (date) "Linux man-pages (unreleased)" .SH NAME UTF-8 \- an ASCII compatible multibyte Unicode encoding Have a lovely day! Alex -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
