-
Notifications
You must be signed in to change notification settings - Fork 7
/
index.html
167 lines (152 loc) · 12.9 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
<!doctype html>
<!-- The Time Machine GitHub pages theme was designed and developed by Jon Rohan, on Feb 7, 2012. -->
<!-- Follow him for fun. https://twitter.com/jonrohan. Tail his code on https://github.com/jonrohan -->
<html>
<head>
<meta charset="utf-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
<meta name="dcterms:modified" content="2022-04-19"/>
<link rel="stylesheet" href="stylesheets/stylesheet.css" media="screen"/>
<link rel="stylesheet" href="stylesheets/pygment_trac.css"/>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script type="text/javascript" src="javascripts/script.js"></script>
<title>Nordic EPUB3/DTBook Migrator</title>
<meta name="description" content="Tools for validating and converting Nordic Guidelines-conforming EPUB 3, HTML and DTBook files."/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
</head>
<body>
<div class="wrapper">
<header>
<h1 class="title"><a href="index.html">Nordic EPUB3/DTBook Migrator</a></h1>
</header>
<div id="container">
<p class="tagline">A tool for validating and converting <a href="https://format.mtm.se/nordic_epub/">Nordic Guidelines</a>-conforming EPUB 3, HTML and DTBook files.</p>
<div id="main" role="main">
<div class="download-bar">
<div class="inner">
<a href="https://github.com/nlbdev/nordic-epub3-dtbook-migrator" class="code">View Nordic EPUB3/DTBook Migrator on GitHub</a>
</div>
<span class="blc"></span><span class="trc"></span>
</div>
<article class="markdown-body">
<h1><a name="nordic-epub3dtbook-migrator" class="anchor" href="#nordic-epub3dtbook-migrator"><span class="octicon octicon-link"></span></a>About the tool</h1>
<p>The Nordic EPUB3/DTBook Migrator is a tool for validating and converting <a href="https://format.mtm.se/nordic_epub/">Nordic Guidelines</a>-conforming EPUB 3, HTML and DTBook file sets. It is implemented as a <a href="https://daisy.github.io/pipeline">DAISY Pipeline 2</a> script and is being used for the production of accessible literature by the (mostly) Nordic organizations <a href="https://www.celia.fi/">Celia</a>, <a href="https://www.dedicon.nl/">Dedicon</a>, <a href="https://hbs.is/">HBS</a>, <a href="https://mtm.se">MTM</a>, <a href="https://www.nlb.no/">NLB</a>, <a href="https://nota.dk/">Nota</a>, <a href="https://www.sbs.ch/">SBS</a>, <a href="https://www.spsm.se/">SPSM</a>, and <a href="http://statped.no/">Statped</a>.</p>
<p>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.</p>
<p>The Nordic EPUB3/DTBook Migrator is closely related to the development of the <a href="https://format.mtm.se/nordic_epub/">Nordic Guidelines</a>, 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 <a href="https://format.mtm.se/nordic_epub/2020-1/">2020-1</a> version of the guidelines. For <a href="https://format.mtm.se/nordic_epub/2015-1/">2015-1</a>-conforming files, conversion between e.g. EPUB 3 and DTBook is also supported.</p>
<p>This project provides the following Pipeline 2 scripts:</p>
<ul>
<li>EPUB3 Validator</li>
<li>EPUB3 to DTBook (2015-1 guidelines only)</li>
<li>EPUB3 to HTML (2015-1 guidelines only)</li>
<li>EPUB3 ASCIIMath to MathML (2015-1 guidelines only)</li>
<li>HTML to EPUB3 (2015-1 guidelines only)</li>
<li>HTML to DTBook (2015-1 guidelines only)</li>
<li>HTML Validator (2015-1 guidelines only)</li>
<li>DTBook to EPUB3 (2015-1 guidelines only)</li>
<li>DTBook to HTML (2015-1 guidelines only)</li>
<li>DTBook Validator (2015-1 guidelines only)</li>
</ul>
<h2>Additional notes</h2>
<ul>
<li>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.</li>
<li>In the 2015-1 Nordic Guidelines, math is marked up using ASCIIMath. An experimental script for converting this ASCIIMath to MathML is provided.</li>
<li>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.</li>
<li>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 <code><meta property="nordic:guidelines"></code> element in <code>package.opf</code>.</li>
</ul>
<h1><a name="installation" class="anchor" href="#installation"><span class="octicon octicon-link"></span></a>Installation</h1>
<p><strong>Latest version: 1.5.2 (note, Docker-only version!)</strong></p>
<p>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.</p>
<p>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 <a href="https://github.com/nlbdev/nordic-epub3-dtbook-migrator/tree/mvn-repo/org/daisy/pipeline/modules/nordic-epub3-dtbook-migrator">Maven repository on GitHub</a>, or from the <a href="https://github.com/nlbdev/nordic-epub3-dtbook-migrator/releases">GitHub Release page</a>. The GitHub Release page also contains a description of changes for each release.</p>
<h2>Using Docker (recommended)</h2>
<p>The Nordic Migrator is published as <code>nlbdev/nordic-epub3-dtbook-migrator</code>, tagged with release versions.</p>
<p>Example of how to run the Nordic EPUB3/DTBook Migrator with Docker:</p>
<pre><kbd>docker run --network=host --rm -it nlbdev/nordic-epub3-dtbook-migrator:1.5.2</kbd></pre>
<p>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 <a href="http://localhost:9000/">http://localhost:9000/</a>):</p>
<pre><kbd>docker run --network=host --rm -it daisyorg/pipeline-webui:v2.7.1</kbd></pre>
<h3>Using docker-compose</h3>
<p>A slightly more elaborate method of running the validator in Docker is using <a href="https://docs.docker.com/compose/"><kbd>docker-compose</kbd></a>.</p>
<p>Suggested <code>docker-compose.yml</code> file:</p>
<pre>
<code>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:</code>
</pre>
<p>The two containers can now be started jointly with the following suggested command (replace the path with your docker-compose.yml location):</p>
<pre><kbd>docker-compose -f [path to docker-compose.yml] up --force-recreate -d</kbd></pre>
<p>The web UI service should now be up and running on <a href="http://localhost:9000/">http://localhost:9000/</a>, which you can access from a browser to manage Nordic Migrator jobs (e.g. validation).</p>
<p><strong>Please note that adding e.g. <code>restart: always</code> 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 <a href="https://docs.docker.com/">Docker documentation</a> to learn more.</strong></p>
<h2>Using the Pipeline 2 Updater</h2>
<p>Note that as of Pipeline 2 v1.13, the minimum required version of Java is 11. It is recommended to install Java from <a href="https://adoptopenjdk.net">https://adoptopenjdk.net</a>.</p>
<ol>
<li>Download and install Pipeline 2 v1.14.1 by following the <a href="https://daisy.github.io/pipeline/Get-Help/User-Guide/Installation/">DAISY Pipeline 2 installation guide</a>.</li>
<li>Use the <a href="https://daisy.github.io/pipeline/Get-Help/User-Guide/Installation/#updater">updater mechanism as described in the installation guide</a>, but using the following URL as the <code>"service"</code>:<br/> <code>"https://nlbdev.github.com/nordic-epub3-dtbook-migrator/releases/"</code></li>
</ol>
<h1><a name="resources" class="anchor" href="#resources"><span class="octicon octicon-link"></span></a>Resources</h1>
<h2>General</h2>
<ul>
<li><a href="https://github.com/nlbdev/nordic-epub3-dtbook-migrator/issues/">Issue tracker (GitHub; report issues here)</a></li>
<li><a href="https://format.mtm.se/nordic_epub/2020-1/">Nordic Guidelines for the Production of Accessible EPUB 3 (Version: 2020-1)</a></li>
<li><a href="https://format.mtm.se/nordic_epub/2015-1/">Requirements for Quality Content Production in EPUB 3.0/XHTML (Version: 2015-1)</a></li>
<li><a href="resources/dtbook_markup_requirements_2011-2_v_1.docx">Requirements for Text and Image Quality and Markup with DTBook XML (Version: 2011-2)</a></li>
</ul>
<h2>Mapping and validation</h2>
<p><strong>NB, conversion between EPUB 3 and DTBook is currently only supported for 2015-1 guidelines.</strong></p>
<ul>
<li><a href="schemadoc/2020-1/index.html">List of 2020-1 validation rules</a></li>
<li><a href="schemadoc/2015-1/index.html">List of 2015-1 validation rules</a></li>
<li><a href="mapping.html">Documentation for the mapping between HTML and DTBook</a> (2015-1, not normative)</li>
<li><a href="classes.html">Documentation for the classes used in the Nordic EPUB3 profile</a> (2015-1, not normative)</li>
</ul>
<h2>Tool user guides</h2>
<ul>
<li><a href="guide/index.html">Nordic EPUB3/DTBook Migrator User Guide (web interface)</a> <strong>Please note: The book categories mentioned at the end are outdated and not applicable to present/coming contracts with the Nordic Agencies</strong></li>
<li><a href="https://daisy.github.io/pipeline/Get-Help/User-Guide/">DAISY Pipeline 2 User Guide</a></li>
</ul>
</article>
</div>
</div>
<footer>
<div class="owner">
<p><a href="https://github.com/nlbdev" class="avatar"><img src="https://avatars3.githubusercontent.com/u/6852279?s=60" width="48" height="48"/></a> <a href="https://github.com/nlbdev">nlbdev</a> maintains <a href="https://github.com/nlbdev/nordic-epub3-dtbook-migrator">Nordic EPUB3/DTBook Migrator</a></p>
</div>
<div class="creds">
<small>This page generated using <a href="https://pages.github.com/">GitHub Pages</a><br/>theme by <a href="https://twitter.com/jonrohan/">Jon Rohan</a></small>
</div>
</footer>
</div>
<div class="current-section">
<a href="#top">Scroll to top</a>
<a href="https://github.com/nlbdev/nordic-epub3-dtbook-migrator/tarball/master" class="tar">tar</a><a href="https://github.com/nlbdev/nordic-epub3-dtbook-migrator/zipball/master" class="zip">zip</a><a href="" class="code">source code</a>
<p class="name"></p>
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-51973045-1");
pageTracker._trackPageview();
} catch(err) {}
</script>
</body>
</html>