docs/asciidoc/Readme.asciidoc - juddi - Git at Google

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