Re: <OK> [Groff] Simplifying groff documentation

[Michael(tm) Smith]

"Eric S. Raymond" <address@hidden>, 2006-12-23 00:56 -0500:

> Well, no, actually.  DocBook -> man is easy -- you're throwing away
> structure when you do that.  man -> DocBook is *hard*, because you have 
> to deduce semantic structure from presentation-level cliches.  

DocBook -> man may be easy in terms of not needing to preserve
structure. But it's not particularly easy in other ways --
especially since the most likely way to do it is with XSLT, and
XSLT (well, XSLT 1.0 at least) has some serious limitations as a
programming language, and those limitations can make it a real
chore do certain things that are dead simple in most other
languages (string manipulations, regex string replacements,
storing and retrieving data in/from data structures).

And then there's handling of whitespace, which is a notorious
issue in XML processing. It's not much of a problem when doing
XML-to-XML or XML-to-HTML conversion, but it is a big and ugly
PITA when doing the XML-to-text conversion that's needed for
generating *roff output from DocBook source.

The are some other challenges -- like how to handle things like
footnotes and hyperlinks in *roff output -- but those are fun in
comparison.

> In fact, consensus among the world's DocBook mavens was that this was
> impossible to pull off -- before I, er, did it.  It required an unusual
> combination of advanced compiler-jockery, familiarity with certain AI
> techniques, and sheer bloody-minded persistence. 

I'm not sure if I'm a DocBook maven but I will admit that I was
among those that didn't think it could be done well. But I have to
say now that I think doclifter is a mighty piece of work indeed.

  --Mike

-- 
Michael(tm) Smith
http://www.w3.org/People/Smith/