Hi Greg, 

Greg A. Woods wrote:
> I'm not a big fan of any of the available PDF readers, but perhaps if
> there were a good open-source one that had better searching and browsing
> capabilities with multiple open documents then it would be the best
> format for online publishing of NetBSD documentation too.

HTML is has tremendous advantages over PDF, which is why it and not PDF
dominates the www.  

> > The evidence stands against you, though.
> 
> Just look at the lines of code, the inherent parser
> complexity, and the CPU cycles necessary for handling anything like
> SGML, let alone XML.  

Right.  And look at what it does, HTML in particular.  Stylesheets control
appearance by assigning appearance to meaning.  If you use a typesetting
language as your source document, the conversion tool is *necessarily*
ignorant of the meaning, because the input describes appearance only.  No
amount of scripting will overcome that input deficit. The results show it,
every time.  

XML is usually considered a subset of SGML, btw. 
(http://www.w3.org/TR/NOTE-sgml-xml.html)

> >  Many very large documentation
> > projects rely on DocBook.
> 
> That's clearly not what I was talking about.  Just because people can
> push a bull through a china shop doesn't mean they should.  

Ah, but how many people push a bull through a china shop with good
results?  How often do they convince others to join them?  

I submit to you that the LDP and FreeBSD documentation projects, to name
but two, have created very good results and attracted many authors.  You
can put that down to mass hysteria if you want to, but there are clear
technical advantages to DocBook not shared by any alternative.  I'm
inclined to believe those people noticed the advantages and don't share
your sense of asthetics.  They might also have decided that to learn
DocBook was to acquire a useful skill with a long shelf life.  

> > DocBook is neither an accident nor a fad.
> 
> Sadly that is true.
> 
> However if you don't think Groff (or Lout, for that matter) is actively
> used and maintained, then please look again.

I know, and I'm glad for it.  But they're typesetting languages.  They
have no concept of a "screen", of user input, of a prompt, of an error
message, of a code sample.  That makes them technically inferior in our
problem domain, because it's impossible to control the appearance of those
things consistently except by brute force.  They also have tiny userbases
(authors, not readers of man pages) compared to DocBook, which means
they're far less likely to already be in or near the technical repertoire
of the potential NetBSD contributor. Which would limit your pool of
documentation authors to, approximately, one.  

ISTM we disagree on what's important.  To you, small tools and a terse
language matter.  To me, great HMTL and consistent appearance matter more.
 So too does popularity, because free software undertakings live and die
at the intersection of skills and desire.  I also think the tools will get
better, or at least have the best chance to, because of that popularity. 
Maybe that's why there's no FireFox for PDF.  Or why nedit, which does
syntax highlighting for 28 languages, doesn't include mdoc (much less
lout) among them.  

But, you know, I obviously don't do terse.  It wouldn't even have occurred
to me to leave the "e" out of "create".  

Regards, 

--jkl