Afternoon all, As you know I've been quieter than usual lately (I've been busy changing companies/countries) but now I have a little bit of time on my hands I've been fleshing out the OCCI spec. Much of the feedback we've received has been that it's too abstract (which you'll recall was by design following the format wars of 2009) so I've added some examples to help people visualise what's going on. I've also added the following guide to the repository as README.txt so as to make it as easy as possible for others to get involved in the editing of the OCCI documents. I had a clash for the call this week but understand this issue was raised for the 17th time so hopefully this will put it to bed and make it a lot easier for more of you to get involved - if you have any questions you know where to find me. Cheers, Sam Open Cloud Computing Interface (OCCI) Editor Getting Started Guide
Overview
========
"DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software but it can be used for any other sort of documentation."
It was selected for OCCI in order to allow us to maintain a single source and publish to multiple formats:
* HyperText Markup Language (HTML) * Portable Document Format (PDF) * Plain Text (TXT)
Getting Started
===============
You will need the following to get started editing OCCI:
* Mercurial (http://mercurial.selenic.com/) * XML Editor (XMLmind: http://www.xmlmind.com/xmleditor/download.shtml)
1. Download and install Mercurial and your preferred XML editor.
2. Get a local copy of the occi repository with this command: hg clone https://occi.googlecode.com/hg/ occi 3. Edit the DocBook source (Hint: TDG5 is a great resource both for getting
started and as a reference)
Checking In
===========
If you want to check in changes you'll likely need to create a ~/.hgrc file something like this:
[ui]
username = John Citizen
[auth]
occi.prefix = occi.googlecode.com/hg/ occi.username = john@example.com occi.password = LF3W8dKKJG5X7 occi.schemes = https
You can now commit your changes (with a useful changelog entry please!) using:
hg ci hg push
Rendering
=========
You will need DocBook tools if you want to render the DocBook XML to other formats (which you should do each time you check in changes):
* DocBook XSLT (
http://sourceforge.net/projects/docbook/files/docbook-xsl-ns/)
* Apache FOP Binaries (http://www.apache.org/dyn/closer.cgi/xmlgraphics/fop
)
Under Mac OS X (using the default Makefile):
1. Extract docbook-xsl-ns into ~/Library/XML/XSL 2. Extract Apache FOP and copy build/fop.jar and lib/*.jar into
/Library/Java/Extensions
Then whenever you make changes simply run "make" to generate new HTML and PDF versions.
Resources
========= * Official Site (http://www.docbook.org/) * Wikipedia - DocBook (http://en.wikipedia.org/wiki/DocBook) * DocBook 5.0 - The Definitive Guide (
* DocBook XSL: The Complete Guide (