Re: Standardize roff

[Ingo Schwarze <schwarze@usta.de>]

Hi San,

Sam Varshavchik wrote on Sun, Aug 14, 2022 at 08:20:34PM -0400:
> Ingo Schwarze writes:
>> DJ Chase wrote on Sat, Aug 13, 2022 at 05:27:34PM +0000:

>>> Have we ever considered a de jure *roff standard?

>> No, i think that would be pure madness given the amount of working
>> time available in any of the roff projects.

> I tinkered with something like this some years ago, but I took a slightly  
> different approach.
> 
> I converted man pages

What kind of manual pages?

> from 'roff source to Docbook XML using a … pretty large Perl script.

That sounds very foolish on several levels.

First, and most obviously, you seem to be duplicating esr@'s work
on doclifter:

  http://www.catb.org/~esr/doclifter/
  https://gitlab.com/esr/doclifter/-/blob/master/doclifter

Second, quick and dirty Perl-style parsing is usually not good
enough to parse roff code, and a huge script is not particularly
good for readability and maintainability.

Yes, i know the same resevations would apply to esr@'s work,
which is a giant Python 3 script.  But at least there is some
evidence that his work was able to find significant numbers of
real issues in real manual pages.

> Once a year, or so, when I have nothing better to do I pull the current
> man  page tarball and reconvert it. I usually need to tinker the Perl
> script, here and there, each time.
> 
> The Docbook folks provide a stylesheet that converts Docbook XML
> back to 'roff.

Yikes.  That thing is by far the worst man(7) code generator existing
on this planet.  If at all possible, you should avoid that toolchain
like the plague.

It is so bad that for years, bogus reports caused by that totally
broken toolchain have caused the majority of invalid mandoc bug
reports.

> The end result you get is standardized 'roff, whatever that means.

Absolutely not.  The result is utter crap.  It is rarely even
syntactically valid, let alone reasonable style.

> But, yes, the effort require to clean up and standardize the formatting
> of man pages would be mammoth. There's more inconsistency across the
> various man pages, from various sources, than consistency.

That isn't completely untrue, but all the same, mandoc copes well
enough with more than 95% of valid real-world manual pages, and groff
with 100%.  In a nutshell, the only stuff that breaks with groff
is manual pages that are completely invalid, usually coming from
the official DocBook XML toolchain, and in rarer cases coming from
other broken man(7) generators.

All this is barely related to the question of standardizing roff(7),
though.  Roff is much more than manual pages.

Yours,
  Ingo