如何利用 Sigil 和 EpubCheck 插件检查和修复 EPUB 文件

如何利用 Sigil 和 EpubCheck 插件检查和修复 EPUB 文件

2022-09-04 举报

使用 EpubCheck 插件的目的是找出所有可能导致 EPUB 文件推送失败的问题,以便用 Sigil 进行修复。导致 EPUB 推送失败的问题大多出在 content.opf 和 toc.ncx 这两个文件上,因此尽量根据验证结果中的提示信息进行修复,确保其不会出现与这两个文件相关的错误信息。

一、为 Sigil 安装 EpubCheck 插件

首先需要确保你已经安装了 Sigil,通过下面提供的链接下载 EpubCheck 插件压缩包,依次点击 Sigil 菜单【Plugins(插件) → Manage Plugins(插件管理)】,在弹出对话框中点击【Add Plugin(添加插件)】,选择插件压缩包,点击【打开】按钮即可完成安装。

插件安装成功后会出现在 Sigil 的插件列表中,如下图所示:

为Sigil安装EpubCheck插件

注意,运行 Sigil 的 EpubCheck 插件需要确保你的操作系统安装了 Java 环境,安装 JRE(Java Runtime Environment)或 JDK(Java Development Kit)均可。如果已安装可忽略此步骤,否则可在以下链接中任选其一下载安装。若非以 Java 开发为目的,推荐安装体积更小的 JRE。

* 提示:如果你使用的 Sigil 版本号小于 0.9.0,还需要确保你的操作系统安装了 Python 。

二、用 EpubCheck 插件验证 EPUB

用 EpubCheck 插件验证 EPUB 的具体方法为:用 Sigil 打开 EPUB 文件,依次点击 Sigil 的菜单【插件(Plugins) → 有效性(Validation) → EpubCheck】即可对其进行检测。

待插件检查完毕后(时间长短因文件大小而异),会在 Sigil 界面下方弹出“验证结果”,结果中会列出当前 EPUB 文件所有违 EPUB 规范的地方,如下图所示:

EpubCheck验证EPUB文件后的结果

验证结果会以表格的形式列出,每一行表示一个具体问题,你可以通过四个栏目查看某个问题的具体信息。这四个栏目的表头含义分别如下所示:

  • 文件(File):问题涉及代码所在文件。
  • 行(Line):问题涉及代码所在文件中的行号。如果值为 N/A 表示元素缺失。
  • 偏移(Offset):问题涉及代码相对于所在文件中所有字符的偏移量。
  • 错误信息(Message):问题涉及代码所在文件中的列号,以及导致该问题的具体提示。

所幸,除了行号值为 N/A 的行,我们不必根据这些信息手动去查找问题涉及代码所在具体位置,只需要双击相应行就可以自动定位了。注意,有时可能多个行对应同一个问题。

对于行号值为 N/A 的行,表示文件中缺失某种 EPUB 规范中规定的必须存在的元素,你需要根据“错误信息”中给出的提示,参考 EPUB2 或 EPUB3 规范自行添加。不过通常这种问题不会影响推送,除非其它问题修复后仍然推送失败,否则可以暂时忽略这种问题。

* 提示:判断 EPUB 使用的是 EPUB2 规范还是 EPUB3 规范,可以通过其 OPF 文件中 <package> 元素的 version 属性值进行确认,如果该值是 2.0 说明是 EPUB2,如果是 3.0 就是 EPUB3。

如前文所述,大多数情况下最需要关注的是 content.opf 和 toc.ncx 这两个文件存在的问题,除非这两个文件修复完仍然推送失败,其它 CSS 或 XHTML 文件中出现的问题都不太会影响推送。

二、根据验证结果修复存在的问题

通常 EpubCheck 给出的错误信息足以作为修复问题的线索。如果英文读起来吃力,可以单击某一行的“错误信息”栏,然后按快捷键 Ctrl + C 将相应的文本内容复制下来,就可以借助“Google 翻译”之类的翻译服务帮助理解了。下面举个例子来说明一下如何修复 EPUB 文件中存在错误。

