GuideREADME

Test Didier This PressGang wiki is the source of the PressGang Guide document. Or, as we like to call it…​

The Holy Grail of Documentation

This guide covers how to build the PressGang Guide Book written in AsciiDoc using the DocBook toolchain.

Here are the players:

• AsciiDoc (processed using Asciidoctor)

• Asciidoctor Maven Plugin

• jdocbook

• jdocbook Maven Plugin

• PressGang styles & custom DocBook XSL

• Holy Hand Grenade (ahem, Maven)

The directory layout of the wiki in this example is:

├── Guide
│   └── en-US
│       ├── Guide-docinfo.xml
│       ├── Guide.asciidoc
│       ├── GuideExampleChapter.asciidoc
│       ├── GuideREADME.asciidoc
│       ├── GuideSecondExampleChapter.asciidoc
│       └── _Sidebar.asciidoc
├── Home.asciidoc
├── images
│   └── jenkins.png
└── pom.xml

The Guide document is based on the AsciiDoc book.txt example, and a Guide-docinfo.xml include file to support more then one author. The 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.

Building the Holy Grail

If you want to build these yourself you need to check out the repository locally using:

git clone git@github.com:pressgang/pressgang-tools.wiki.git

and run:

mvn clean install

and it will build HTML and PDF versions in the target/docbook/publish/en-US directory.

Q & A

1. I spotted a typo, can I fix it?

   Yes please help us maintain the documentation. Simply update the appropriate page right on GitHub. Our nightly build will distribute the changes to docbook and the HTML and PDF versions, as specified in the Maven pom.

2. 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 pressgang-tools 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.

3. How do I add numbering and references?

   You should add a label. We use the convention <type>-<chapter>-<label>. For example:

   [[figure-gs-screenshot-of-openshift]]
   .Welcome screen of OpenShift.
   image::website/images/jenkins.png[Screenshot of OpenShift]]

   The label figure-gs-screenshot-of-openshift can be used to link to this figure using [figure-gs-screenshot-of-openshift]. The GuideExampleChapter contains an example.

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

5. Why are all the files prefixed with Guide?

   The GitHub wiki flattens out the directory structure on the Pages page. In order to group all the files of the Guide together, we decided to prefix them all with Guide.