/+
- Name: SisuDoc Spine, Doc Reform [a part of]
- Description: documents, structuring, processing, publishing, search
- static content generator
- Author: Ralph Amissah
[ralph.amissah@gmail.com]
- Copyright: (C) 2015 (continuously updated, current 2026) Ralph Amissah, All Rights Reserved.
- License: AGPL 3 or later:
Spine (SiSU), a framework for document structuring, publishing and
search
Copyright (C) Ralph Amissah
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU AFERO General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see [https://www.gnu.org/licenses/].
If you have Internet connection, the latest version of the AGPL should be
available at these locations:
[https://www.fsf.org/licensing/licenses/agpl.html]
[https://www.gnu.org/licenses/agpl.html]
- Spine (by Doc Reform, related to SiSU) uses standard:
- docReform markup syntax
- standard SiSU markup syntax with modified headers and minor modifications
- docReform object numbering
- standard SiSU object citation numbering & system
- Homepages:
[https://www.sisudoc.org]
[https://www.doc-reform.org]
- Git
[https://git.sisudoc.org/]
+/
module sisudoc.outputs.io_out.xmls;
@safe:
template outputXHTMLs() {
import std.file;
import std.outbuffer;
import std.uri;
import std.conv : to;
import sisudoc.outputs.io_out;
import sisudoc.outputs.io_out.rgx;
import sisudoc.ocda.meta.rgx_files;
import sisudoc.outputs.io_out.rgx_xhtml;
import sisudoc.outputs.io_out.zip_pod;
import sisudoc.outputs.io_out.xmls;
import sisudoc.outputs.io_out.xmls_css;
mixin spineRgxOut;
mixin spineRgxXHTML;
struct outputXHTMLs {
static auto rgx = RgxO();
static auto rgx_xhtml = RgxXHTML();
string div_delimit(
string section,
return ref string previous_section
) {
string delimit = "";
string delimit_ = "";
if (section != previous_section) {
switch (section) {
case "head":
delimit_ ~= "\n
";
}
previous_section = section;
delimit ~= delimit_;
}
// 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, "&") // "&"
.replaceAll(rgx_xhtml.quotation, """) // """
.replaceAll(rgx_xhtml.less_than, "<") // "<"
.replaceAll(rgx_xhtml.greater_than, ">") // ">"
.replaceAll(rgx.br_line, " ")
.replaceAll(rgx.br_line_inline, " ")
.replaceAll(rgx.br_line_spaced, " \n ")
.replaceAll(rgx.nbsp_char, " ");
return _txt;
}
/+ the same escaping for where markup cannot go. +/
string special_characters_plain(string _txt) {
_txt = _txt
.replaceAll(rgx.br_line, " ")
.replaceAll(rgx.br_line_inline, " ")
.replaceAll(rgx.br_line_spaced, " ")
.replaceAll(rgx_xhtml.ampersand, "&")
.replaceAll(rgx_xhtml.quotation, """)
.replaceAll(rgx_xhtml.less_than, "<")
.replaceAll(rgx_xhtml.greater_than, ">")
.replaceAll(rgx.nbsp_char, " ");
return _txt;
}
/+ ↓ a date for an attribute value: the same trimming, no markup +/
string special_characters_plain_date(string _txt) {
_txt = _txt
.replaceAll(regex(r"(?:-00)+"), "")
.replaceAll(rgx.br_line, " ")
.replaceAll(rgx.br_line_inline, " ")
.replaceAll(rgx.br_line_spaced, " ")
.replaceAll(rgx.nbsp_char, " ");
return _txt;
}
string special_characters_date(string _txt) {
_txt = _txt
.replaceAll(regex(r"(?:-00)+"), "")
.replaceAll(rgx.br_line, " ")
.replaceAll(rgx.br_line_inline, " ")
.replaceAll(rgx.br_line_spaced, " \n ")
.replaceAll(rgx.nbsp_char, " ");
return _txt;
}
string special_characters_breaks_indents_bullets(O)(
const O obj,
) {
string _txt = special_characters_text(obj.text);
if (obj.metainfo.is_a == "group") {
_txt = (_txt)
.replaceAll(rgx.grouped_para_indent_1,
" ")
.replaceAll(rgx.grouped_para_indent_2,
" ")
.replaceAll(rgx.grouped_para_indent_3,
" ")
.replaceAll(rgx.grouped_para_indent_4,
" ")
.replaceAll(rgx.grouped_para_indent_5,
" ")
.replaceAll(rgx.grouped_para_indent_6,
" ")
.replaceAll(rgx.grouped_para_indent_7,
" ")
.replaceAll(rgx.grouped_para_indent_8,
" ")
.replaceAll(rgx.grouped_para_indent_9,
" ")
.replaceAll(rgx.grouped_para_indent_hang, " ")
.replaceAll(rgx.grouped_para_bullet, "● ")
.replaceAll(rgx.grouped_para_bullet_indent_1,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_2,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_3,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_4,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_5,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_6,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_7,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_8,
" ● ")
.replaceAll(rgx.grouped_para_bullet_indent_9,
" ● ");
}
if (!(obj.metainfo.is_a == "code")) {
_txt = (_txt)
.replaceAll(rgx_xhtml.line_break, " ");
}
return _txt;
}
string font_face(string _txt) {
_txt = _txt
.replaceAll(rgx.inline_emphasis, ("$1"))
.replaceAll(rgx.inline_bold, ("$1"))
.replaceAll(rgx.inline_underscore, ("$1"))
.replaceAll(rgx.inline_italics, ("$1"))
.replaceAll(rgx.inline_superscript, ("$1"))
.replaceAll(rgx.inline_subscript, ("$1"))
.replaceAll(rgx.inline_strike, ("$1"))
.replaceAll(rgx.inline_insert, ("$1"))
.replaceAll(rgx.inline_mono, ("$1"))
.replaceAll(rgx.inline_cite, ("$1"));
return _txt;
}
/+ ↓ the heading element for a markup level.
Markup goes to level 7; HTML stops at h6, and an is simply
not an element, so the deepest three markup levels share h6 and
are told apart by the "heading" class and their ocn. Level 0 is
the document title, which is h1 in a segment of its own.
+/
int _heading_element_level(O)(O obj, string _xml_type) {
int _lev = obj.metainfo.heading_lev_markup.to!int;
if (_xml_type == "epub" && _lev == 0) { return 1; }
return (_lev > 6) ? 6 : _lev;
}
/+ ↓ the anchors an object carries.
"name" on an 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_",
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 ~= (_is_a_unique_target)
? ""
: "";
}
}
}
return tags;
}
string header_metadata(M)(
M doc_matters,
) {
string _publisher="Publisher"; // TODO
string o;
o = format(q"┃
┃",
special_characters_plain(doc_matters.conf_make_meta.meta.title_full),
special_characters_plain(doc_matters.conf_make_meta.meta.creator_author),
_publisher,
special_characters_plain_date(doc_matters.conf_make_meta.meta.date_published),
special_characters_plain(doc_matters.conf_make_meta.meta.date_created),
special_characters_plain(doc_matters.conf_make_meta.meta.date_issued),
special_characters_plain(doc_matters.conf_make_meta.meta.date_available),
special_characters_plain(doc_matters.conf_make_meta.meta.date_valid),
special_characters_plain(doc_matters.conf_make_meta.meta.date_modified),
doc_matters.src.language_tag,
special_characters_plain(doc_matters.conf_make_meta.meta.rights_copyright),
doc_matters.opt.action.generated_by ? special_characters_plain(doc_matters.generator_program.name_and_version) : "",
special_characters_plain(doc_matters.generator_program.url_home),
);
return o;
}
string site_info_button(M)(
M doc_matters,
) {
string _locations;
if (doc_matters.conf_make_meta.make.home_button_text.length > 0) {
_locations = (doc_matters.conf_make_meta.make.home_button_text)
.replaceAll(
rgx.inline_link,
("
┃",
special_characters_text(doc_matters.conf_make_meta.meta.rights_copyright),
((doc_matters.conf_make_meta.meta.rights_license).empty) ? "" : " ",
((doc_matters.conf_make_meta.meta.rights_license).empty) ? ""
: "License: " ~ special_characters_text(doc_matters.conf_make_meta.meta.rights_license)
);
return o;
}
string inline_images(O,M)(
string _txt,
const O obj,
M doc_matters,
string _suffix = ".html",
string _xml_type = "seg",
) {
string _img_pth;
switch (_xml_type) {
case "epub": _img_pth = "image/"; break;
case "scroll": _img_pth = format(q"┃%s/image/┃", "../.."); break;
case "seg": _img_pth = format(q"┃%s/image/┃", "../../.."); break;
default: break;
}
if (_txt.match(rgx.inline_image)) {
_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
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 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 "";
}
string inline_links(O,M)(
string _txt,
const O obj,
M doc_matters,
string _suffix = ".html",
string _xml_type = "seg",
) {
string seg_lvs;
if (obj.has.inline_links) {
if (obj.metainfo.is_a != "code") {
_txt = replaceAll!(m =>
m[1] ~ "┤"
~ (replaceAll!(n =>
n["type"] ~ n["path"] ~ (n["file"].encodeComponent)
)((obj.stow.link[m["num"].to!ulong]).to!string, rgx.uri_identify_components))
~ "├"
)(_txt, rgx.inline_link_number_only);
}
if ((_txt.match(rgx.mark_internal_site_lnk))
&& (_xml_type == "scroll")) { // conditions reversed to avoid: gdc compiled program run segfault
_txt = _txt.replaceAll(
rgx.inline_seg_link,
"$1");
}
if (_xml_type == "seg" || _xml_type == "epub") {
seg_lvs = (_xml_type == "epub") ? "seg_lv1to4" : "seg_lv4";
foreach (m; _txt.match(rgx.inline_link_hash)) {
if ((m.captures["hash"] in doc_matters.has.tag_associations)
&& (seg_lvs in doc_matters.has.tag_associations[(m.captures["hash"])])
) {
if (
m.captures["hash"]
== doc_matters.has.tag_associations[(m.captures["hash"])][seg_lvs]
) {
_txt = _txt.replaceFirst(
rgx.inline_link_hash,
"┥$1┝┤$3" ~ _suffix ~ "├"
);
} else {
_txt = _txt.replaceFirst(
rgx.inline_link_hash,
"┥$1┝┤"
~ doc_matters.has.tag_associations[(m.captures["hash"])][seg_lvs]
~ _suffix ~ "#" ~ "$3"
~ "├"
);
}
} else {
if (doc_matters.opt.action.vox_gt_1) {
writeln(
"WARNING on internal document links, anchor to link <<"
~ m.captures["hash"]
~ ">> not found in document, "
~ "anchor: " ~ m.captures["hash"]
~ " document: " ~ doc_matters.src.filename
);
}
}
}
}
_txt = _txt
.replaceAll(
rgx.inline_link_fn_suffix,
("$1" ~ _suffix))
.replaceAll(
rgx.inline_link,
("$1"))
.replaceAll(
rgx.mark_internal_site_lnk,
"");
}
debug(markup_links) {
if (_txt.match(rgx.inline_link)) {
writeln(__LINE__,
" (missed) markup link identified (",
obj.has.inline_links,
"): ", obj.metainfo.is_a, ": ",
obj.text
);
}
}
debug(markup) {
if (_txt.match(rgx.inline_link)) {
writeln(__LINE__,
" (missed) markup link identified (",
obj.has.inline_links,
"): ", obj.metainfo.is_a, ": ",
obj.text
);
}
}
return _txt;
}
string inline_notes_scroll(O,M)(
string _txt,
const O obj,
M doc_matters,
) {
if (obj.has.inline_notes_reg) {
_txt = font_face(_txt);
_txt = _txt.replaceAll(
rgx.inline_notes_al_regular_number_note,
("$1")
);
}
if (obj.has.inline_notes_star) {
_txt = font_face(_txt);
_txt = _txt.replaceAll(
rgx.inline_notes_al_special_char_note,
("$1")
);
}
debug(markup_endnotes) {
if (_txt.match(rgx.inline_notes_al_regular_number_note)) {
writeln(__LINE__, " (missed) markup endnote: ", obj.metainfo.is_a, ": ", obj.text);
}
}
debug(markup) {
if (_txt.match(rgx.inline_notes_al_regular_number_note)) {
writeln(__LINE__, " (missed) markup endnote: ", obj.metainfo.is_a, ": ", obj.text);
}
}
return _txt;
}
Tuple!(string, string[]) inline_notes_seg(O,M)(
string _txt,
const O obj,
M doc_matters,
) {
string[] _endnotes;
if (obj.has.inline_notes_star) {
_txt = font_face(_txt);
/+ need markup for text, and separated footnote +/
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",
"
\n";
foreach (subtoc; obj.tags.lev4_subtoc) {
if (auto m = subtoc.match(rgx.inline_link_subtoc)) {
auto indent = (m.captures[1].to!int - 3).to!string; // css assumptions based on use of em for left margin & indent
auto text = m.captures[2].to!string;
text = font_face(text);
auto link = m.captures[3].to!string;
lev4_subtoc ~= subtoc.replaceFirst(rgx.inline_link_subtoc,
format(q"┃
┃",
obj.metainfo.is_a,
_txt
);
}
return o;
}
string verse_scroll(O,M)(
string _txt,
const O obj,
M doc_matters,
string _suffix = ".html",
string _xml_type = "html",
) {
_txt = inline_markup_scroll(_txt, obj, doc_matters, _suffix);
string o = verse(_txt, obj, doc_matters);
return o;
}
Tuple!(string, string[]) verse_seg(O,M)(
string _txt,
const O obj,
M doc_matters,
string _suffix = ".html",
string _xml_type = "html",
) {
Tuple!(string, string[]) t = inline_markup_seg(_txt, obj, doc_matters, _suffix, _xml_type);
_txt = t[0].to!string;
string[] _endnotes = t[1];
string o = verse(_txt, obj, doc_matters);
Tuple!(string, string[]) u = tuple(
o,
_endnotes,
);
return u;
}
/+ ↓ column widths as a
, not a width attribute on every cell +/
string _table_colgroup(O)(const O obj) {
if (obj.table.column_widths.length == 0) { return ""; }
string _cols;
foreach(w; obj.table.column_widths) {
_cols ~= (w > 0)
? "