假设验证某个 EPUB 文件得到如下所示结果,显示 content.opf 和 toc.ncx 文件存在一些问题:

验证结果
文件 偏移 错误信息
content.opf N/A N/A Col: -1: ERROR(OPF-030): The unique-identifier “BookId” was not found.
content.opf 19 1022 Col: 91: ERROR(RSC-005): Error while parsing file: The “id” attribute does not have a unique value
content.opf 30 2070 Col: 74: ERROR(RSC-005): Error while parsing file: The “id” attribute does not have a unique value
content.opf 19 1022 Col: 91: ERROR(RSC-005): Error while parsing file: attribute “properties” not allowed here; expected attribute “fallback”, “fallback-style”, “required-modules” or “required-namespace”
content.opf 14 771 Col: 39: ERROR(RSC-005): Error while parsing file: attribute “property” not allowed here; expected attribute “content”, “id”, “name”, “scheme” or “xml:lang”
content.opf 14 771 Col: 39: ERROR(RSC-005): Error while parsing file: element “meta” missing required attributes “content” and “name”
content.opf 14 791 Col: 59: ERROR(RSC-005): Error while parsing file: text not allowed here; expected the element end-tag
toc.ncx N/A N/A Col: -1: ERROR(NCX-001): NCX identifier (“”) does not match OPF identifier (“9787532777686”).

乍一看问题有很多,但是仔细分析就会发现,有很多行号是重复的,这就说明那一行中同时存在多种问题,有可能修复一处就能消除这些问题。下面我们就来逐个演示修复问题的思路。

表中第 1 行,即行号的值为 N/A 的那一行的错误信息示为:唯一标识符“BookID”未找到。

一般情况下这表示缺失了某个元素。根据 EPUB2 规范中的说明,OPF 文件中根元素 <package> 必须为其属性 unique-identifier 指定一个值,该值必须和元数据元素 <identifier> 的 id 属性值相同。但是在本例中,根元素 <package> 的 unique-identifier 属性值是 BookId,元素 <identifier> 的 id 属性值却是如下所示的 ISBN,因此出现了上述错误提示。

...
<dc:identifier id="ISBN">9787532777686</dc:identifier>
...

分析出原因后,就可以如下所示按照 EPUB 规范修正这一行代码:

...
<dc:identifier id="BookId" opf:scheme="ISBN">9787532777686</dc:identifier>
...

表中第 2、3 行的错误信息同为:“id”属性没有唯一值。这说明同一个 id 属性在两个元素中出现了两次,通过双击这两行定位到具体代码后可以发现,行号为 19 和 30 那两个元素不仅是 id 属性出现了重复,href 属性引用的资源也是重复的。而另一个行号为 19 的错误信息为:属性“properties”不允许出现在这里。这说明元素中出现了不该出现的 properties 属性。

...
<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" properties="nav"/>
...
<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
...

分析出原因后,就可以对这两个元素去重,并去掉不应该出现在元素中的属性:

...
<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
...

提示:如果仅仅是元素的 id 属性出现了重复,而 href 属性指向的资源没有重复,只需要将 id 的属性值改成不相同的即可。如果是 href 属性指向的资源是重复的,就不用管 id 是否重复,直接去重即可。

表中第 5、6、7 行的错误信息同时出现在行号 14 上,分别为:属性“property”不允许出现在这里、元素“meta”缺失属性“content”和“name”、文本不允许出现在这里;预期的是元素结束标签。这些错误表明,电子书的制作者将 EPUB3 的规范用在了 EPUB2 上,错误地使用了 <meta> 元素,在 EPUB2 规范中该元素类似于 XHTML 1.1 规范中的 <meta> 元素,这是一个不能包含文本的空元素,在 EPUB2 中通常会使用 name 和 content 这两个属性。

...
<meta property="dcterms:modified">2018-05-19T09:41:10Z</meta>
...

EPUB2 规范中显示 <meta> 元素是可选的,因此,方便起见,你可以直接将这行代码删除。如果由于某种原因需要保留此元数据,需要更改成如下所示符合 EPUB2 规范的形式:

...
<meta name="dcterms:modified" content="2018-05-19T09:41:10Z"/>
...

