Re: Manual page sections shouting

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4379 bytes --]

Hi Branden,

On 1/7/23 11:17, G. Branden Robinson wrote:
> 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.  :)

Changing the section names is easy.  I already started.  The difficult part will 
be finding the references and changing them, which is more than sed -i, since 
I'll have to differentiate between actual references, and other things called 
NAME.  Also, depending on the context, I'll have to quote and prepend with 
"section" (if not already done), or keep it raw (for example in tables).

But yes, I think that seems a consistent-enough way of having references, so 
maybe the Linux man-pages will stop shouting rather soon :)

Cheers,

Alex

BTW, I had another similar concern about some global style fix of that sort 
while waking up.  Now I don't remember, but when I do, I'll send you an email :)

> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>

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