/+
- 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/]
+/
/++
the segment names spine keeps for itself
the one list of them, and the check that says when a document's own
heading has claimed one
[sisudoc.ocda.meta.reserved_names]
+/
module sisudoc.ocda.meta.reserved_names;
@safe:
/+ ↓ spine names the sections it generates, these names are reserved.
.
The table of contents, the gathered endnotes, the glossary, the
bibliography, the book index and the blurb are not in the markup: spine
makes them, and gives each a segment name of its own. A document whose
own heading asks for one of those names ("1~endnotes Endnote") is asking
for a name that is already taken, and before this was noticed both wrote
into the same file: the generated section and the author's heading, with
the navigation listing that file twice, the second time behind its own
earlier entry in reading order.
.
The parser therefore seeds the set of heading anchor names it has seen
with these before it reads a document, so that a heading claiming one is
disambiguated by ocn suffix the same way a repeated anchor tag is, and
the generated section keeps the name the table of contents links to.
.
Two things live here rather than in the parser:
.
the list so that the parser's seeding and the check below cannot
come to hold different ideas of what is reserved;
.
the check which runs over a finished abstraction, names the
headings that were renamed, and is what tells an author
that a heading of theirs is not called what they wrote.
A warning: the document is correct and complete, and the
name it ends up with works. --strict makes it a failure,
for the run that is meant to be publishable.
.
The renaming is not something the author has to accept. A heading given
any other anchor name ("1~my-notes Endnote") keeps it, and the warning
goes away.
+/
/+ ↓ mixed in as a named mixin (mixin spineReservedNames _name;) and its
imports are inside its functions rather than at template scope: what a
mixin template declares at its own scope is visible in the scope it is
mixed into, and an import there can hijack a name the host was already
resolving by UFCS.
+/
template spineReservedNames() {
/+ ↓ the names spine makes for itself, in one place.
_the_title is the head section's own; the rest are the generated
sections, and are the section keys of the abstraction.
+/
string[] reservedHeadingAnchorNames() {
return [
"toc", "endnotes", "glossary", "bibliography", "bookindex", "blurb",
"_the_title",
];
}
/+ ↓ the same, as the set the parser seeds itself with +/
bool[string] reservedHeadingAnchorTags() {
bool[string] _reserved;
foreach (_name; reservedHeadingAnchorNames()) { _reserved[_name] = true; }
return _reserved;
}
/+ ↓ one heading that asked for a name spine had already taken +/
struct ST_ReservedNameUse {
string section; // where in the abstraction it sits
string reserved; // the name it asked for
string anchor; // the name it was given instead
string level; // as marked up, :A :B 1 2 ...
int ocn;
}
/+ ↓ was this heading renamed out of the way of a reserved name?
.
Read off the anchor rather than reported by the parser: the parser
renames by appending the object's number, so "endnotes" becomes
"endnotes-135" on the object whose ocn is 135, and that pairing is what
identifies it. Requiring the number to be the object's own is what keeps
a heading an author really did call "endnotes-135" from being reported as
something it is not.
+/
private string _reservedNameClaimedBy(O)(O obj) {
import std.conv : to;
string _anchor = obj.tags.anchor_tag_html;
if (_anchor.length == 0) { return ""; }
string _suffix = "-" ~ obj.metainfo.ocn.to!string;
if (_anchor.length <= _suffix.length) { return ""; }
if (_anchor[($ - _suffix.length) .. $] != _suffix) { return ""; }
string _stem = _anchor[0 .. ($ - _suffix.length)];
foreach (_name; reservedHeadingAnchorNames()) {
if (_stem == _name) { return _name; }
}
return "";
}
/+ ↓ every heading of a document that claimed a reserved name.
document order, the section order the .ssp is written in, so that two
runs over the same document report it the same way round.
+/
ST_ReservedNameUse[] reservedNameHeadings(D)(D doc) {
import std.algorithm : canFind, sort;
import std.conv : to;
ST_ReservedNameUse[] _out;
string[] _sections = ["head", "toc", "body", "endnotes",
"glossary", "bibliography", "bookindex", "blurb", "tail"];
string[] _extra;
foreach (_k; doc.abstraction.byKey) {
if (!_sections.canFind(_k)) { _extra ~= _k; }
}
foreach (_k; _extra.sort) { _sections ~= _k; }
foreach (section; _sections) {
if (section !in doc.abstraction) { continue; }
foreach (obj; doc.abstraction[section]) {
if (obj.metainfo.is_a != "heading") { continue; }
string _claimed = _reservedNameClaimedBy(obj);
if (_claimed.length == 0) { continue; }
/+ ↓ the generated sections carry the reserved names themselves and are
not what this is about: they are headings spine made, and they keep
the plain name. Only an object that was renamed reaches here, and a
generated one never is.
+/
ST_ReservedNameUse _u;
_u.section = section;
_u.reserved = _claimed;
_u.anchor = obj.tags.anchor_tag_html;
_u.level = obj.metainfo.marked_up_level;
_u.ocn = obj.metainfo.ocn.to!int;
_out ~= _u;
}
}
return _out;
}
/+ ↓ the report, as the lines to print.
the document is named once and its headings indented under it, as the ocn
alignment check does, so that a run over a collection reads as a list of
documents.
+/
string[] reservedNameReportLines(
string doc_key,
string lang,
ST_ReservedNameUse[] _uses,
) {
import std.conv : to;
string[] _out;
if (_uses.length == 0) { return _out; }
_out ~= "WARNING reserved segment name: " ~ doc_key
~ ((lang.length > 0) ? " [" ~ lang ~ "]" : "");
foreach (_u; _uses) {
_out ~= " heading " ~ _u.level ~ " at ocn " ~ _u.ocn.to!string
~ " asks for \"" ~ _u.reserved
~ "\", which spine gives its own generated section";
_out ~= " it is named \"" ~ _u.anchor
~ "\" instead; give the heading another name to keep one of your own";
}
return _out;
}
}