表中最后一行的错误来自 toc.ncx 文件,错误信息为:NCX 标识符(“”)与 OPF 标识符(“9787532777686”)不匹配。根据 EPUB2 规范中的说明,NCX 文件中必须包含一个 <meta> 元素,其 name 属性值为 dtb:idcontent 属性值要引用 OPF 中 identifier 元素的值。而在本例中,NCX 文件中 <meta> 元素的 content 属性值却为空,因此出现了上述错误提示。

...
<meta name="dtb:uid" content=""/>
...

解决方法很简单,直接将 OPF 文件中元数据元素 identifier 的值拷贝过来即可:

...
<meta name="dtb:uid" content="9787532777686"/>
...

至此,示例中 content.opf 和 toc.ncx 这两个文件存在的所有错误就修复完成了。当然并非所有错误都会导致推送失败,比如上面这个例子中,导致推送失败的是表中的第 2、3、4 条错误,其它的其实并不影响推送,但是如果不是太难解决,还是建议一次性解决,以避免重复测试推送。

上面这些对 EPUB 文件的修复操作仅提供一种解决问题的思路,并不能覆盖所有 EPUB 文件中可能出现的错误,你可以参照这些思路,尝试解决你遇到的具体问题。书伴总结了一些推送 EPUB 文件时出现频率较高推送失败原因可供参考,同时欢迎留言分享你的经验。

好书推荐
筠溪集
筠溪集

宋代诗文别集。24卷。李迩逊撰。卷1至卷3为奏议,卷4、卷5为外制,卷6为表、状,卷7为书、启,卷8至卷10为议古,卷11至卷20为诗,卷21为杂著、题跋,卷22为铭、赞、序、记,卷23为祭文,卷24为墓志铭、塔铭。卷首载楼钥序,卷末附乐府1卷,另附《筠溪李公家传》及作者之孙李珏跋各1篇。李珏跋称:“大父捐馆之日,先君尚幼,遗墨散失,旋传录于亲友家,所辑文稿仅有二十四卷,其间脱误居多。”楼钥序称李迩逊归隐西山16年,“不复有仕宦意,哦诗自娱,笔力愈伟”。朱熹对其《宿观妙堂诗》也甚为倾倒。李珏跋则盛赞其文章:“烟林云峤,幅巾杖屦,趣深理到,追轶风骚,意寄高远,经渊史薮,据古鉴今,乱阶治迹,贯穿敷陈。”本集除收入《四库全书》,还影印编进《四库全书珍本初集》。其上海图书馆所藏明抄本又题作《竹溪先生文集》(简称《竹溪集》),内容与《四库全书》本《筠溪集》相同。

李弥逊
郧溪集
郧溪集

诗文别集。北宋郑獬(1022—1072)撰。二十八卷。獬字毅夫,安陆(今湖北云梦)人。皇祐进士。知制诰,拜翰林学士,权知开封府。王安石恶之,以侍读学士出知杭州,徙青州。有集原五十卷,淳熙十三年(1186)秦焴尝序而刊之。久佚。此本乃四库馆臣从《永乐大典》内裒辑编次,又以《宋文鉴》、《两宋名贤小集》所载分类补入。含制七卷,诏二卷,口宣一卷,表状等三卷,书、记、解等五卷,祝文一卷,墓志铭三卷,诗六卷。其文章宗旨源出韩愈,内容多涉时政。史称其文章豪伟峭整,议论剀切,精练民事。有《四库全书》本。另有《两宋名贤小集》本,收有《幻云居诗稿》一卷。载其诗二十五首,多即景抒怀之作。

郑獬
知非堂稿
知非堂稿

