Re: [Groff] Defect patterns in real-world man-pages

[Peter Schaffter]

On Wed, Mar 05, 2014, Eric S. Raymond wrote:
> Here are some facts about the defect patterns that I think are interesting:
> 
> * There's a perceptible correlation between the origin date of a
>   page and the (closely correlated) complexity and defect density of
>   its markup.  Older pages have more complex and more troff-aware 
>   markup, with more bugs. Newer pages use fewer troff-level requests
>   and have fewer bugs.

A natural evolution, methinks, as earlier generations of manpage
authors were more familiar with troff generally.  As troff started
its slide into "just use it to write manpages", most of the newer
folk stuck to what's easy, namely the supplied macros.  No time and
no inclination to delve into the guts to tweak stuff.
 
> * The single most wretched hive of scum and villainy throughout the
>   corpus is the markup for command synopses.  There are no semantic
>   macros for these, so people come up with endlessly inventive and
>   perverse ways to make them come out right presentationally.

That "endlessly inventive" side of groff is one of its greatest
strengths.  Not so sure about "perverse", though I well understand
your feelings. :)

> * No matter which distro you choose or how many packages you add, the 
>   percentage of man pages that pass strict validation by doclifter 
>   in their unaltered form now hovers at around 93%.

Unbelievable.

> What's interesting is that the resulting cleaned-up man markup uses a 
> remarkably small set of low-level groff requests, and employs those
> in very stereotyped ways.

Precisely what's to be expected.  The more responsive the macros,
the less need for presentational intervention.

> Note, by the way, that groff's own pages are the single worst and
> nastiest exceptions to this general rule of simplicity.  There are
> impacted layers of hideous macrology in there, only some of which I
> have successfully simplified to something reasonable.

Again, no surprise.  We all *know* groff.

"Hideous macrology" sounds positively Satanic!
 
> Now I hope it is clearer why I have begun to think in terms of
> actually enforcing hygienic macro use and blocking out low-level
> requests.  What can be done by social-engineering page maintainers
> into cleaning up their acts voluntarily has in fact been done already,
> with considerable success.  It only took me more than ten years of
> grinding at the problem!

Again, hard to believe.

> The remaining holdouts are going to need a boot up the butt to
> overcome their inertia.

You may have reached the law of diminishing returns stage.

-- 
Peter Schaffter
http://www.schaffter.ca