[Groff] Re: Simplifying groff documentation

[Werner LEMBERG]

> 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.

> It would take the markup on these pages back down towards
> presentation level, yes -- but as a matter of reality troff is
> irremediably stuck there anyway.

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).

> 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...


    Werner