nlbdev/nordic-epub3-dtbook-migrator

Nordic EPUB3/DTBook Migrator

项目状态

当前工作重点：

• 完成并发布根据2020-1指南验证EPUB的官方版本
• 移除对Pipeline 2的依赖

有关当前开发阶段的更多详情：https://github.com/nlbdev/nordic-epub3-dtbook-migrator/issues/522

2015年

本项目的最初目标是为北欧国家的图书馆提供EPUB3到DTBook的转换工具，这些图书馆为视障读者提供无障碍文献（NLB、MTM、SPSM、Celia、Nota和SBS）。转换通过XProc和XSLT实现，并以DAISY Pipeline 2脚本形式提供。此转换允许各组织在必要时继续使用其基于DTBook的工具生产盲文和合成语音，并在生产工具准备就绪后逐步过渡到EPUB。

该工具尝试以最小损失将EPUB3映射到DTBook（1:1映射）。尽管EPUB3内部由多个HTML文件组成，但中间的单页HTML表示对于与DTBook之间的转换非常有用。

2020年

2020年启动了指南修订工作。参与组织包括Celia、Dedicon、HBS、MTM、NLB、Nota、SBS、SPSM和Statped。

因此，需要更新验证器，并实现了针对新指南的EPUB验证。目前（至少尚未）不存在指南旧版本（EPUB 2015-1或DTBook 2011-2）与新版本（EPUB 2020-1）之间的转换路径。

脚本

本项目提供以下Pipeline 2脚本：

• EPUB3转DTBook
• EPUB3转HTML
• EPUB3验证器
• EPUB3 ASCIIMath转MathML
• HTML转EPUB3
• HTML转DTBook
• HTML验证器
• DTBook转EPUB3
• DTBook转HTML
• DTBook验证器

目前唯一支持2020-1指南的脚本是EPUB3验证器。

EPUB3转DTBook脚本允许新的EPUB3文件与遗留的基于DTBook的系统一起使用。

DTBook转EPUB3脚本允许将遗留DTBook升级到新的基于EPUB3的生产系统。

还提供了用于在出版物的中间单HTML表示之间转换的脚本。这些脚本可用于调试，或当基于HTML的生产系统需要单文档HTML表示作为输入或输出时使用。

提供了EPUB3、DTBook和单文档HTML文件的验证器。EPUB3验证器可检查新EPUB3文件是否符合北欧标记指南。DTBook和HTML验证器可用于基于DTBook或HTML的生产系统。

在北欧标记指南（2015-1版）中，数学内容使用ASCIIMath标记。提供了将ASCIIMath转换为MathML的实验性脚本。

EPUB3、HTML和DTBook文件中使用的语法是EPUB3、HTML和DTBook的严格子集，由北欧标记指南定义。大多数DTBook可与这些脚本一起使用，对输入DTBook语法的限制很少。然而，对HTML/EPUB3语法的限制较多，因为必须有转换为DTBook的方法。最值得注意的是，这些EPUB3目前不允许包含音频和视频等多媒体。

构建

安装依赖：

bash
sudo apt install git maven gpg

克隆仓库：

bash
git clone https://github.com/nlbdev/nordic-epub3-dtbook-migrator.git

Nordic Migrator可通过Maven直接构建（例如mvn clean package），或通过Docker间接构建（例如docker build .）。

测试是构建过程的一部分，但也可显式调用：mvn test。

发布

首先，确保您拥有GPG密钥：https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key

并确保在~/.gnupg/gpg.conf中将GPG密钥设置为默认：

default-key ABCDEF123

将GitHub凭据添加到本地~/.m2/settings.xml（应使用个人访问令牌作为密码）：

xml
  <server>
    <id>github</id>
    <username><!-- 您的github用户名 --></username>
    <password><!-- 您的个人访问令牌 --></password>
  </server>

发布惯例是从功能分支或专用发布分支发布，然后通过合并提交合并到master分支。

准备发布：

bash
mvn release:prepare

系统将提示：

• 发布版本是什么（…）？ - 使用语义化版本控制选择版本号。对于错误修复等，默认值（递增的补丁版本号）即可
• SCM发布标签或标签是什么（…）？ - 我们使用的标签是“v”后跟发布版本，这也是默认建议
• 新的开发版本是什么（…）？ - 使用默认值，即发布版本递增补丁版本并添加“-SNAPSHOT”后缀

此时，Maven将更新POM中的版本并运行所有测试，这需要几分钟时间。

完成后，在git日志中会看到：

HEAD        [maven-release-plugin] prepare for next development iteration
tag: vX.X.X [maven-release-plugin] prepare release vX.X.X

然后，可使用以下命令发布发布工件：

bash
mvn release:perform

同时，记得将标签推送到上游：

git push origin vX.X.X

项目设置为使用mvn-repo分支作为Maven仓库，工件将发布到该分支。

如果要在另一个项目中使用nordic migrator作为Maven包，请将此仓库添加到项目中：

xml
    <repository>
        <id>nordic-epub3-dtbook-migrator-mvn-repo</id>
        <url>https://github.com/nlbdev/nordic-epub3-dtbook-migrator/raw/mvn-repo/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
    </repository>

Docker镜像

带有版本标签的提交会在Docker Hub上自动构建和标记。标签由mvn release:prepare自动创建，当使用git push origin vX.X.X将git标签推送到Github时，webhook会通知Docker Hub构建新镜像。

master分支上的所有提交都会在Docker Hub上构建，最新提交可通过:latest标签获取。

参考资料

有关更多信息，请参见http://nlbdev.github.io/nordic-epub3-dtbook-migrator/%E3%80%82