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

[Ingo Schwarze]

Hi Larry,

Larry Kollar wrote on Sat, Apr 21, 2018 at 10:44:43AM -0400:

> I'm in violent agreement with your and Brandon's assessment
> of all-caps headings.  Shoot, there aren't many
> terminal programs that *can't* do bold these days;
> I think even that VT220 I keep
> planning to connect to my iMac can do it.
> 
> Given a choice, I never all-caps my manpage headings.

Not a real problem, your pages are still readable and correct -
and you argue they are even more readable and nicer.  Fair enough.

Some parsers may warn, including mandoc:

mandoc: <stdin>:1:5: STYLE: lower case character in document title: Dt foo
mandoc: <stdin>:1:5: STYLE: lower case character in document title: TH foo

But it's only flagged as a STYLE level issue, meaning that there
is no ambiguity, portability, or formatting problem.

> I've succumbed to convention once or twice, maybe.
> It would be cool if man(1) could recognize an all-caps string
> flush left, and turn it into bolded title case.

Err, no, serious layering violation alert.  In implementations
were the formatter and man(1) are separate programs, the man(1)
utility should please *not* try to change the formatting, not
even in a well-intentioned way.  It should only display the
rendered version it got, unchanged.

The formatter can't do the tranformation either: once the case of
some string was clobbered into ALL CAPS, going back programmatically
is impossible, information was lost.  For example, the OpenBSD
ipsec.conf(5) manual contains

  .Sh IPSEC.CONF FILE FORMAT

and it might contain

  .Sh IPSEC AUTOMATIC KEYING

No formatter can figure out that the correct capitalization is

  .Sh ipsec.conf file format
  .Sh IPsec automatic keying

I'm not necessarily opposed to getting rid of this antiquated
convention (though i would have to check with Jason, who sometimes
is aware of arguments that i miss), except that i would probably
be the poor guy who would have to edit thousands of manual pages,
a process that can only partly be automated and certainly requires
checking all of them by hand.

You will understand that while i see the point why the convention
is not good - and even worse for .TH and .Dt than for .Sh - i'm not
thrilled by the idea of getting rid of it so late in the game, for
the sheer volume of churn it would cause.

Yours,
  Ingo