[Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Werner LEMBERG <address@hidden>:
> > I don't want to go down a technical rathole of adding complexity and
> > not actually solving the problem.  Gunnar shows us that the real
> > problem here is these special macros are too complicated for
> > anything but groff to interpret.  That's the issue that needs to be
> > fixed, not kluged around with excessive cleverness in my software --
> > even if the cleverness would be fun for me to implement.
> 
> We are getting nearer.  I can live with what you say above.
> However...
> 
> > So by inserting a few .br requests in the Synopsis section, I can
> > both mostly restore the visual appearance of the Synopsis in troff
> > output and duplicate it rather closely in generated HTML.
> 
> ... this is too simplistic IMHO.  See my other mail.

Yes.  I grant your point there.
 
> I want a presentation which works equally well for all output devices.
> I'm willing to restrict the involved macros to something doclifter can
> understand (and this stuff could be then documented properly in a
> guide).

That would be a large step in a good direction, and one that would
benefit other viewers as well and make Gunnarr happy.  I will
cooperate by helping you develop the "safe set" and helping write the
guide to it, and by enhancing doclifter in any way that's reasonable
to keep that safe set from being too restrictive.

Excellent.  I think we can see a way forward beginning to emerge.

> > Bernd's experiment art getting to structural level was a good try,
> > but it creates more problems than it solves.
> 
> Probably you are right.  BTW, what about -mdoc?  This package has a
> much richer set of commands, and there is rarely a need to define a
> command by yourself.  And it can produce nicely formatted SYNOPSIS
> sections without the aid of low-level groff stuff.  Perhaps I shall
> convert some of the problematic man pages to that format...

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.

I think -mdoc is one of the two feasible solutions we are converging on.
The other would be to define .OP and .SY as discussed in previous 
email, and teach doclifter to interpret those.

I don't have a strong feeling about which would be better.  I guess I
lean a little towards .OP/.SY; I think it's simpler.  But I would 
cheerfully do the work necessary for either path.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>