Posted by rockyallen on Dec 11, 2017; 8:19pm
URL: https://discuss.asciidoctor.org/Asciidoc-and-dependency-management-tp3751p6075.html

I know this is an old thread, but I just want to give my experience.

We assemble a single large document for each customer from many modules. Each customer can have different modules and different versions of those modules.
We tried the each-module-publishes-a-jar approach, but the editing cycle was too painful. Modules are quite often developed in parallel with the overall document, and you need to edit them seamlessly.

Our solution is to hold the modules in SVN, and create SVN dependencies from the master document project onto the modules it needs. On checking out the master document project, SVN then checks out all the necessary modules into a single folder where the master document can see them, eg:

== Maintenance
include::{moduledir}/engine123/master.adoc[tag=maintenance]
include::{moduledir}/gearbox456/master.adoc[tag=maintenance]

Initially the dependencies are to trunk. When the document is stable, you can change them to tags. And export rather than checkout if you don't want to risk inadvertent changes to the modules.

Note the single master.adoc for each module. I find this makes WYSIWYG editing much easier.
The file has a standard set of tags for "description", "maintenance", "spares" etc. so that the overall master is just a list of include::[tag=], and hardly ever has to be edited.

Good:
- Works well with our Jenkins build server
- Keeps dependencies in 1 place
- Single button build once the dependencies are defined
- Publish a manual for each module with no extra work

Bad:
Very SVN specific
Maintaining the dependencies using Tortoise SVN is ugly.

Ideally the dependencies would be declared in a tool-agnostic way and kept in the build script (Ant in our case) or in the master document. Antora maybe?

This works for us, but any suggestions for stream-lining it would be good.