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

[Ingo Schwarze]

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