openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi Arnaud -
Asciidoc is great and we can work it into our toolchain. O'Reilly
offers authors the option of either authoring in DocBook (which is
most of our source on docs.openstack.org) or Asciidoc.

I like to accept documentation in any format - even Word docs printed
and handed to me from a briefcase at the Design Summit. We had many
pages of documentation already in DocBook when I joined. I'm
interested in building a community of contributors and finding ways to
enable their contributions, so all formats are welcomed.

Feel free to contact me with specific ideas about Asciidoc contributions.

Thanks,
Anne

On Tue, Dec 6, 2011 at 2:20 AM, Arnaud Quette <aquette.dev@xxxxxxxxx> wrote:
> 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/