aboutsummaryrefslogtreecommitdiffhomepage
path: root/src/sisudoc/outputs/io_out/epub3.d
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-13 20:53:26 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-09-14 12:18:51 -0400
commit6835275408e1629f450d163e0cc5221c977e87d2 (patch)
treeac35771a889a4766d8efc89af5f78e91fa99e3d3 /src/sisudoc/outputs/io_out/epub3.d
parentregex: confine url within an endnote (delimiter) (diff)
epub and html: no errors left over the sample set
epubcheck 5.3.0 over the 35 sample epubs went from 1302 remaining errors to none. The six causes for those remaining errors fixed here. most of the count was one of them: - Tables (1123 errors, 86%) where the writer emitted obsolete attributes, removed in 2014; table also now in div instead of a paragraph. also fixed: - Navigation (115). Every level 4 heading's nav entry ended "#0", the ocn of an object that has no ocn and so no id. - Duplicate ids (37). (from three unrelated sources). - The publication identifier (27 warnings). dc:identifier was a hardcoded hex string, not a UUID, and the same one in all 35 files, so two documents in one library collided. It is now UUID v5 over the document's own uid: a real RFC 4122 identifier, stable across builds and distinct per document. - Image manifest entries (15). media-type was "image/" plus the file extension, giving "image/jpg", which is not a media type; epubcheck reads it as a foreign resource and wants a fallback. There is now a mapping, which also covers svg and webp. Item ids came from the file basename, and "2bits_02_01-100.png" gave an id starting with a digit, which is not an XML name; ids are now prefixed and sanitised. - An ocn resolving to no segment (9). A poem block and its first verse share one ocn; the verses are written into a segment and the block itself is not. Also dropped from the package document: an xmlns:xsi that nothing used, and a prefix declaration for the rendition vocabulary, which is a reserved prefix and needed no declaring. The package now carries xml:lang. test-epub-validity.sh now allows no fatal and no error. Two NAV-011 warnings remain and are described in it. Three reference .ssp files change, all of them the anchor tag disambiguation above. (assisted by Claude-Code)
Diffstat (limited to 'src/sisudoc/outputs/io_out/epub3.d')
-rw-r--r--src/sisudoc/outputs/io_out/epub3.d68
1 files changed, 56 insertions, 12 deletions
diff --git a/src/sisudoc/outputs/io_out/epub3.d b/src/sisudoc/outputs/io_out/epub3.d
index b00165d..420c536 100644
--- a/src/sisudoc/outputs/io_out/epub3.d
+++ b/src/sisudoc/outputs/io_out/epub3.d
@@ -77,6 +77,45 @@ template outputEPub3() {
.replaceAll(rgx.nbsp_char, " ");
return _txt;
}
+ /+ ↓ a manifest item id, which has to be an XML name.
+ An XML name may not begin with a digit, and a file quite happily
+ may: "2bits_02_01-100.png" gave id="2bits_02_01-100", which is not
+ a name. A prefix settles the first character, and anything else a
+ filename allows and a name does not becomes an underscore. +/
+ string _manifest_id(string _prefix, string _name) {
+ string _id;
+ foreach (c; _name) {
+ _id ~= ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')
+ || (c >= '0' && c <= '9') || c == '_' || c == '-' || c == '.')
+ ? c : '_';
+ }
+ return _prefix ~ "_" ~ _id;
+ }
+ /+ ↓ the media type of an image, which is not its file extension.
+ There is no "image/jpg"; a manifest that claims one is declaring a
+ foreign resource, and EPUB then demands a fallback for it. The
+ core image types are these, and anything else genuinely is
+ foreign. +/
+ string _image_media_type(string _ext) {
+ switch (_ext.toLower) {
+ case "jpg": case "jpeg": return "image/jpeg";
+ case "png": return "image/png";
+ case "gif": return "image/gif";
+ case "svg": case "svgz": return "image/svg+xml";
+ case "webp": return "image/webp";
+ default: return "image/" ~ _ext.toLower;
+ }
+ }
+ /+ ↓ the publication identifier, as a real RFC 4122 UUID.
+ Version 5, name based: the name is the document's own uid, so the
+ identifier is stable across rebuilds and distinct per document,
+ which is what dc:identifier is for. A random v4 would be neither.
+ The namespace is v5 of "sisudoc.org" under the DNS namespace. +/
+ string _epub_publication_uuid(string _doc_uid) {
+ import std.uuid : sha1UUID, dnsNamespace;
+ auto _ns = sha1UUID("sisudoc.org", dnsNamespace);
+ return sha1UUID(_doc_uid, _ns).toString;
+ }
/+ ↓ the last modified time, as EPUB3 requires it: exactly one dcterms:modified
on the package, in UTC to the second, CCYY-MM-DDThh:mm:ssZ
+/
@@ -105,11 +144,10 @@ template outputEPub3() {
string epub3_oebps_content(D,P)(D doc, P parts) {
auto xhtml_format = outputXHTMLs();
auto pth_epub3 = spinePathsEPUB!()(doc.matters.output_path, doc.matters.src.language);
- string _uuid = "18275d951861c77f78acd05672c9906924c59f18a2e0ba06dad95959693e9bd8"; // TODO sort uuid in doc.matters!
+ string _uuid = _epub_publication_uuid(doc.matters.src.doc_uid_out);
string content = format(q"┃<?xml version="1.0" encoding="utf-8"?>
- <package version="3.0" xmlns="http://www.idpf.org/2007/opf" unique-identifier="bookid" prefix="rendition: http://www.idpf.org/vocab/rendition/#">
+ <package version="3.0" xmlns="http://www.idpf.org/2007/opf" unique-identifier="bookid" xml:lang="%s">
<metadata
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:identifier id="bookid">urn:uuid:%s</dc:identifier>
@@ -126,6 +164,7 @@ template outputEPub3() {
<item id="css" href="%s" media-type="text/css"/>
<item id="nav" href="toc_nav.xhtml" media-type="application/xhtml+xml" properties="nav" />
┃",
+ doc.matters.src.language,
_uuid,
xhtml_format.special_characters_plain(doc.matters.conf_make_meta.meta.title_main),
(doc.matters.conf_make_meta.meta.title_sub.empty) ? "" : format(
@@ -145,14 +184,13 @@ template outputEPub3() {
(pth_epub3.fn_oebps_css).chompPrefix("OEBPS/"),
);
content ~= parts["manifest_documents"];
- // TODO sort jpg & png
foreach (image; doc.matters.srcs.image_list) {
- content ~= format(q"┃ <item id="%s" href="%s/%s" media-type="image/%s" />
+ content ~= format(q"┃ <item id="%s" href="%s/%s" media-type="%s" />
┃",
- image.baseName.stripExtension,
+ _manifest_id("img", image.baseName.stripExtension),
(pth_epub3.doc_oebps_image).chompPrefix("OEBPS/"),
image,
- image.extension.chompPrefix("."),
+ _image_media_type(image.extension.chompPrefix(".")),
);
}
content ~= " " ~ "</manifest>" ~ "\n ";
@@ -251,8 +289,14 @@ template outputEPub3() {
_new_title_set = true;
} else {
_new_title_set = false;
+ /+ ↓ a fragment only where there is one to reach.
+ A heading of level 4 or less is the top of its own
+ file, so the file is the target. A heading below
+ that sits inside a file and carries id="<ocn>", so
+ that is the fragment. An object with no ocn has no
+ id, and "#0" was pointing at nothing. +/
string _hashtag = "";
- if ((obj.metainfo.heading_lev_markup <= 4) && (obj.metainfo.ocn == 0)) {
+ if ((obj.metainfo.heading_lev_markup > 4) && (obj.metainfo.ocn > 0)) {
_hashtag = "#" ~ obj.metainfo.ocn.to!string;
}
string _href = "<a href=\""
@@ -575,15 +619,15 @@ template outputEPub3() {
) {
_segment_files_seen[obj.tags.segment_anchor_tag_epub] = true;
oepbs_content_parts["manifest_documents"] ~=
- format(q"┃<item id="%s.xhtml" href="%s.xhtml" media-type="application/xhtml+xml" />
+ format(q"┃<item id="%s" href="%s.xhtml" media-type="application/xhtml+xml" />
┃",
- obj.tags.segment_anchor_tag_epub,
+ _manifest_id("seg", obj.tags.segment_anchor_tag_epub),
obj.tags.segment_anchor_tag_epub,
);
oepbs_content_parts["spine"] ~=
- format(q"┃<itemref idref="%s.xhtml" linear="yes" />
+ format(q"┃<itemref idref="%s" linear="yes" />
┃",
- obj.tags.segment_anchor_tag_epub,
+ _manifest_id("seg", obj.tags.segment_anchor_tag_epub),
);
}
}