Re: [groff] Regularize (sub)section cross references.

[John Gardner]

> Now arguably (for example, John Gardner said something like that)
> that syntax rule is an anachronism and has detrimental effects,
> for example confusing screen readers.

Just to clarify what Ingo's remembering — non-visual agents (braille
displays and speech-to-text programs) have no way of differentiating
acronyms from "CAPS AS HEADINGS"-style text. Many agents recognise very
common initialisms (like "RE:", "BBC:", "HTML", but the precise behaviour
depends on implementation.

In (modern) HTML, the correct way to achieve this is just:

<h2>Bugs</h2>


... with either of the following rules in your linked stylesheet(s):

h2 { text-transform: uppercase; }

h2 { font-variant: small-caps; }

... because HTML is for content, and CSS is for appearance and layout. =)
And, like Ingo mentioned, "LOUD, SHOUTING HEADINGS" are ultimately a relic
from the (tele)typewriter era.

The only justified use of ALL CAPS is in legal writing. Uppercase has
always been used to ensure significant terms stay conspicuous, irrespective
of medium.

On Sat, 15 Dec 2018 at 06:13, Ingo Schwarze <address@hidden> wrote:

> Hi Branden,
>
> again, thanks for your cleanup work...
>
> G. Branden Robinson wrote on Fri, Dec 14, 2018 at 10:46:57AM -0500:
>
> > commit a1b2ed16b3f8df2f3900365284a7d67003aca651
> > Author: G. Branden Robinson <address@hidden>
> > Date:   Fri Dec 14 09:37:24 2018 -0500
> >
> >     *.man: Regularize (sub)section cross references.
> [...]
> >     + Quote (sub)section names instead of setting them in bold or
> italics.
> [...]
> >     + Stop setting (sub)section names in all caps.  That is a
> presentational
> >       matter better decided in the implementation of the .SH and .SS
> macros.
> [...]
> >
> > diff --git a/contrib/gdiffmk/gdiffmk.1.man
> b/contrib/gdiffmk/gdiffmk.1.man
> > index 26532f0..1e20d47 100644
> > --- a/contrib/gdiffmk/gdiffmk.1.man
> > +++ b/contrib/gdiffmk/gdiffmk.1.man
> > @@ -102,9 +102,7 @@ Clearly both cannot be
> >  Note that the output is not necessarily compatible with all macro
> packages
> >  and all preprocessors.
> >  .
> > -See the
> > -.B BUGS
> > -section below.
> > +See section \(lqBugs\(rq below.
>
>  ... but i disagree with this particular change s/BUGS/Bugs/.
>
> There are two places in the specification of the manual page source
> languages (man and mdoc) where the grammar requires words in all caps:
>
>  1. the first argument of the .TH/.Dd macro
>  2. and all head arguments of the .SH/.Sh macro
>
> These are not presentational decisions, but rather syntax requirements.
> So the name of the standard section is "BUGS", not "Bugs".
>
> Now arguably (for example, John Gardner said something like that)
> that syntax rule is an anachronism and has detrimental effects,
> for example confusing screen readers.  So modernizing the syntax
> rules to allow ".SH See also" and rendering that as "SEE ALSO"
> in ASCII output (as a presentational decision) and as
>
>   <h1 class="Sh">See also</h1>
>
> in HTML output, recommending some CSS rule requesting small caps
> rendering for the .Sh class, likely makes sense.
>
> But such a change to the language definition needs a conscious
> decision, requires changes to all formatters (for making the required
> translations) and to all manual pages, and only after that can the
> fruits be collected.
>
> Note that, where a section title continues to be given in the
> tradtions ALL CAPS syntax, even after changing the rules, the
> formatter must not change it to normal or title case because it
> might contain e.g. acronyms that must remain in all caps (like
> "ASCII") or proper names where English spelling rules require
> capitalization.  Consequently, if we want to change the rules, all
> manual pages of all software packages must be edited.  Because that
> implies a huge amount of work for documentation maintainers, it
> probably ought to be discussed with the community of at least one
> operating system before being implemented in groff.
>
> Until that work is done, we have to call the BUGS section by its
> actual name, not by some imaginary variant that does not exist.
>
> Also, the change is detrimental because a user searching for the
> customary string BUGS in their pager will no longer find the
> reference to the section.
>
> As a side note, the syntax rule "must be all caps" only applies
> to .SH/.Sh.  The arguments to .SS/.Ss are traditionally given
> in title case or in sentence case.
>
>
> Finally, and less importantly, the traditional formatting for section
> and subsection refences is italics, just like for .UR/.MT/.Lk/.Mt,
> because section and subsection reference are essentially hyperlinks:
> words that the user is invited to click on are traditionally
> underlined, and in any case the formatting of ought to agree
> with that of .UR/.MT for consistency.
>
> Yours,
>   Ingo
>
>