diff options
Diffstat (limited to 'src/sisudoc/ocda/abstraction/doc_from_artefact.d')
| -rw-r--r-- | src/sisudoc/ocda/abstraction/doc_from_artefact.d | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/src/sisudoc/ocda/abstraction/doc_from_artefact.d b/src/sisudoc/ocda/abstraction/doc_from_artefact.d new file mode 100644 index 0000000..e45cbf0 --- /dev/null +++ b/src/sisudoc/ocda/abstraction/doc_from_artefact.d @@ -0,0 +1,279 @@ +/+ +- 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.ocda.abstraction.doc_from_artefact; +@safe: +/+ ↓ a document, from an artefact rather than from markup + + spineAbstraction() parses markup and hands the output writers a doc: + an abstraction and a doc_matters. This does the same from a .ssp or a + .ocda.db, filling the same docMattersMake() arguments, so that what + comes out is the value the writers already take and they never learn + which of the two made it. + + Three of the seven arguments come from the run and are the same either + way: program_info, opt_action, and the conf half of conf_make_meta, + which is site and run scoped (urls, papersize, the search database) and + has no business in a document's own artefact. The other four come from + the artefact: + + conf_make_meta meta and make from the @meta and @make blocks, over + the site config the run assembled + doc_has docHasFromAbstraction, over the objects + doc_digest the markup digest from @source + manifest synthesised from the artefact's path and the + document's own name and language + + What is not here, deliberately: insert_file_list, which is read only by + source_pod.d for --source and --pod2. No artefact carries the markup, + so a pod cannot be rebuilt from one, and the empty list is the truthful + answer rather than a gap. ++/ +template spineDocFromArtefact() { + import std.algorithm : endsWith; + import std.array; + import std.conv : to; + import std.path; + import std.regex; + import std.stdio; + import std.string; + import sisudoc.ocda.meta.conf_make_meta_structs; + import sisudoc.ocda.meta.doc_matters; + import sisudoc.ocda.io_in.paths_source; + import sisudoc.ocda.abstraction.doc_has; + import sisudoc.ocda.abstraction.load; + import sisudoc.ocda.meta.topic_register; + mixin spineDocMatters; + mixin spineDocHasFromAbstraction; + mixin spineAbstractionLoad; + mixin spineTopicRegister; + /+ ↓ a .ssp header key from a field name: the first underscore becomes the + dot that separates the group, so title_main is title.main and + rights_copyright_text is rights.copyright_text. The writer's keys are + formed the same way, which is what lets this be read off the struct + rather than kept as a second list to fall out of step with it. + +/ + private string _sspKeyOf(string _member) { + foreach (i, c; _member) { + if (c == '_') { return _member[0 .. i] ~ "." ~ _member[i + 1 .. $]; } + } + return _member; + } + /+ ↓ the document's own header, over the site config the run assembled. + + every string field of MetaComposite is looked for under its own key, + so a field added there and emitted by the writer arrives here without + anything being added. The arr fields are split from the string they + come from, as agreed: that is parsing a value, not deriving a + structure. + +/ + ConfComposite confMakeMetaFromHeader(S)(S _ssp, ConfComposite _site_conf) { + ConfComposite _out = _site_conf; // conf: site and run scoped, kept + static foreach (_m; __traits(allMembers, MetaComposite)) { + static if (is(typeof(__traits(getMember, _out.meta, _m)) == string)) {{ + enum string _key = _sspKeyOf(_m); + if (auto _v = _key in _ssp.meta) { __traits(getMember, _out.meta, _m) = *_v; } + }} + } + /+ ↓ title_sub is a copy of title_subtitle, made where the header is + read, and is what epub3 puts in dc:title id="subtitle". It is not + emitted, being the same string twice; it is remade here the way the + yaml reader makes it +/ + _out.meta.title_sub = _out.meta.title_subtitle; + /+ ↓ creator.author is the author list joined with ", ", so splitting on + it gives the list back +/ + if (_out.meta.creator_author.length > 0) { + foreach (_a; _out.meta.creator_author.split(", ")) { + if (_a.strip.length > 0) { _out.meta.creator_author_arr ~= _a.strip; } + } + } + /+ ↓ the topic register arrays, by the one rule the yaml reader uses: + the split is not a plain one and deriving it twice would be two + answers to the same question +/ + { + auto _tr = topicRegisterArrays(_out.meta.classify_topic_register); + _out.meta.classify_topic_register_arr = _tr.arr; + _out.meta.classify_topic_register_expanded_arr = _tr.expanded; + } + /+ ↓ make: the keys are the field names, with no group to separate +/ + if (auto _v = "doc_type" in _ssp.make) { + _out.make.doc_type = *_v; _out.make_str.doc_type = *_v; + } + if (auto _v = "auto_num_top_at_level" in _ssp.make) { + _out.make.auto_num_top_at_level = *_v; + } + if (auto _v = "auto_num_top_lv" in _ssp.make) { + try { _out.make.auto_num_top_lv = (*_v).to!int; } catch (Exception ex) {} + } + if (auto _v = "auto_num_depth" in _ssp.make) { + try { _out.make.auto_num_depth = (*_v).to!int; } catch (Exception ex) {} + } + if (auto _v = "breaks" in _ssp.make) { + _out.make.breaks = *_v; _out.make_str.breaks = *_v; + } + if (auto _v = "home_button_text" in _ssp.make) { + _out.make.home_button_text = *_v; _out.make_str.home_button_text = *_v; + } + /+ ↓ footer is a list, joined with the separator the format escapes +/ + if (auto _v = "footer" in _ssp.make) { + _out.make.footer = sspUnescapeSplit(*_v); + _out.make_str.footer = _out.make.footer; + } + return _out; + } + /+ ↓ where a document loaded from an artefact says it is. + + an artefact names its document (% Source:) and its language (@source + language) but not where the pod holding its images sits, so that is + taken from where the artefact itself was found: + + pod/<doc>/media/abstraction/<uid>.ssp -> pod/<doc>/ + pod/<uid>.ocda.db -> pod/<doc>/ + + which is where --pod2 puts them both. The images beside a .ssp are + then found where html.d already looks; a .ocda.db carries its own and + does not need the directory to exist. + +/ + struct ST_ArtefactPaths { + string pod_dir; + string src_file_with_path; + } + ST_ArtefactPaths artefactPaths(S)(string _artefact, S _ssp) { + ST_ArtefactPaths _out; + string _lang = ("language" in _ssp.source_info) ? _ssp.source_info["language"] : "en"; + string _dir = _artefact.dirName; + if (_artefact.endsWith(".ssp")) { + /+ ↓ <pod>/media/abstraction/<uid>.ssp: two directories up is the pod +/ + _out.pod_dir = (_dir.baseName == "abstraction") + ? _dir.dirName.dirName : _dir; + } else { + /+ ↓ <dir>/<uid>.ocda.db, the pod tree beside it named for the document +/ + string _uid = _artefact.baseName; + foreach (_sfx; [".ocda.db", ".db"]) { + if (_uid.endsWith(_sfx)) { _uid = _uid[0 .. $ - _sfx.length]; break; } + } + if (_uid.endsWith("." ~ _lang)) { _uid = _uid[0 .. $ - _lang.length - 1]; } + _out.pod_dir = (_dir.chainPath(_uid).array).to!string; + } + _out.src_file_with_path = (_out.pod_dir + .chainPath("media").chainPath("text").chainPath(_lang) + .chainPath(_ssp.source).array).to!string; + return _out; + } + /+ ↓ the doc the output writers take, from an artefact. + + the reading is done here rather than by the caller, and that is not + only tidiness: main() is @system, so a template mixed in there infers + @system for everything it declares, and the output writers are @safe + and will not take objects of such a type. Doing it inside this module, + which is @safe:, is what makes the loaded objects the same kind of + thing the parser's are. Called as spineDocFromArtefact!()(...), the + way spineAbstraction!() is, rather than mixed in. + +/ + auto spineDocFromArtefact(P,O,E)( + string _artefact, + P program_info, + O _opt_action, + E _env, + ConfComposite _site_conf, + ) { + auto _loaded = abstractionLoad(_artefact); + auto _ssp = _loaded.doc; + auto _pths = artefactPaths(_artefact, _ssp); + auto _manifest = PathMatters!()(_opt_action, _env, _pths.pod_dir, _pths.src_file_with_path); + auto _cmm = confMakeMetaFromHeader(_ssp, _site_conf); + auto _has = docHasFromAbstraction(_ssp.abstraction, _ssp.doc_has, _opt_action); + /+ ↓ the digests: the markup digest is what @source carries, and it is + the one that says which source this abstraction was made from. The + header and text digests are of parts an artefact does not keep + separately, and are left unset rather than guessed at + +/ + ST_ArtefactDigest _dig; + if (auto _v = "digest" in _ssp.source_info) { + _dig.markup_doc = _hexToDigest(*_v); + } + auto _abstraction = _ssp.abstraction; + auto _matters = docMattersMake( + program_info, _opt_action, _manifest, _cmm, _has, _dig, string[].init, + ); + /+ ↓ the same shape spineAbstraction() returns, built the same way: a + struct of accessors over the locals, with whether the artefact + could be read at all, which the caller has to know +/ + auto theDOC() { + struct ST_DOC { + const auto abstraction() { return _abstraction; } + auto matters() { return _matters; } + bool loaded() { return _loaded.loaded; } + string note() { return _loaded.note; } + string source_name() { return abstractionSourceName(_loaded.source); } + } + return ST_DOC(); + } + return theDOC(); + } + /+ ↓ the digests doc_matters carries. Only markup_doc can be filled from + an artefact, @source having recorded it; the header and text digests + are of parts no artefact keeps separately and are left unset rather + than guessed at. Shaped to match ST_doc_digest, which is declared + inside spineRawMarkupContent and reachable only by parsing a file. + +/ + struct ST_ArtefactDigest { + ubyte[32] markup_doc; + ubyte[32] header; + ubyte[32] text; + } + private ubyte[32] _hexToDigest(string _hex) { + ubyte[32] _out; + if (_hex.length < 64) { return _out; } + foreach (i; 0..32) { + try { _out[i] = _hex[i*2 .. i*2+2].to!ubyte(16); } catch (Exception ex) {} + } + return _out; + } +} |
