[Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Werner LEMBERG <address@hidden>:
> It seems that we can do a decent job by adding a small set of
> additional macros to man; this would have the benefit of getting a
> clear conversion with doclifter, and a standardized interface for
> future man pages (which current ones might adopt also).

Agreed.

I know Gunnarr has concerns about macros we might add going unused, but I
have some ability to influence that.  I've successfully pushed over
200 man-page patches upstream to different projects.

> > > BTW, what about -mdoc?
> > 
> > That would work fine, as long as you don't have to use .Xo/.Xc;
> > doclifter has a weakness there, and it's one that I fear is not
> > going to be easy to fix.
> 
> Interesting.  Is there something on the groff side we could do to
> improve that?

I will investigate, but off the top of my head I think the answer
is no.  Fixing the problem on the troff end would probably require
complicated changes that would be difficulyt to make backward-compatibly.
 
> > I think -mdoc is one of the two feasible solutions we are converging
> > on.
> 
> Well, this means a lot of work and should be done perhaps only for man
> pages which would look really ugly otherwise.
> 
> > The other would be to define .OP and .SY as discussed in previous 
> > email, and teach doclifter to interpret those.
> 
> Yep.

I will further note that teaching doclifter to interpret .OP and .SY
would be extremely easy -- as in, done and tested ub 20 minutes or less.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>