[Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Werner LEMBERG <address@hidden>:
> > 1) It would address the issue by adding complexity to the markup and
> >    the interpretation path, rather than subtracting it.
> 
> Not necessarily.  Currently, you are applying doclifter's heuristic
> engine to guess a high-level structure of a man page (cf. the example
> w.r.t. embedded C code snippets you've given in another mail).  The
> markup in some groff man pages is already doing this -- it implements
> macros which gives you those high-level markup!  With other words, a
> regexp solution would provide a direct translation instead of reduced
> markup followed by educated guessing.

I said I kind of liked the idea.  But it still won't solve the only visible 
problem created by reducing to standard man markup, which is losing
some polish on the synopsis.  

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.
 
> > 2) It won't solve the problem someone else in this thread pointed
> >    out, which is that the nonstandard macros break other viewers,
> >    including older *roff versions.
> 
> This, admittedly, is a valid argument.  But it leads to nowhere IMHO.
> It's the same as with HTML -- I'm sure there are still browsers which
> can't display HTML 4 correctly...

Case isn't parallel.  The overwhelming vast majority (99.007% of pages
in my 13,000-page sample) are "HTML 3".  It's definitely the eight 
groff pages that are the outlier here.

Nevertheless, I might tend to agree with your dismissal if the only
issue were legacy Bell Labs troff, but more modern viewers like TkMan
handled these well.  But Gunnar reminds us that isn't the case.
Having grappled with it myself, I grasp the scope of the problem --
there is no realistic chance that *any* viewer other than groff itself
will ever render these pages correctly,
 
> > 3) It won't solve the actual problem with the simplified markup,
> >    which is the command synopsis not looking as nice.
> 
> Well, this is something different, I agree.  What's your suggestion to
> improve this?  Is it possible at all to write troff code (not
> necessarily man markup) so that doclifter can display something nicer?

Yes.  In command synopses only, the troff request .br is translated
into a special <sbr/> tag that forces a line break.  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 the way forward that I recommend.  Strip the pages down to
statandard man markup, and add some judicious .br and .in tags to fix up
the appearance of the Synpsis sections.  This would solbe my problem,
and it would solve Gunnar's problem, without a lot of added 
complexity in the code path.

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.  Bernd's experiment art getting to structural level was
a good try, but it creates more problems than it solves.

> I've misunderstood you.  Apparently, you don't plan to write a
> `lifting' engine by yourself to handle texinfo, right?

No.  Someone else has already done most of that work, there's a 
makeinfo --docbook option.  It doesn't work quite right, but fixing
it would definitely be easier than messing with groff-texinfo.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>