Mark Weinem wrote:
> > I thought mdoc(7) provided all the necessary features for simultaneous
> > publication of documentation in various forms

How do you define a URL in mdoc?  Does it become an HREF anchor when
converted to HTML?  What about a GUI component?  How do you include a
graphic?  

> > If folks want more structured (and truly structured) documentation
> > then I could only recommend Lout (pkgsrc/textproc/lout) as it is light
> > years beyond anything-TeX or troff-like and still light years beyond
> > anything-ML too.

I don't understand how you can recommend it.  The PDF backend is
officially deprecated, and I see no HTML backend.  

> > I'd personally be happier with raw troff or even raw TeX than
> > anything-ML.  There's nothing in the textual/documentation world more
> > difficult and more complex to read, parse, or manage than *ML files.

The evidence stands against you, though.  Many very large documentation
projects rely on DocBook.  

None of the systems you mention afaik have anything like DocBook
stylesheets.  I don't see separation of content from format.  Take the
<screen> tag for example (http://www.docbook.org/tdg/en/html/screen.html).
 How would you impose uniform formatting of screenshots unless every
instance of a screen is so designated?  

DocBook is not perfect for everything.  When my daughter's school papers
began including footnotes, I set her up with LaTeX, not DocBook, for
heaven's sake.  Right tool for the job.  She's not trying to maintain
technical documentation.  

DocBook is neither an accident nor a fad.  It demonstrably yields good
HTML and printed output.  It is well documented and actively worked on.  I
would also guess that of any system you might mention, it has the most
practitioners.  For those reasons alone it's the best available choice.  

Respectfully, 

--jkl