View Nordic EPUB3/DTBook Migrator on GitHub

About the tool

The Nordic EPUB3/DTBook Migrator is a tool for validating and converting Nordic Guidelines-conforming EPUB 3, HTML and DTBook file sets. It is implemented as a DAISY Pipeline 2 script and is being used for the production of accessible literature by the (mostly) Nordic organizations Celia, Dedicon, HBS, MTM, NLB, Nota, SBS, SPSM, and Statped.

The tool supports EPUB 3-only workflows, where primarily validation is needed, or EPUB 3—DTBook workflows, where the primary production is carried out in EPUB 3 but including a conversion to DTBook, allowing the organization to use the output in legacy DTBook-based tools, e.g. TTS or Braille production tools. The tool's conversion capabilities work in both directions, so it can also be used to upgrade legacy DTBook file sets to EPUB 3.

The Nordic EPUB3/DTBook Migrator is closely related to the development of the Nordic Guidelines, a joint application of EPUB 3 and DTBook formats for the production of accessible content at the Nordic organizations. Currently, only validation is supported for files conforming to the 2020-1 version of the guidelines. For 2015-1-conforming files, conversion between e.g. EPUB 3 and DTBook is also supported.

This project provides the following Pipeline 2 scripts:

  • EPUB3 Validator
  • EPUB3 to DTBook (2015-1 guidelines only)
  • EPUB3 to HTML (2015-1 guidelines only)
  • EPUB3 ASCIIMath to MathML (2015-1 guidelines only)
  • HTML to EPUB3 (2015-1 guidelines only)
  • HTML to DTBook (2015-1 guidelines only)
  • HTML Validator (2015-1 guidelines only)
  • DTBook to EPUB3 (2015-1 guidelines only)
  • DTBook to HTML (2015-1 guidelines only)
  • DTBook Validator (2015-1 guidelines only)

Additional notes

  • Scripts for converting to and from the intermediary single-HTML representation of the publications are also provided. These are useful either for debugging, or if a single-document HTML representation is needed as input to or output from an HTML-based production system.
  • In the 2015-1 Nordic Guidelines, math is marked up using ASCIIMath. An experimental script for converting this ASCIIMath to MathML is provided.
  • The grammar used in the EPUB 3, HTML and DTBook files—the Nordic Guidelines—is a strict subset of EPUB 3, HTML and DTBook. Most DTBooks will work with these scripts. There are few limitations to the input DTBook grammar. There are more limitations to the HTML/EPUB 3 grammar however, because there must be a way to convert it to DTBook. Most notably, multimedia such as audio and video are currently not allowed in these EPUB 3s.
  • The Nordic EPUB3 Validator script can validate according to both 2015-1 and 2020-1 rulesets. Which ruleset will be applied is determined by the value of the <meta property="nordic:guidelines"> element in package.opf.

Latest version: 2.0.0

The 2.x versions of nordic-epub3-dtbook-migrator can only be run through Docker. But it has both a command line interface, and an API.

Command line interface

Example of running the command line interface:

docker run --rm -it -v "$(pwd)":"$(pwd)" -w "$(pwd)" nlbdev/nordic-epub3-dtbook-migrator java -jar /var/www/bin/NordicValidator.jar

Example of validating an EPUB from the command line::

docker run --rm -it -v "$(pwd)":"$(pwd)" -w "$(pwd)" nlbdev/nordic-epub3-dtbook-migrator java -jar /var/www/bin/NordicValidator.jar X60352A.epub

REST API

Example of starting the Docker container as a service:

docker run --publish 8080:80 nlbdev/nordic-epub3-dtbook-migrator

Example of validating an EPUB using the API and curl:

curl -s -F config='{"noEPUBCheck":false,"noACE":false,"schema":"2020-1"}' -F file=@X60352A.epub http://localhost:8080/v1/Validation

When it comes to documentation, the SwaggerAPI / OpenAPI documentation can be viewed either by downloading an editor like Postman, or going to https://editor.swagger.io/. The API definition is available on the following URL, and you can either download the file and upload it to the editor, or import the URL directly:

https://raw.githubusercontent.com/nlbdev/nordic-epub3-dtbook-migrator/master/web/docs/api_v1.yaml

Last Pipeline 2 based version: 1.5.2

Note that earlier 1.x versions supported normal Pipeline 2 installation and the Pipeline 2 updater mechanism. However, 1.5.2 does only run as a Docker container.

If you want to install the tool using some other mechanism than Docker, the JAR file is available from the Maven repository on GitHub, or from the GitHub Release page. The GitHub Release page also contains a description of changes for each release.

Using Docker

The Nordic Migrator is published as nlbdev/nordic-epub3-dtbook-migrator, tagged with release versions.

Example of how to run the Nordic EPUB3/DTBook Migrator with Docker:

docker run --detach --name pipeline -e PIPELINE2_WS_HOST=0.0.0.0 -e PIPELINE2_WS_AUTHENTICATION=false nlbdev/nordic-epub3-dtbook-migrator:1.5.2

After starting the Nordic Migrator, you could also start the Pipeline 2 Web UI on the same system like this, if you don't have any other interface (starts on http://localhost:9000/):

docker run --detach --link pipeline -p 9000:9000 --name pipeline-webui -v webui-data:/opt/daisy-pipeline2-webui/data -e DAISY_PIPELINE2_URL=http://pipeline:8181/ws daisyorg/pipeline-webui:v2.7.1

Using docker-compose

A slightly more elaborate method of running the validator in Docker is using docker-compose.

Suggested docker-compose.yml file:

services:
   pipeline:
      image: nlbdev/nordic-epub3-dtbook-migrator:1.5.2
      environment:
         PIPELINE2_WS_HOST: "0.0.0.0"
         PIPELINE2_WS_AUTHENTICATION: "false"
      volumes:
         - "pipeline-data:/opt/daisy-pipeline2/data"
   webui:
     image: daisyorg/pipeline-webui:v2.7.1
     environment:
        DAISY_PIPELINE2_URL: http://pipeline:8181/ws
     ports:
        - "9000:9000"
     volumes:
        - "webui-data:/opt/daisy-pipeline2-webui/data"
     depends_on:
        pipeline:
           condition: service_healthy
volumes:
   pipeline-data:
   webui-data:

The two containers can now be started jointly with the following suggested command (replace the path with your docker-compose.yml location):

docker-compose -f [path to docker-compose.yml] up --force-recreate -d

The web UI service should now be up and running on http://localhost:9000/, which you can access from a browser to manage Nordic Migrator jobs (e.g. validation).

Please note that adding e.g. restart: always to the .yml config file will restart the containers after Docker or system restart. However, on Windows, the web UI container will not be successfully resumed after system restart this way. So either exit Docker Desktop before system shutdown, or initiate the containers afresh with the command above. There are many ways of setting up Docker services, please refer to the Docker documentation to learn more.

Resources

General

Mapping and validation

NB, conversion between EPUB 3 and DTBook is currently only supported for 2015-1 guidelines.

Tool user guides