[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [groff] groff as the basis for comprehensive documentation?
From: |
John Gardner |
Subject: |
Re: [groff] groff as the basis for comprehensive documentation? |
Date: |
Sat, 21 Apr 2018 17:15:44 +1000 |
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
>
- Re: [groff] groff as the basis for comprehensive documentation?, (continued)
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/20
- Re: [groff] groff as the basis for comprehensive documentation?, Steffen Nurpmeso, 2018/04/20
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/20
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/20
- Re: [groff] groff as the basis for comprehensive documentation?, Larry Kollar, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/22
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/22
- Re: [groff] groff as the basis for comprehensive documentation?, G. Branden Robinson, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?,
John Gardner <=
- Re: [groff] groff as the basis for comprehensive documentation?, Nate Bargmann, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Nate Bargmann, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, James K. Lowden, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, G. Branden Robinson, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/22