[Xapian-discuss] Xapian documentation

[Peter Karman]

R. Mattes scribbled on 5/8/06 4:56 PM:

> 
> 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 ...)

yes, I used DocBook when at Cray for all our software docs (C, Fortran, 
etc.). We only used a small subset of the available tags. Otherwise, 
it's easy to get lost in the DocBook maze.

For my own work I use POD (Perl's Plain Old Documentation) format, as it 
is easy to write and translates easily to HTML and man (catman) formats.

If the goal for a Xapian book is to integrate nicely with the website 
and provide an offline doc reference, I still recommend DocBook over 
LinuxDoc or some of the other semantic defs, simply because of the 
widespread use of the format. Yes, there should be a better open source 
XML editor out there, no question about that. But as I've written lots 
with just a plain text editor and libxml2/xmllint to test with, I'm biased.

Otherwise, if semantic markup is not desirable, POD is a nice format to 
write in, imho.

-- 
Peter Karman  .  http://peknet.com/  .  peter at peknet.com