[occi-wg] OCCI Editor Getting Started Guide (docs/README.txt)

[Sam Johnston]

Good question so I'm copying the list (especially for the benefit of the
newcomers).

We maintain a Google Code repository at http://code.google.com/p/occi/ which
includes a Mercurial (hg) repository at https://occi.googlecode.com/hg/ -
this is in addition to the (currently fairly ordinary) marketing site at
http://www.occi-wg.org/ and OGF's GridForge at http://forge.ogf.org/

The best way to get at up-to-the-second updates is to go to the Source tab,
then Browse. There you'll find a "code" and "docs" directory (the purpose of
which should be fairly obvious) and under docs you'll find 3 versions
(DocBook XML, PDF and HTML) of each file. Click on e.g.
occi-core.html<http://code.google.com/p/occi/source/browse/docs/occi-core.html>and
on the right hand side you'll find a "View raw file" link (in this
case
occi-core.html <http://occi.googlecode.com/hg/docs/occi-core.html>).

Note that sometimes the PDF and HTML renderings fall behind the DocBook XML
renderings by a few hours/days but regenerating them is fairly
straightforward, following the instructions in
README.txt<http://occi.googlecode.com/hg/docs/README.txt>

Hope this helps,

Sam

On Thu, Feb 18, 2010 at 6:23 PM, X wrote:

> Dear Sam:
>
> Does your changes to occi docs are available online?
>
> Regards,
> X
>
> On Thu, Feb 18, 2010 at 1:09 PM, Sam Johnston <samj at samj.net> wrote:
> > 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 <john at example.com>
> >>
> >> [auth]
> >>
> >> occi.prefix = occi.googlecode.com/hg/
> >>
> >> occi.username = john at 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
> >> (http://www.docbook.org/tdg5/en/html/docbook.html)
> >>
> >>  * DocBook XSL: The Complete Guide
> >> (http://www.sagehill.net/docbookxsl/index.html)
> >
> >
> > _______________________________________________
> > occi-wg mailing list
> > occi-wg at ogf.org
> > http://www.ogf.org/mailman/listinfo/occi-wg
> >
> >
>
>
>
> --
> Regards,
> X
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.ogf.org/pipermail/occi-wg/attachments/20100218/ab863ae6/attachment.html