Re: [groff] groff as the basis for comprehensive documentation?

[G. Branden Robinson]

At 2018-04-20T23:19:44+0200, Ingo Schwarze wrote:
> >> man://mandoc.1#EXIT_STATUS
> 
> > Now, as for the SHOUTY SHOUTY...
> 
> That's not a matter of SHOUTING, but of case sensitivity.
> The name of that standard section in man(7) and mdoc(7)
> is "EXIT STATUS", not "Exit Status" nor "Exit status"
> nor "exit status".  Case is preserved, consider:

> That's a bad idea.  I admit that many authors use unusual and even
> inconsistent casing in section headers (even in the very mandoc.1)-:,
> which may sometimes seem awkward.  But in technical documentation,
> casing is often deliberate, and automatically changing it based on
> natural language rules is prone to make information incorrect in
> some cases.

I disagree with most of this analysis.  As far as I can tell this was a
presentational decision, similar to the one that led to the Unix
trademark being shown in small caps.  I don't recall the reference but
the reason was not because Unix was supposed to be in full caps--it's
not an acronym, after all--but just to show off a fancy font on the
typesetter.

In my opinion, which I am far too young and poorly-connected to have
proffered when it would have made any difference, the
forced-full-capitalization of section titles in man page sources is an
information-destroying transform done in the wrong place at the wrong
time.  Section headings should be capitalized as section titles normally
are in technical documentation: either like work titles, or first-letter
only, with the normal rules for proper nouns and adjectives respected.

It would be better if man-db (or similar) set a *roff variable
that the macro package would check to see if case transformation on
section headings was desired.  The default, for the next n years, of
course, would be to go ahead and do the transformation to avoid shocking
people.

This has been itching me for many years; thanks for the excuse to air
my grievance.  ;-)

-- 
Regards,
Branden

signature.asc
Description: PGP signature