Creating CHM Files From AsciiDoc

Creating CHM Files From AsciiDoc

A lot of documentation is present on how to create documentation from HTML files, in a CHM format, but a lot of it is either outdated, depends on Windows, or plain out wrong. There’s got to be a better way.

Here’s the way.

The toolchain is also very simple. First, asciidoc itself supports having as output htmlhelp, the unpacked version that can be compiled in the HTML Help Builder available for Windows. Unfortunately asciidoctor doesn’t support the htmlhelp output :(.

Calling it is very simple, namely:

a2x -f htmlhelp index.adoc

This will generate the index.hhp along with the files required to be packaged. Fortunately there is a tool bundled in FreePascal, that will do the compilation to CHM even in Linux, named chmcmd. Calling it is again trivial (must be in the same folder where index.hhp was generated):

chmcmd index.hhp

This will generate the index.chm. While easy to run these commands need both the full installation of asciidoc and FreePascal, that on my Linux it’s about 2GB.

In order to make our lives easier, I created a docker container for these, to easily integrate it into the build sytem of your choice bmst/chm-generator.

Running everything becomes then just:

docker run -it \
           --rm \
            -v `pwd`:/src \
            -v `pwd`:/out \
            bmst/chm-generator

Happy documenting!

 

Article Photo taken from Pexels: https://www.pexels.com/photo/book-shelves-book-stack-bookcase-books-207662/