Forum OpenACS Q&A: Re: Docbook a barrier to doc efforts?

Posted by John Sequeira on
Several people have mentioned that an advantage of DocBook is exporting to multiple formats...  does anyone actually see that being useful?  i.e.  Is the PDF generated by docbook any better than what you could get starting from easily generated HTML and converting using htmldoc or Acrobat?

i.e. Would anyone actually read the PDF?

I think for documentation,  lowering the barriers to entry should take precedence over output flexibility.  It's fine to say that tools exist to support DocBook,  but wouldn't it be much better to just be able to use the tools for crunching text everyone knows about already?

For those reasons,  I vote wiki or something like it.  This would mean ETP would be closer to supporting it,  and you could still possibly render to DocBook if need be.  For instance,  Almost Free Text (a wiki variant) allows you to write filters that export different formats (html/xml/troff/latexe/etc).  I imagine you could write a DocBook export plugin and satisfy people favoring either approach.

Forget about figuring out:
1) which DocBook tool is most mature and useful
2) what element should I use for this callout or code block
3) how do I get my docs included in the CVS tree
etc. etc.

... Just hit the ETP button and write.