This work has been superseeded by JBPM-4740: please see that jira for the current procedures.

Old procedure

This will add a module that contains asciidoc documentation. The module, when built, generates docbook documentation chapter compatible with our existing docbook documentation.

The module is there to allow writers the possible to write and maintain documentation in asciidoc as well as docbook.

More notes:

HOW IT WORKS (overview)

Writing in AsciiDoc

If you want to write your chapter or section in asciidoc instead of docbook,

A1. You add a asciidoc file with the correct name in the correct place, and write the documentation
A2. You modify the pom.xml in the *-asciidoc to exclude the original docbook
A3. you run maven clean install in the *-asciidoc module and the normal, and make sure that the output matches the original.
A4. You modify the original docbook file:

Copy the generated docbook into the file
add a comment that says that the docbook was generated!

If you're adding a new chapter,

B1. you add a placeholder docbook file in the *-docs module
B2. you add your real documentation in the *-asciidoc module.
B3. generate the docbook and look at it
B4. create a docbook file in the original docbook module

copy the generated docbook into the file
add a comment that saws that the docbook was generated

Injecting code

1. You add a new file to the kie-docs-code module
2. You make sure it compiles
3. You annotate it:
3a. Like this:
https://github.com/mrietveld/kie-documentation/blob/master/kie-docs/kie-docs-code/src/main/java/org/kie/remote/client/documentation/JavaApiExamples.java#L42
( http://mrhaki.blogspot.nl/2014/04/awesome-asciidoc-include-partial-parts.html )
3b. Or like this:
https://github.com/mrietveld/kie-documentation/blob/master/kie-docs/kie-docs-code/src/main/java/org/kie/remote/client/documentation/jms/SendJmsExample.java#L24
( http://mrhaki.blogspot.nl/2014/05/awesome-asciidoc-explain-code-with.html )
4. You reference your code:
4a. just a part, like this:
https://github.com/mrietveld/kie-documentation/blame/master/kie-docs/jbpm-asciidocs/src/main/asciidoc/RemoteAPI/Java-section.adoc#L116
4b. Or the whole file, like this:
https://github.com/mrietveld/kie-documentation/blame/master/kie-docs/jbpm-asciidocs/src/main/asciidoc/RemoteAPI/JMS-section.adoc#L70
4. Rebuild the module, since the code is injected via a dependency

HOW IT REALLY WORKS (technical details)

1. We unpack the original docbook files into the (gitignored) src/main/docbook directory. There are <excludes> in the pom.xml that ignore the docbook files that we regenerate with asciidoc.

https://github.com/mrietveld/kie-documentation/blob/master/kie-docs/jbpm-asciidocs/pom.xml#L59

2. We also unpack our code sources into target/code and set a variable that references where the code has been put.

3. We generate docbook from asciidoc
3a. the asciidoc files must follow a certain format: *-chapter.adoc or *-section.adoc. This is for XSLT transformations later
3b. The asciidoc files must also contain some tips for the xslt transformations, like this: