[Xlog-discussion] Documentation format: TeX, HTML, PDF & DocBook

[Jacob Anawalt]

Joop Stakenborg wrote:
> I have switched to html documentation for the next version. The idea
> was to use both latex2html and pdflatex to generate a nice set of
> documents

That sounds like a good idea. I was glad to see a step away from the 
current help setup. The TeX format seems simple enough and fairly 
diff/patch friendly compared to many other options. I must look in the 
wrong places for documentation or a good reference. I'm fine with 
writing text, but when I want to do something special like the verbatim 
block, I don't know the keyword to find what the command is.

I'm not too sad that the pdf didn't work out. They are nice sometimes, 
like if you want an easy to print format. I usually prefer html over 
pdf. At least people can generate a pdf from the .tex if they really 
want it, so I don't think it's so bad if it's not part of the package.

It would be nice if the help files were integrated into gnome-help in 
some future version. It looks like that system uses DocBook. I installed 
TeX4ht and used it to make DocBook output that yelp loaded. The 
formatting left some things to be desired and some content out. Maybe an 
expert on that system could help out. If not, it would require some 
proofing and tweaks to get the right final output.

http://developer.gnome.org/arch/doc/help.html
http://www.cse.ohio-state.edu/~gurari/TeX4ht/mn3.html#QQ1-3-11

--
Jacob / kd7yko