How to build the jUDDI Guide Book in Docbook format?
====================================================

This jUDDI wiki is the source of the jUDDI Guide document. The directory layout of the wiki in this example is
....
├── Guide
│   └── en-US
│       ├── Guide-docinfo.xml
│       ├── Guide.asciidoc
│       ├── GuideDatabase-Connection-Setup.asciidoc
│       ├── GuideReadme.asciidoc
│       └── _Sidebar.asciidoc
├── Home.md
├── JUDDI.asciidoc
├── Readme.asciidoc
├── images
└── pom.xml
....

The Guide document is based on the Asciidoc http://www.methods.co.nz/asciidoc/book.txt[book.txt] example, and a Guide-docinfo.xml include file to support more then one author. The http://asciidoctor.org/[AsciiDoctor] maven plugin converts the asciidoc files into an intermediate Docbook format ('Guide.xml'), which then is used as input for _maven-jdocbook-plugin_ to create HTML and PDF versions. If you want to build these yourself you need to check out the repository locally using:
----
git clone git@github.com/UDDI/juddi.wiki.git
----
and run:
----
mvn clean install
----
and it will build HTML and PDF versions in the target/docbook/publish/en-US directory.

[qanda]
.Q&A
I spotted a typo, can I fix it?::
Yes please help us maintain the documentation. Simpy update the
appropriate page right on
https://github.com/UDDI/juddi/wiki/Guide[github]. Our nightly
build will distribute the changes to docbook and the html and pdf
versions.

How do I add an image?::
Images can not be uploaded through the github UI. Instead you need to add them to the `images` directory in the root of the juddi.wiki repo and then push it up to github. You can then reference your image on the page using `image::images/<myimage>.ext`.
NOTE: Make sure to add an empty line before and after this image reference.

How do add a numbering and references?::
You should add a label -we use the convention
<type>-<chapter>-<label>, i.e.
`[[figure-UDDIREG-Invocation Pattern]]`- , a title i.e. 
`.Invocation Pattern using the UDDI Registry.` and then the thing itself -for an
image use something like `image::images/UDDI_Registry_invocation_pattern.png[Invocation Pattern using the UDDI Registry]`. The label `figure-UDDIREG-Invocation Pattern` can be used to link to this figure using
`<<figure-UDDIREG-Invocation Pattern>>`. The link:GuideUDDIRegistryIntroduction[UDDIRegistryIntroduction] contains an example.

How do I add a chapter to the book in docbook?::
We add chapters as different files, and then include them in the
`Guide.asciidoc` file. At docbook generation time it will pull in the
chapter into the `Guide.xml` file. Also we add a link in the `_Sidebar.asciidoc`
page to have a link when looking at it at Github in wiki style.

Why are all the files prefixed with `Guide`?::
The GitHub wiki flattens out the directory structure on the link:_pages[Pages] page. So in order to group all the files of the Guide together we decided to prefix them all with `Guide`.