@@ -35,104 +35,103 @@

Nordic EPUB3/DTBook Migrator

-

Installation

-

Latest version: 1.4.6

-

If you want to install the tool using some other mechanism than those describe below, then you can download the JAR file from - Maven Central, - or from the GitHub Release page. - The GitHub Release page also contains a description of changes for each release. However, using either - the Pipeline 2 Updater or running the nordic migrator using Docker is recommended.

- -

Using the Pipeline 2 Updater

-

Note that as of Pipeline 2 v1.13, the minimum required version of Java is 11. It is recommended to install Java from https://adoptopenjdk.net.

-
    -
  1. Download and install Pipeline 2 v1.13 by following the DAISY Pipeline 2 installation guide.
    2. -
  2. Use the updater mechanism as described in the installation guide, - but using the following URL as the "service":
    - "https://nlbdev.github.com/nordic-epub3-dtbook-migrator/releases/"
    3. -
- -

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 --network=host --rm -it nlbdev/nordic-epub3-dtbook-migrator:1.4.6
- -

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 --network=host --rm -it daisyorg/pipeline-webui:v2.7.0
- - -

About the tool

- -

The main goal of the Nordic EPUB3/DTBook Migrator is to provide a EPUB3 to DTBook conversion tool -for the libraries in the Nordic countries providing accessible litterature to -visually impaired readers (NLB, MTM, -SPSM, -Celia, Nota and SBS). -The conversion will be implemented in XProc and XSLT and provided as a -DAISY Pipeline 2 script. -This conversion will allow the organizations to continue to use their respective -DTBook-based tools for production of Braille and Synthetic Speech, -as long as those are necessary.

- -

This tool attempts to map EPUB3 to DTBook with as little loss as possible (a 1:1 mapping).

- -

While the EPUB3 will consist of multiple HTML files internally, an intermediate -single-page HTML representation is useful for converting to and from DTBook.

- -

This project provides the following Pipeline 2 scripts:

- -
    -
  • EPUB3 to DTBook
    • -
  • EPUB3 to HTML
    • -
  • EPUB3 Validator
    • -
  • EPUB3 ASCIIMath to MathML
    • -
  • HTML to EPUB3
    • -
  • HTML to DTBook
    • -
  • HTML Validator
    • -
  • DTBook to EPUB3
    • -
  • DTBook to HTML
    • -
  • DTBook Validator
    • -
- -

The EPUB3 to DTBook script will be used to allow new EPUB3 files to be used -with legacy DTBook-based systems.

- -

The DTBook to EPUB3 script allows legacy DTBooks to be upgraded to new -EPUB3-based production systems.

- -

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 -a HTML-based production system.

- -

Validators for EPUB3, DTBook and single-document HTML files are provided. -The EPUB3 validator allows us to check that new EPUB3 files are valid according -to the nordic markup guidelines. The DTBook and HTML validators can be useful -for DTBook- or HTML-based production systems.

- -

In the nordic markup guidelines, math is marked up using ASCIIMath. -An experimental script for converting this ASCIIMath to MathML is provided.

- -

The grammar used in the EPUB3, HTML and DTBook files is a strict subset of EPUB3, HTML and DTBook, -and is defined in the Nordic markup guidelines. Most DTBooks will work with these scripts, -there are few limitations to the input DTBook grammar. There are more limitations to the HTML/EPUB3 -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 EPUB3s.

- -

Resources

- - +

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.
    • +
+

Installation

+

Latest version: 1.5.2 (note, Docker-only version!)

+

There are several ways to run the Nordic Migrator. Below, we outline the process for installing and running the Nordic Migrator in two ways, using Docker or using the DAISY Pipeline 2 Updater. Running the Nordic Migrator with Docker is strongly recommended.

+

If you want to install the tool using some other mechanism than Docker or the Pipeline 2 Updater method, 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 (recommended)

+

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 --network=host --rm -it 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 --network=host --rm -it 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.

+

Using the Pipeline 2 Updater

+

Note that as of Pipeline 2 v1.13, the minimum required version of Java is 11. It is recommended to install Java from https://adoptopenjdk.net.

+
    +
  1. Download and install Pipeline 2 v1.14.1 by following the DAISY Pipeline 2 installation guide.
    2. +
  2. Use the updater mechanism as described in the installation guide, but using the following URL as the "service":
    "https://nlbdev.github.com/nordic-epub3-dtbook-migrator/releases/"
    3. +
+ + +

Resources

+

General

+ +

Mapping and validation

+

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

+ +

Tool user guides

+