2. Prerequisites

To understand the purpose of each dependency, see the conversion graph.

Dependencies

The IDML format is complex, and extracting information from it is difficult. Ideally, this repository would consist of a single Haskell file, like Pandoc’s other readers. However, that would take an enormous amount of time to develop.

Others have explored reading IDML files, notably the project idml2xml-frontend, distributed under the FreeBSD license. We build our converter by continuing that work, offering a binding between idml2xml-frontend and Pandoc—i.e., converting the Hub XML output of idml2xml-frontend into DocBook 5.1 format.

The dependencies are:

  • Python 3.x;

  • Java 1.7+;

  • the Python package dependencies (with the command pip install -r requirements.txt)

  • idml2xml-frontend (installed with git via the command git clone https://github.com/transpect/idml2xml-frontend --recurse-submodules);

  • specify in a .env file the path to idml2xml-frontend (see the example provided with .env.sample).

Pandoc is not strictly a dependency since idml2docbook does not require it. However, a slightly modified version of Pandoc has been developed to support reading paragraph and character styles. To use it, you must compile it from source. You can also use the official version of Pandoc, but without style mapping. A pull request is in progress to include these new features in the main Pandoc branch.

Note: For large IDML files, it may be necessary to increase the Java heap size, for example to 2048m or 4096m.

Environment configuration (.env)

The .env.sample file shows an example configuration file.

At a minimum, this converter requires idml2xml-frontend to run. The IDML2HUBXML_SCRIPT_FOLDER line in the .env file should point to the absolute path of the idml2xml-frontend directory on your machine. This is the only entry that is required for idml2docbook to function.

The other values in the .env file can override the default settings of the idml2docbook package. For more information on these variables, consult the package help with the -h/--help option:

python -m idml2docbook -h

Configuration test

To verify that the dependencies are installed and the .env file is correctly set up, you can test the converter in your terminal with the following command:

pandoc hello_world.idml -f idml.lua -t markdown

The result should then be:

::: {wrapper="1" role="NormalParagraphStyle"}
Hello world!
:::