[Xapian-discuss] Xapian documentation

[R. Mattes]

On Mon, 2006-05-08 at 11:11 -0500, Peter Karman wrote:
> 
> James Aylett scribbled on 5/8/06 10:54 AM:
> 
> > 
> > I'd argue (although mostly for the sake of arguing :-) that doing
> > something because the majority of the Linux world does it is actually
> > a very bad idea. (Gee, let's all use CORBA :-)
> 
> oh, I agree. I wasn't trying to suggest that since "everyone else is 
> doing it, so should we." Merely that there is a great deal of experience 
> out there with DocBook and so it is fairly portable and has a decent 
> tool set.
> 

Sorry, but i disagree here. DocBook is a rather nasty beast in disguise.
It's a DTD with a marketing departement (and a bloody mighty one!).
In my experience it's actually a rather _bad_ format for most OS
projects. Yes, semantic markup is the way to go, but DocBook the DTD
somehow manages to be both way too specific and at the same time way to
general. The minimal markup already is rather eloquent (to be polite)
compared to, hmm, LinuxDoc or TEI/TEI-light. But, even worse, the markup
is stupidly C/C++ centric. Ever tried to document a Perl module or a
Python class? Oberon interface - no way.

On a markup level:  it's a DTD (SGML), which means it doesn't really
play nice with XML features like namespaces (which would be handy to
fix the problem of being C-centric). DocBook XML is a side project that
suffers from some of the stupid shortcommings of XML DTDs (too little
time to elaborate on this ...). 

> >> There are many good free tools for DocBook publishing, the best
> >> among them the XSLT stuff from Norm Walsh et al.

That's about the only decent open source _formating_ tool I came
accross. There's OpenJade but unfortunately that tools seems to abuse
the TeX renderer in the most horendous way i ever saw (instead of using
(La)TeX's wonderful typesetting capabilities they use it to place boxes
at fixed positions ... ever realized _how_ crappy the printed output
is?). 
For toolchain support? What editors are there? Emacs with psgml (but
only for DocBook SGML) or the excelent nXML mode (which still lacks a
lot of the cool psgml features we would like to have for heavy DTDs like
DocBook). That's about it. XML Mind's editor would be nice iff open
source, but alas, it's not (and it only runs on Sun's chosen platforms,
not on my Linux/PPC :-(
Want to include special markup in your own namespace (Dublin Core
metainfo or Creative Comm. licence info)? Not with the "free" edition.

 
> > Having played a little with XML Mind's editor, I'm inclined to think
> > DocBook is probably the way to go. It's just a pity it's still so
> > damned ugly :-)
> > 
> 
> when my old company switched from nroff man pages to XML man pages, we 
> pretty much doubled the size of our doc set overnight. But then, we 
> suddenly had an enforceable, testable document type definition and 
> semantic meaning to our markup. I still like nroff/troff (it's great for 
> certain appliations) but I was glad to get the added benefits of DocBook.
> 
> so ugliness in one sense can be beauty in another. :)

Well, semantic markup _is_ pretty cool. We do it here at Zeitverlag for
all online publishing and it realy pays of. And DocBook is ecxelent for
the task it was designed for (documentation of broad/deep monster C++
APIs :-) 
Why not something like LinuxDoc (or even, shudders, Texinfo XML ...)

 Cheers, Ralf Mattes