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:

quoted

quoted

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

quoted

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.

quoted

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.

quoted

or upper case,

I advise this only when the identifier would be shouted in other
contexts, like X(7).

quoted

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/>