aboutsummaryrefslogtreecommitdiffhomepage
path: root/src/sisudoc/outputs/io_out/xmls.d
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-13 21:56:43 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-09-14 12:18:51 -0400
commiteb5a9f3dab1d1848a1aa90c534a125c222327635 (patch)
tree92e53a0c8cf7c3d3dddef14d82730cdf99b6e4b9 /src/sisudoc/outputs/io_out/xmls.d
parentepub and html: no errors left over the sample set (diff)
images alt text, and epub says what it is
Four things, not visible in an error count: - Images had no alt text, even where markup carried the text, and the field alt text is present, incorrectly used in code; fixed as the alt. { sm_tux.png 64x80 "Gnu/Linux - a better way" }image an image with nothing to say for itself gets alt="" - Images with no dimensions were incorrectly written width="0" height="0", fixed - Accessibility metadata, which EPUB Accessibility 1.1 requires: schema:accessMode, accessibilityFeature and accessibilityHazard, plus accessModeSufficient and accessibilitySummary, which epubcheck does not test for; used by - readers looking for a book it can use, - anyone distributing into the EU. Every value is derived from the document, not asserted: a document with no images says so, one whose images all carry alt text claims alternativeText and textual sufficiency, one where an image says nothing claims neither. Nothing claims WCAG conformance, which would be a claim about an evaluation that has not happened. - DPUB-ARIA roles beside the structure spine already knew about. doc-toc, doc-endnotes, doc-bibliography, doc-glossary and doc-index on the sections, doc-noteref on a note reference and doc-footnote on the note it points at. "doc_endnotes" as a class name means something to a stylesheet and nothing to a reading system. Not doc-biblioentry: DPUB- ARIA 1.1 deprecated it. These are plain ARIA, so the html gets them too. Also dealt with here: - Spine makes certain sections such as endnotes, bookindex, ... and a heading that has a name for itself cannot share the same name, if it does the name is now disambiguated, disambiguated. (disambiguation similar to that used for a repeated anchor tag) - Endnote anchors fixed to use "id" (being one unique tag in the document that is target of every reference to it)instead of obsolete form (they were <a name="note_1">. "name" on an <a>). Book index markers keep "name": the same marker sits on every object an entry names, 296 times in one document, and those are markers of where a term occurs rather than distinct targets. (assisted by Claude-Code)
Diffstat (limited to 'src/sisudoc/outputs/io_out/xmls.d')
-rw-r--r--src/sisudoc/outputs/io_out/xmls.d130
1 files changed, 110 insertions, 20 deletions
diff --git a/src/sisudoc/outputs/io_out/xmls.d b/src/sisudoc/outputs/io_out/xmls.d
index c1e733e..4ce5434 100644
--- a/src/sisudoc/outputs/io_out/xmls.d
+++ b/src/sisudoc/outputs/io_out/xmls.d
@@ -78,13 +78,13 @@ template outputXHTMLs() {
delimit_ ~= "\n<div class=\"doc_title\">\n" ;
break;
case "toc":
- delimit_ ~= "\n<div class=\"doc_toc\">\n" ;
+ delimit_ ~= "\n<div class=\"doc_toc\"" ~ _section_role(section) ~ ">\n" ;
break;
case "bookindex":
- delimit_ ~= "\n<div class=\"doc_bookindex\">\n" ;
+ delimit_ ~= "\n<div class=\"doc_bookindex\"" ~ _section_role(section) ~ ">\n" ;
break;
default:
- delimit_ ~= "\n<div class=\"doc_" ~ section ~ "\">\n" ;
+ delimit_ ~= "\n<div class=\"doc_" ~ section ~ "\"" ~ _section_role(section) ~ ">\n" ;
break;
}
if (previous_section.length > 0) {
@@ -96,6 +96,40 @@ template outputXHTMLs() {
// you also need to close the last div, introduce a footer?
return delimit;
}
+ /+ ↓ the DPUB-ARIA role for a document section.
+ spine has always known what these sections are; the output never
+ said so, and "doc_endnotes" as a class name means something to a
+ stylesheet and nothing to a reading system or a screen reader.
+ These roles are what carry that structure across. They are plain
+ ARIA, valid in html as well as in the epub, so both get them.
+ .
+ A section with no role of its own returns nothing rather than an
+ invented one.
+ +/
+ /+ ↓ and the role of an individual object, where it has one of its own.
+ A gathered endnote is a note body, whatever the section around it
+ says; the reference to it carries doc-noteref at the other end.
+ .
+ Not doc-biblioentry for a bibliography entry: DPUB-ARIA 1.1
+ deprecated it, and the entries sit inside doc-bibliography, which
+ is what a reader needs.
+ +/
+ string _para_role(O)(O obj) {
+ switch (obj.metainfo.is_a) {
+ case "endnote": return " role=\"doc-footnote\"";
+ default: return "";
+ }
+ }
+ string _section_role(string _section) {
+ switch (_section) {
+ case "toc": return " role=\"doc-toc\"";
+ case "endnotes": return " role=\"doc-endnotes\"";
+ case "bibliography": return " role=\"doc-bibliography\"";
+ case "glossary": return " role=\"doc-glossary\"";
+ case "bookindex": return " role=\"doc-index\"";
+ default: return "";
+ }
+ }
string special_characters_text(string _txt) {
_txt = _txt
.replaceAll(rgx_xhtml.ampersand, "&amp;") // "&#38;"
@@ -216,12 +250,29 @@ template outputXHTMLs() {
if (_xml_type == "epub" && _lev == 0) { return 1; }
return (_lev > 6) ? 6 : _lev;
}
+ /+ ↓ the anchors an object carries.
+ "name" on an <a> is obsolete; "id" is what a link target is. The
+ two are not interchangeable here, because these tags are not all
+ link targets. A gathered endnote carries exactly one, "note_<n>",
+ which is unique in the document and is what every reference to it
+ points at, so that one becomes an id.
+ .
+ A book index entry carries the same marker on every object the
+ entry names - "loc" appears 296 times in one document - and those
+ are markers of where a term occurs, not distinct targets. Making
+ them ids would put the same id in a document hundreds of times,
+ so they stay as they are until the book index gives them
+ something unique to be.
+ +/
string _xhtml_anchor_tags(O)(O obj) {
string tags="";
+ bool _is_a_unique_target = (obj.metainfo.is_a == "endnote");
if (obj.tags.anchor_tags.length > 0) {
foreach (tag; obj.tags.anchor_tags) {
if (!(tag.empty)) {
- tags ~= "<a name=\"" ~ special_characters_text(tag) ~ "\"></a>"; /+ repeated markers, not unique targets: see below +/
+ tags ~= (_is_a_unique_target)
+ ? "<a id=\"" ~ special_characters_text(tag) ~ "\"></a>"
+ : "<a name=\"" ~ special_characters_text(tag) ~ "\"></a>";
}
}
}
@@ -552,17 +603,54 @@ string tail(M)(M doc_matters) {
default: break;
}
if (_txt.match(rgx.inline_image)) {
- _txt = _txt
- .replaceAll(rgx.inline_image,
- ("$1<img src=\""
- ~ _img_pth
- ~ "$3\" width=\"$4\" height=\"$5\" /> $6"))
- .replaceAll(
- rgx.inline_link_empty,
- ("$1"));
+ _txt = replaceAll!(m =>
+ m["pre"].to!string
+ ~ _img_element(_img_pth ~ m["img"].to!string, m["width"].to!string,
+ m["height"].to!string, _image_alt(m["post"].to!string))
+ ~ " " ~ _image_rest(m["post"].to!string)
+ )(_txt, rgx.inline_image);
+ _txt = _txt.replaceAll(rgx.inline_link_empty, ("$1"));
}
return _txt;
}
+ /+ ↓ an image's alt text, which markup carries and every writer was
+ throwing away: { tux.png 64x80 "a better way" }image. The project's
+ own markup reference calls it alt text, and it was being left in the
+ visible flow as a quoted string beside the image instead, so no <img>
+ spine wrote had an alt at all.
+ +/
+ string _image_alt(string _post) {
+ if (auto m = _post.matchFirst(rgx.inline_image_alt)) {
+ return m["alt"].to!string;
+ }
+ return "";
+ }
+ /+ ↓ and what is left of the markup once the alt text is taken out of it +/
+ string _image_rest(string _post) {
+ if (auto m = _post.matchFirst(rgx.inline_image_alt)) {
+ return m.post.to!string;
+ }
+ return _post;
+ }
+ /+ ↓ the <img> itself.
+ alt is required, and an image with nothing to say for itself takes
+ alt="", which is the way to say "decorative, skip me". No alt at all
+ is not that, it is an omission, and a reader has to announce the file
+ name instead.
+ .
+ width and height are dropped when there are none. They were written
+ as width="0" height="0", which is a perfectly valid pair of HTML
+ integers meaning zero by zero, so the image did not appear at all;
+ max-width in the stylesheet caps a width and cannot raise one.
+ +/
+ string _img_element(string _src, string _w, string _h, string _alt) {
+ string _dim = (_w == "0" && _h == "0")
+ ? ""
+ : " width=\"" ~ _w ~ "\" height=\"" ~ _h ~ "\"";
+ return "<img src=\"" ~ _src ~ "\""
+ ~ " alt=\"" ~ special_characters_plain(_alt) ~ "\""
+ ~ _dim ~ " />";
+ }
string inline_links(O,M)(
string _txt,
const O obj,
@@ -665,14 +753,14 @@ string tail(M)(M doc_matters) {
_txt = font_face(_txt);
_txt = _txt.replaceAll(
rgx.inline_notes_al_regular_number_note,
- ("<a href=\"#note_$1\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
+ ("<a href=\"#note_$1\" role=\"doc-noteref\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
);
}
if (obj.has.inline_notes_star) {
_txt = font_face(_txt);
_txt = _txt.replaceAll(
rgx.inline_notes_al_special_char_note,
- ("<a href=\"#note_$1\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
+ ("<a href=\"#note_$1\" role=\"doc-noteref\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
);
}
debug(markup_endnotes) {
@@ -699,7 +787,7 @@ string tail(M)(M doc_matters) {
foreach(m; _txt.matchAll(rgx.inline_notes_al_special_char_note)) {
_endnotes ~= format(
"%s%s%s%s\n %s%s%s%s%s %s\n%s",
- "<p class=\"endnote\">",
+ "<p class=\"endnote\" role=\"doc-footnote\">",
"<a href=\"#noteref_",
m.captures[1],
"\">",
@@ -714,7 +802,7 @@ string tail(M)(M doc_matters) {
}
_txt = _txt.replaceAll(
rgx.inline_notes_al_special_char_note,
- ("<a href=\"#note_$1\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
+ ("<a href=\"#note_$1\" role=\"doc-noteref\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
);
}
if (obj.has.inline_notes_reg) {
@@ -723,7 +811,7 @@ string tail(M)(M doc_matters) {
foreach(m; _txt.matchAll(rgx.inline_notes_al_regular_number_note)) {
_endnotes ~= format(
"%s%s%s%s\n %s%s%s%s%s %s\n%s",
- "<p class=\"endnote\">",
+ "<p class=\"endnote\" role=\"doc-footnote\">",
"<a href=\"#noteref_",
m.captures[1],
"\">",
@@ -738,7 +826,7 @@ string tail(M)(M doc_matters) {
}
_txt = _txt.replaceAll(
rgx.inline_notes_al_regular_number_note,
- ("<a href=\"#note_$1\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
+ ("<a href=\"#note_$1\" role=\"doc-noteref\"><span class=\"noteref\" id=\"noteref_$1\">&#160;<sup>$1</sup> </span></a>")
);
} else if (_txt.match(rgx.inline_notes_al_regular_number_note)) {
debug(markup) {
@@ -1012,7 +1100,7 @@ string tail(M)(M doc_matters) {
if (!(obj.metainfo.identifier.empty)) {
o = format(q"┃ <div class="substance">
<label class="ocn"><a href="#%s" class="lnkocn">%s</a></label>
- <p class="%s" data-indent="h%si%s" id="%s">%s
+ <p class="%s" data-indent="h%si%s" id="%s"%s>%s
%s
</p>
</div>┃",
@@ -1026,18 +1114,20 @@ string tail(M)(M doc_matters) {
obj.attrib.indent_hang,
obj.attrib.indent_base,
obj.metainfo.identifier,
+ _para_role(obj),
tags,
_txt
);
} else {
o = format(q"┃ <div class="substance">
- <p class="%s" data-indent="h%si%s">%s
+ <p class="%s" data-indent="h%si%s"%s>%s
%s
</p>
</div>┃",
obj.metainfo.is_a,
obj.attrib.indent_hang,
obj.attrib.indent_base,
+ _para_role(obj),
tags,
_txt
);