Manual page sections shouting

Manual page sections shouting

[Alejandro Colomar]

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

Hi Branden,

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?

Cheers,

Alex

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

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

Re: Manual page sections shouting

[Alejandro Colomar]

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



On 1/7/23 01:25, Alejandro Colomar wrote:
> Hi Branden,
> 
> 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?

Also, when referring to the section within a page, would you refer in lowercase, 
or the first-upper-then-lower?  Using uppercase is unambiguous, while using 
lowercase might need "section" next to the section name.  Maybe it's not so easy 
to do the change.

> 
> Cheers,
> 
> Alex
> 

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

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

Re: Manual page sections shouting

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3410 bytes --]

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

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

Re: Manual page sections shouting

[Alejandro Colomar]

[-- 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 --]

Re: Manual page sections shouting

[Lennart Jablonka]

Quoth G. Branden Robinson:
>_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.

Surely man(1) and man(7) could coorperate to produce a tags file that 
could be used by a pager.  On OpenBSD, you can use less(1)’s :t to jump 
to a bunch of stuff in a man page.

-- 
Lennart

modal man(7) extensions for groff and man-db man(1) (was: Manual page sections shouting)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1564 bytes --]

Hi Lennart,

At 2023-01-10T17:21:54+0000, Lennart Jablonka wrote:
> Quoth G. Branden Robinson:
> > _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.
> 
> Surely man(1) and man(7) could coorperate to produce a tags file that
> could be used by a pager.  On OpenBSD, you can use less(1)’s :t to
> jump to a bunch of stuff in a man page.

I like this idea.  It meshes well with another I've had to eliminate the
necessity for lexgrog(1) by supporting a mode (selected by a register or
string specified at formatting time) where the page formats the contents
of the "Name" section, and _only_ that, and exits (technically, `nx`es).

It would be up to man(1) to stuff the tag output into a temporary file
and tell less(1) to use it, but that sort of thing is consistent with
its existing feature set, I think.

Regards,
Branden

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