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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sat, Apr 21, 2018 at 03:06:14AM -0400:
> At 2018-04-20T23:19:44+0200, Ingo Schwarze wrote:
>> John Gardner wrote:
>>> 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,

True.  The convention "write the first argument of .TH, .Dt,
and all arguments of .Sh in ALL CAPS" is a premature presentational
decision.

> 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

I strongly agree with that: once done, it cannot be undone.

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

I mildly agree with that sentiment, as explained in my other
posting - except for the large amount of work it would cause me.

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

So what?  With two explicit OKs - namely, from Michael Kerrisk and
Jason McIntyre - i would switch that right away and not even provide
a knob for people to turn.  Let them be shocked.  Things change.

The problem is, i have to change several thousand manual pages first
even if we all agree it would be nice to have - is that amount of
work well invested, or are there more important things to do?


The point at *this* point of the thread is a *completely*
different one:  HTML anchors are not only used for section
headers, but also for command names, function names, variable
names, and many other syntax elements where case is no doubt
syntactically important.  So as long as the section name
appearing in a specific manual page is "EXIT STATUS", the
anchor has to be exactly that, and no case variation.

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

Yours,
  Ingo