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 <g.branden.robin...@gmail.com> > 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
