This directory contains what's eventually intended to become reference
documentation for OpenStack High Availability.
Contrary to the rest of the documentation which is straight-up
DocBook, this guide is being maintained, at least for the time being,
in AsciiDoc. AsciiDoc processing is supported by the OpenStack Jenkins
CI infrastructure, but not by the Maven toolchain. So as a stop-gap
measure until such support becomes available, please do this if you
want to build offline before you send a patch:
1. Make your change to the AsciiDoc source file (.txt). The syntax
should be self explanatory-and intuitive to anyone who's ever used
something like Markdown or RST. The AsciiDoc cheatsheet is an
extremely useful resource: http://powerman.name/doc/asciidoc
2. Pipe your stuff through AsciiDoc. Here's one catch: AsciiDoc
currently doesn't fully support DocBook 5, but the Maven toolchain
requires it. So you'll have to run your AsciiDoc output through the
"db4upgrade.xsl" stylesheet that ships with DocBook 5.
3. Finally, indent your resulting XML with two spaces. This should
produce a clean patch against bk-ha-guide.xml which you can then
submit to Gerrit along with your .txt file patch.
4. Add an "xml:id" attribute on the root <book> element. The Maven
toolchain requires this.
Here's a command line you can use with AsciiDoc, xsltproc, xmllint and
sed to achieve all of the above:
asciidoc -b docbook -d book -o - ha-guide.txt | \
xsltproc -o - /path/to/db4-upgrade.xsl - | \
xmllint --format - | \
sed -e 's,^<book ,<book xml:id="bk-ha-guide" ,' \
> bk-ha-guide.xml
Admittedly, the sed hack is particularly ugly, but it does get the job
done.
After that, you should be able to build with "mvn clean
generate-sources" as you normally would.
