openstack team mailing list archive

[Arnaud Quette <aquette.dev@xxxxxxxxx>]

Dear Anne, Stefano and stackers,

I've seen a few mails passing around, on the documentation topic.

I've quickly looked at the source, and found my comment would still be relevant.
So here we go:

you seem to have the exact same documentation needs and issues I've
faced some time ago:
- being able to version documentation, through a simple source format
- being able to generate a wide range of output (PDF, single / multi
page HTML, ePub, Groff manpage, Docbook, ...)
- have a lightweight and maintainable format (not docbook for
example), that allows to focus on the content, and not the technical
bits.

I found the light with Asciidoc, 2 years ago (pointed by ESR):
http://www.methods.co.nz/asciidoc/
It has an RST like syntax, provides tons of plugins for output, allows
to condition and modularize inclusion is flexible and very nice in
general.
I've since then revamped the whole NUT documentations, including the
website, using this:
- the website and documentations:
http://www.networkupstools.org/documentation.html
- the "source code" (all .txt files + Makefile.am for the rules):
http://anonscm.debian.org/viewvc/nut/trunk/docs/

If you are interested in, I can elaborate more.

See you soon on the power management topic...

cheers,
Arnaud
-- 
Linux / Unix Expert R&D - Eaton - http://powerquality.eaton.com
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Debian Developer - http://www.debian.org
Free Software Developer - http://arnaud.quette.free.fr/