Re: [Groff] Simplifying groff documentation

[Eric S. Raymond]

Gunnar Ritter <address@hidden>:
> > Well, does this mean that I should refrain from using any GNU
> > extensions in man pages?
> 
> Yes, I recommend that. As you know, I like most of them and
> have re-implemented them accordingly in Heirloom troff, so
> this is not an argument against groff extensions in general.
> But in manual pages, it is better to stick with traditional
> macros and simple requests. GNU extensions are not the only
> problem - even ".de" is better avoided.

While I agree with Gunnar's argument in general, I wouldn't go as far
as avoiding .de.  My doclifter is perfectly happy eating macro definitions
and expanding them, and the logic for this is simple enough that I think
we can reasonably expect other viewers to do likewise.

Having grappled with troff markup weirdness on 13,000 pages, and
written an interpreter for a a substantial part of troff within
doclifter, one of the things I am well equipped by experience to do is
describe a "safe troff" subset that we should recommend man-page
writers adhere to.

I think it might not be a bad idea for troff to throw warnings when
a man page uses a troff request outside the safe set.  Note that I 
am *not* recommending this measure for troff documents other than
man pages.

Here is the safe set:

.br .nl .sp .bp .ft .fi .nf .ul .cu .tm .so .ds .as .rm
.rn .em .am .nr .rr .ig .pm .cc .c2 .ab .do 

This is not all the requests doclifter interprets.  I also handle
.nop .return .mso .als .shift .fam, but recommend against putting
these in the safe set because heirloom troff and other viewers 
probably won't get them right.

The really big evil issue is .if/.ie/.el; I handle many cases of these 
correctly, but the logic to get evaluation of conditionals right is so
complex and the edge cases so nasty that these cannot in general be
in the safe set.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>