Re: [Groff] Simplifying groff documentation

[Eric S. Raymond]

Werner LEMBERG <address@hidden>: 
> > 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.
> 
> Hmm.  This is doable by redefining the requests, but it means an
> update to the man macros each time I add something new.

I can imagine doing it with redefinitions, but I think it would probably
be best to write a troff-level hook that lets a macro package declare
a safe set to troff.

> > 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 
> 
> Thanks.  However, you haven't told us which escapes are `safe'.

I should have listed .de in the safe-request set as well.  That's an 
important one.

Safe escapes:  
     \' \- \$ \* \& \<SP> \<CR> 
     \c \d \e \f \u \n

Note that \w is *not* safe.  In general, we can't count on the viewer to be 
able to render horizontal or vertical motions with precision, we can't 
count on it to know font sizes, and we can't even count on it to know
whether its output uses fixed- or variable-width fonts.

> > 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.
> 
> Well, conditionals can't be avoided (see my other mail), I think, so I
> wonder whether you can go into details which evaluation cases cause
> problems.

This will take a little digging into the guts of my evaluator.  I'll get 
back to you on it.

On a related topic, there are a couple of man macro extensions that would go 
a long way towards eliminating the need for people to do ugly troff
hackery.  These are, by the way, macros for which there is much 
precedent in Unix usage:

.EX/.EE: Example displays:

.de EX
.nf
.ft CW
..
.de EE
.ft R
.fi
..

.DS/.DE: Displays for running text

.de DS
.nf
..
.de DE
.fi
..

To make these more useful, the start macros could take an optional
argument that is an indent for the display.  doclifter would not use the 
numeric value of the argument, but might translate differently depending on
whether an indent was specified or not.

With these in place, almost all of the uses of ,in, .ti, and .br in
my 13,000-page corpus could go away and be replaced by pure man macros.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>