Re: Manual page sections shouting

[G. Branden Robinson]

Hi Alex!

At 2023-01-07T01:25:50+0100, Alejandro Colomar wrote:
> I agree with you that I'd prefer that section headings didn't shout at
> the reader.  However, I've waited to do such a change, because I'm not
> sure about it.  There's a good thing about having them in uppercase:
> references to them are also in uppercase, and that makes it easy to
> grep for them (I need to do that from time to time).
> 
> Do you have any opinion on that?

Yes.  :)  Section headings are still in sentence case (capitalize first
letter) or title case (capitalize each word except for a fuzzy list of
exceptions even native English speakers struggle to master).

Whether sentence or title case is used is a style choice that I don't
have a prescription for.  In the groff man pages, after some discussion
on the list we migrated to sentence case.  As I recall there was at
least one advocate for title case for section headings proper (`SH`) and
sentence case for subsection headings (`SS`).

The distinction is almost invisible for standard section headings
anyway; the only common multi-word heading is "See also"; that one is
practically never cross referenced, and it's almost always easier to
find by just mashing Shift+G in the pager.

If you type "-i" in less(1), this will toggle case-insensitive pattern
matching.  You can then search for the section name with a leading
capital letter; that is usually reliable for detecting the headings, or
cross references to them.

> Also, when referring to the section within a page, would you refer in
> lowercase, or the first-upper-then-lower?  Using uppercase is
> unambiguous,

That's true, albeit shouty.

> while using lowercase might need "section" next to the section name.

In the groff man pages I have adopted the practice of always preceding
the cross reference with "section" or "subsection" as appropriate, and
quoting it with typographer's quotation marks (\(lq and \(rq).

I go to the trouble of distinguishing sections from subsections because
they are by default indented differently, and that gives people,
especially those with a little facility with regular expressions,
another tool with which to locate the relevant material.

For instance, the following rules of thumb are crude but effective:

Find a section named "Options" in a page:

/^Options

Find a subsection named "History" in a page:

/^   History

(where 3 spaces lie between ^ and "History").

_If_ we added yet another groff extension to man(7), analogous to
mdoc(7)'s `Sx`, we could support hyperlinks directly to man page
sections and subsections.  (On terminals, we'd still need a way to mark
locations in the page text as link targets, and for it to be practically
useful, pagers would have to grow more features.  Given the amount of
idiocy, particularly from people who think that a URL in a terminal
window is a security risk in some way that a URL on a web page isn't,
that Egmont Koblinger has had to put up with in promulgating OSC 8, I
would not count on the infrastructure for this materializing soon.)  But
for PDF all the pieces are in place; they just need some glue in the
groff man(7) package.

> Maybe it's not so easy to do the change.

Changing the lettercase of the (sub)section headings in groff's ~60 man
pages was not difficult.  "sed -i" was equal to the task.  :)

Regards,
Branden

signature.asc
Description: PGP signature