| 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`. |