Home

This wiki is the source of the Scribble documents. We convert the asciidoc into an intermediate Docbook format, which then is used to create HTML and PDF versions.

The Asciidoc cheat-sheet is a nice place to start learning about Asciidoc itself.

Converting the Scribble documents into Docbook format

If you want to build these yourself you need to install asciidoc on your machine and check out the repository locally using:

git clone https://github.com/scribble/scribble-docs.wiki.git

Then go into the scribble-docs.wiki/<Name>/en-US directory, and run:

asciidoc -a docinfo -b docbook <Name>.asciidoc

Where <Name> is the document name, e.g. ProtocolLanguageGuide. This will produce a docbook formatted file called <Name>.xml.

Creating the PDF and HTML versions

Now, go back up in the root wiki directory (or the specific guide directory of interest) and run:

mvn clean install

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

Committing changes

Unlike other git repositories, it is currently not possible to have a personal fork of the repository in your own github account to issue pull requests.

Therefore changes must be submitted by performing a commit direct on the repository.

git add *
git commit -m "<description of the changes>"

Make sure that the docbook representation of the asciidoc documents has been generated prior to committing the changes.

Q & A

I spotted a typo, can I fix it?

Yes please help us maintain the documentation. Simply update the appropriate page right on github.

How do I add an image?

Images cannot be uploaded through the github UI. Instead you need to add them to the images directory in the root of the rtgov.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. - , a title i.e. .Welcome screen. and then the thing itself -for an image use something like image::images/example.png[Screenshot of the example]. The label figure-screenshot-example can be used to link to this figure using [figure-screenshot-example].

How do I add a chapter to the book in docbook?

We add chapters as different files, and then include them in the top level document, e.g. ProtocolLanguageGuide.asciidoc file. At docbook generation time it will pull in the chapter into the ProtocolLanguageGuide.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.