/+ - Name: SisuDoc Spine - Description: part of SiSU spine (Doc Reform): for document structuring, processing, publishing and search - Author: Ralph Amissah [ralph.amissah@gmail.com] - Copyright: (C) 2015 (continuously updated, current 2026) Ralph Amissah, All Rights Reserved. - License: AGPL 3 or later, for everything in this repository unless a file or a directory specifies otherwise. This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License (AGPLv3) as published by the Free Software Foundation (FSF), 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 Affero General Public License for more details. You should have received a copy of the GNU Affero 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: [https://www.gnu.org/licenses/agpl-3.0.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.meta.doc_matters; @safe: /+ ↓ doc_matters: the one description of what an output writer is given spineAbstraction() builds this from the markup it has just parsed. A document loaded from a .ssp or a .ocda.db has to arrive at the same value from what the artefact carries, so the construction lives here rather than inside the parser, and both paths fill the same arguments: program_info the run opt_action the run manifest where the document is, and what it is called conf_make_meta the document's header, plus the site config doc_has the counts, lists and indexes (ST_DocHas) doc_digest the source digests insert_file_list the files the markup inserted, for --pod2 Nothing downstream learns which path filled them, which is the point: an output writer that has to know where the document came from is a writer that has had something leak into it from upstream. +/ template spineDocMatters() { import std.conv : to; import std.datetime; import std.stdio; import sisudoc.ocda.meta.conf_make_meta_structs; import sisudoc.ocda.io_in.paths_source; auto docMattersMake(P,O,M,H,D)( P program_info, O _opt_action, M _manifest, ConfComposite _make_and_meta_struct, H _doc_has_struct, D doc_digests, string[] _insert_file_list, ) { struct ST_DocumentMatters { auto generator_program() { struct Prog_ { string project_name() { return "spine"; } string name() { return program_info.name; } string ver() { return program_info.ver; } @trusted string name_and_version() { return program_info.name_and_version; } @trusted string name_version_and_compiler() { return program_info.name_version_and_compiler; } string url_home() { return "https://sisudoc.org"; } string url_git() { return "https://git.sisudoc.org/projects/"; } auto compiler() { return program_info.compiler; } auto time_output_generated() { return program_info.time_output_generated; } } return Prog_(); } /+ ↓ when the document is from, as a UTC instant, for the output formats that must carry a timestamp: epub3 requires exactly one dcterms:modified on the package, and an odt carries meta:creation-date and dc:date. . Taken from the document rather than from the clock, so that those artefacts are a function of their source. Stamped from the clock, two runs over unchanged markup produced different bytes, and no comparison of that output could tell a real change from the seconds between two builds. . Read in order: SOURCE_DATE_EPOCH where the environment sets it, which is the reproducible-builds convention and lets a build pin every artefact of one run; then the document's own date.modified; then date.published. The clock is the last resort, for a document that says nothing about when it is from. . A document date is loose markup: "1991", "2006-03" and "2021-12-00" all occur in the sample set, and a month or day of 00 is not a date. A missing or zero part becomes 01, and a day out of range for its month falls back to the first, so what is written is always a valid CCYY-MM-DDThh:mm:ssZ. +/ string modified_utc() { import std.datetime : Date, SysTime, unixTimeToStdTime; import std.format : format; import std.process : environment; import std.regex : ctRegex, matchFirst; /+ ↓ a build may pin every artefact of the run +/ string _sde = environment.get("SOURCE_DATE_EPOCH", ""); if (_sde.length > 0) { try { auto _t = SysTime(unixTimeToStdTime(_sde.to!long), UTC()); return format("%04d-%02d-%02dT%02d:%02d:%02dZ", _t.year, _t.month.to!int, _t.day, _t.hour, _t.minute, _t.second); } catch (Exception) { } } /+ ↓ what the document itself says +/ auto _rgx_date = ctRegex!(`^\s*(?P\d{4})(?:[-/](?P\d{1,2}))?(?:[-/](?P\d{1,2}))?`); foreach (_said; [ conf_make_meta.meta.date_modified, conf_make_meta.meta.date_published, ]) { if (_said.length == 0) { continue; } if (auto _m = _said.matchFirst(_rgx_date)) { int _y = _m["y"].to!int; int _mo = (_m["m"].length > 0) ? _m["m"].to!int : 1; int _d = (_m["d"].length > 0) ? _m["d"].to!int : 1; if (_mo < 1 || _mo > 12) { _mo = 1; } if (_d < 1) { _d = 1; } try { cast(void) Date(_y, _mo, _d); } catch (Exception) { _d = 1; } return format("%04d-%02d-%02dT00:00:00Z", _y, _mo, _d); } } /+ ↓ the document says nothing: the run's own time +/ auto _now = Clock.currTime(UTC()); return format("%04d-%02d-%02dT%02d:%02d:%02dZ", _now.year, _now.month.to!int, _now.day, _now.hour, _now.minute, _now.second); } // auto generated_time() { // UNUSED // auto _st = Clock.currTime(UTC()); // auto _time = _st.year.to!string // ~ "-" ~ _st.month.to!int.to!string // prefer as month number // ~ "-" ~ _st.day.to!string // ~ " [" ~ _st.isoWeek.to!string ~ "/" ~ _st.dayOfWeek.to!int.to!string ~ "]" // ~ " " ~ _st.hour.to!string // ~ ":" ~ _st.minute.to!string // ~ ":" ~ _st.second.to!string; // return _time; // } ConfComposite conf_make_meta() { return _make_and_meta_struct; } auto doc_digest() { return doc_digests; } auto has() { return _doc_has_struct; } auto env() { struct Env_ { auto pwd() { return _manifest.env.pwd; } auto home() { return _manifest.env.home; } } return Env_(); } auto opt() { struct Opt_ { auto action() { /+ getopt options, commandline instructions, raw - processing instructions --epub --html etc. - command line config instructions --output +/ return _opt_action; } } return Opt_(); } auto src() { return _manifest.src; } auto src_path_info() { return spinePathsSRC!()(_manifest.env.pwd, _manifest.src.file_with_absolute_path); // would like (to have and use) relative path } auto pod() { return _manifest.pod; } auto sqlite() { struct SQLite_ { string filename() { string _fn = ""; string _pth = ""; if (_opt_action.sqliteDB_filename.length > 0) { _fn = _opt_action.sqliteDB_filename; } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_filename.length > 0) { _fn = _make_and_meta_struct.conf.w_srv_db_sqlite_filename; } return _fn; } string path() { string _pth = ""; if (_opt_action.sqliteDB_path.length > 0) { _pth = _opt_action.sqliteDB_path; } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_path.length > 0) { _pth = _make_and_meta_struct.conf.w_srv_db_sqlite_path; } return _pth; } string cgi_filename() { string _fn = ""; if (_opt_action.cgi_sqlite_search_filename.length > 0) { _fn = _opt_action.cgi_sqlite_search_filename; } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script.length > 0) { _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script; } return _fn; } string cgi_filename_d() { string _fn = ""; if (_opt_action.cgi_sqlite_search_filename_d.length > 0) { _fn = _opt_action.cgi_sqlite_search_filename_d; } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d.length > 0) { _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d; } return _fn; } } return SQLite_(); } auto output_path() { return _make_and_meta_struct.conf.output_path; } auto srcs() { struct SRC_ { auto file_insert_list() { return _insert_file_list; } auto image_list() { return _doc_has_struct.imagelist; } } return SRC_(); } } return ST_DocumentMatters(); } }