元代诗文别集。何中撰。《四库全书》曾据江西巡抚采进本,将《知非堂稿》6卷编入别集类,但这6卷全是诗。6卷本《知非堂稿》卷首有元至顺二年(1331)吴澂序,元延祐七年(1320)何中自序。自序中提到除《知非堂稿》之外,尚有《知非堂外稿》16卷。6卷本《知非堂稿》卷1—2为五言古诗,卷3为五言律诗及排律,卷4为七言古诗,卷5为七言律诗及排律,卷6为七言绝句,但《四库全书总目》已指出:顾嗣立《元诗选》所选载《知非堂稿》为17卷,王士禛《居易录》中提到的《知非堂稿》为16卷,卷数均与6卷本不一致,或许是由于后人传写时曾合并其卷数。然而16卷、17卷的《知非堂稿》都未流传到今天,已难于判断它们与6卷本的关系。今存何中文集,尚有清道光、咸丰年间刊行的《何太虚文集》10卷,其中1—6卷全同于6卷本《知非堂稿》,另收有《知非堂外稿》4卷。此外还有11卷本《知非堂稿》行于世,今仅见有清抄本,卷首有明洪武二十九年(1396)黄德民序、延祐七年何中自序、元统二年(1334)揭傒斯序。其中1—6卷也是诗,7—11卷是文。据以上情况可知6卷本《知非堂稿》是不全的本子。

何中
贞素斋集
贞素斋集

元代诗文别集。8卷,附录2卷。舒頔撰。《四库全书》曾据浙江鲍士恭家藏本编入别集类。本集有数种清抄善本,又有1种清抄本,仅残存10卷,现藏安徽省图书馆。8卷本《贞素斋集》卷首有明洪武四年(1371)舒頔自序,《贞素斋自传》。在自序中,舒頔说:“虽居离乱中,艰难险阻千情万状,独于诗未尝忘情。”自传中进一步说自己“喜为文章,人求记述,则欣然命笔,未尝以事辞”,“又喜咏歌,或古风长律,取意而足,不蹈袭,不求奇,务在理胜”。足见舒頔对于写作是十分认真的。卷1为记,卷2为序,卷3为辨、碑、跋、文,卷4为传、赋、说、墓志铭等文体,卷5-6为古体诗,卷7为五七言近体(包括1首六言绝句),卷8为七言长律、词。附录卷1为《贞素斋铭》,《贞素斋记》等资料及明洪武十二年张梓撰《舒公行状》。附录卷2为舒远的《北庄遗稿》(卷首有8世孙舒孔昭写的题识)及舒逊的《可庵搜枯集》。舒頔在《贞素斋自传》中说:“三为教官,遭时抢攘,遂退处教授私塾,所居曰贞素斋。”因此,舒頔把文集题为《贞素斋集》。本集为舒頔后裔舒旭、舒孔昭辑刊于明嘉靖年间,由当时的绩溪知县赵春出资刻印。舒頔的诗以七言古体最为擅场,他的文章比较讲究法度,但成就不如诗。

舒頔
贞白遗稿
贞白遗稿

十卷。附《显忠录》二卷。明程通撰。程通,字彦亨,斋名贞白。安徽绩溪人。生卒年未详。洪武十八年(1385)贡入太学。二十三年(1390)举应天(今江苏南京)乡试。时方遣诸王将兵,因以封建、策贡士于廷。程通所对称旨,擢第一。授辽府纪善,进左长史。朱棣继位,程通上书数千言,论战守大计。永乐初,锦衣卫都督纪纲发其事,诏械程通诣京师,与二子俱论死。事迹具《明史》本传。所著述凡百余卷,悉毁于官。后十年,其弟赴荆州,辽王以所图程通像及遗稿授之。嘉靖中,党禁渐弛,其从孙长等乃搜访佚篇,裒为六卷。附以辽王并同时诸人赠言及行状、小传等篇,别为四卷。天启中,其裔孙枢及子应阶又集前后建祠请谥之文,为显忠录二卷,附缀于末。即此本。初,程通以祖平久戍陈情乞赐还乡,人称其孝。及建文中,遭逢国难,上防御封事,而卒以是死,人称其忠。今陈情之表具在,而封事独有题无文。盖嘉靖中刻集时,犹有所讳而不敢存。封建二策,乃其受知于太祖,持议颇正。其他诗文,亦俱醇朴有法。虽所存无多,而大节凛然,有不仅以词章论者,固宜与方练诸集并传不朽。本书有浙江孙仰曾家藏本。

程通
可通过以下方式联系我们