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

[John Gardner]

Hi Branden,

I'll reply to your query about pan-and-zoom transformations in another
thread, as I'm preparing a demo/preview to help explain what I mean. =)
Just responding to your other points:


>
>
>
> *the forced-full-capitalization of section titles in man page sources is
> aninformation-destroying transform done in the wrong place at the
> wrongtime.  Section headings should be capitalized as section titles
> normallyare in technical documentation: either like work titles, or
> first-letteronly, with the normal rules for proper nouns and adjectives
> respected*


I didn't bother explaining this to Ingo as I was shooting him down with his
mdoc-shaped abortions of mutated HTML and CSS mashups, and why he should
really just shut up about mandoc's "superior HTML output" when a Troff
preprocessor could generate more semantically correct and robust output.

But you're right. Writing stuff IN ALL CAPS is bad for assistive
technologies, because programs like screen-readers have no (sane) way of
distinguishing acronyms from, say, shouting or THAT LOUD LAWYER TALK you
often see in licenses and T&Cs.

That's why CSS has a dedicated property
<https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform> for
achieving this effect, without altering the underlying meaning or tone.

On 21 April 2018 at 17:06, G. Branden Robinson <address@hidden
> wrote:

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