Example project for AsciiDoc → DocBook → Webhelp

Introduction

This project is meant to be an example on how to setup and manage HTML-based help documents, authored in AsciiDoc. AsciiDoc is a lightweight markup language that shares the simplicity of similiar languages such as Markdown, but it comes with a larger set of features than most Markdown flavours, at least without any extensions added.

Requirements

Installed using [Chocolatey](https://chocolatey.org/)

choco install adoptopenjdk11
choco install jruby
choco install python3
choco install ant
choco install docbook-bundle
<#
xsltproc might not even be necessary at all, keeping this here mostly "just in case".
It is also installed as a part of JRuby so that should cover any potential need for it.
#>
<# choco install xsltproc #>

Installed using JRuby

jruby -S gem install asciidoctor-pdf pygments.rb

Current issues

As of yet, I haven’t found a way to set up CLASSPATH for the saxon.jar using build.xml or build.properties.
The instructions from DocBook says that "when you generate output, the Saxon jar must not be in your CLASSPATH".
This might mean that I’d have to copy the entire DocBook bundle into the repository and edit the build.xml from DocBook.

For now, I’ve gotten it to work by setting the system environment variable CLASSPATH to point to saxon.jar.
This can also be set "temporarily" in Powershell for the currently running shell by running this command:

$env:classpath = 'C:\ProgramData\chocolatey\lib\docbook-bundle\docbook-xsl-1.79.1\tools\lib\saxon.jar'

To store this permanently for your logged in user, you can run this command:

[Environment]::SetEnvironmentVariable("CLASSPATH",'C:\ProgramData\chocolatey\lib\docbook-bundle\docbook-xsl-1.79.1\tools\lib\saxon.jar',"User")

To store this permanently for all users on the computer, you will first need to start Powershell with elevated permission, then you can run this:

[Environment]::SetEnvironmentVariable("CLASSPATH",'C:\ProgramData\chocolatey\lib\docbook-bundle\docbook-xsl-1.79.1\tools\lib\saxon.jar',"Machine")

Automated build using Ant

This project has been set up to use Ant to build from AsciiDoc to Docbook and then finally to WebHelp. The project has a default configuration-file for the DocBook-to-WebHelp build (build.properties), but if a different propertyfile is supplied on the commandline, it will override the default one.

The docbook-bundle comes with a default build.properties and build.xml that this is based upon.

To build with the default file, simply run: ant
If you want to supply a different file, run: ant -propertyfile MyOwnBuild.properties

Manual instructions

AsciiDoc to DocBook

asciidoctor.bat -b docbook .\asciidoc\main.adoc -o .\docbook\main.xml

Convert DocBook to Webhelp (Ant build)

ant
start webhelp\index.html

flatrick / asciidoc