We convert from asciidoc to pdf using the AsciiDoctor-PDF utility, embedded into a Docker container.
As a prerequisite, you need to build the container.
./build-container.sh
You have two options - one with some interactivity
Call the adoc2pdf.sh
script from the command line with the input filename (full path) as parameter, for example:
$./adoc2pdf.sh /Users/gstarke/projects/isaqb/foundation/curriculum-foundation.adoc
The default language being rendered is English. To explicitly define the language for which a document should be created you can use a second command line parameter with a language code, for example:
$./adoc2pdf.sh /Users/gstarke/projects/isaqb/foundation/curriculum-foundation.adoc DE
The default stage is dev and will include remarks from reviewers. To explicitly define the stage 'prod' you can use a third command line parameter:
$./adoc2pdf.sh /Users/gstarke/projects/isaqb/foundation/curriculum-foundation.adoc DE prod
Call the convert.sh
script from the command line with
$./convert.sh /Users/gstarke/projects/isaqb/foundation/curriculum-foundation.adoc
This will start an interactive shell in the container, giving you several additional options to configure, see figure below:
The main script is configure-and-convert-in-container.sh
, which is located in ./assets
. That script is copied into the Docker container during the build process and is its ENTRYPOINT
.
- At first you need to build the container. There's a
build-container.sh
script prepared for you. - You have two options to convert asciidoc files (see above). The
convert.sh
(see above) gives you some flexibility without forcing you to edit script files. - Both scripts
run
the Docker container, mapping several local directories to paths within the container:/build
is where the output of the conversion is written/pdf-theme
is where the pdf theme is located./documents
is where asciidoctor-pdf expects your asciidoc input file
- During the conversion, the output pdf is created in
/build
.
We customized a theme mimicking the original iSAQB documents (minus special fonts).
See the AsciiDoctor pdf guide for extensive documentation on styling options.
For conversion to pdf we use our custom pdf theme, named isaqb-theme.yml. This theme is located in:
./pdf-theme
The scripts and container are tailored around some specific requirements:
- convert documents written in several (at least EN and DE) languages
- distinguish between development (dev) and production (prod) versions of the target documents: dev versions need to contain comments and remarks, which are contained within the asciidoc source documents.
There's a folder (odt-based-conversion) which contains early experiments with a conversion process based upon OpenOffice.
In case anybody with OpenOffice experience feels eager enough to finish this experiment - great honor would fall upon you. All others can safely ignore this folder...
This work has been initiated by the Foundation Level Working Group of the iSAQB e.V., a non-profit organization to advance the area of software architecture.
Initially created by Peter Götz and Gernot Starke.