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

[Larry Kollar]

> On Dec 14, 2018, at 2:13 PM, Ingo Schwarze <address@hidden> wrote:
> 
> G. Branden Robinson wrote on Fri, Dec 14, 2018 at 10:46:57AM -0500:
> 
>> […]
>> .
>> -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”.

I would characterize it as more of a convention. If “man” doesn’t
throw an error on a mixed-case .SH (and it doesn’t on my system),
then it’s a style requirement and not one enforced by the software.
Maybe it’s enforced in mdoc? I’ll take Ingo’s word as authoritative.

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

Personally, I think it’s worth the effort. As others have pointed out,
the ALL CAPS convention is dated, shouty, and no longer necessary.
I’m willing to help out where needed. In the corner cases where
someone is still using a dumb terminal (or a really dumb emulator),
an environment variable could trigger the macro package to go
old-school and transform the .SH arguments to all-caps.

If anyone has the leverage to modernize manpages, it’s the groff community.

        Larry