/+
- 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 po4a_cfg;
- the po4a configuration for a document, generated from its manifest and
the files its markup names
- written for tools/po4a/po4a.cfg, so its paths are relative to there
+/
module sisudoc.outputs.io_out.po4a_cfg;
@system:
/+ ↓ po4a's configuration, derived rather than kept
The sample this replaces kept a Makefile that built po4a.cfg by globbing
a language directory and listing what it found. Spine already knows both
halves without looking: the manifest says which languages a document
has, and the markup says which files it is made of, through the << lines
the parser follows. Deriving the configuration from those two means it
cannot disagree with the document, which a hand-kept file eventually
does: a language added to the manifest and forgotten in the Makefile
produces a translation nobody updates.
.
It is derived, so it is not kept in git. The sample repository's
whitelist admits pot/ and po/ and not this.
.
neverwrap is deliberately NOT set, and the reason is worth keeping.
.
Without it po4a rewraps its output at about 75 columns, so a document
whose markup keeps one paragraph on one long line comes back reflowed.
That is untidy: it changes no object, since sisu delimits on blank
lines, but it churns every translated file in a diff and leaves the
source language and its translations formatted unlike each other. The
obvious thing is to turn wrapping off.
.
Measured on live-manual, same catalogues and same English, the option
the only difference:
.
fuzzy before with neverwrap without
ca 1 889 5
de 8 103 10
it 149 804 152
.
of 1126 strings. po4a will not use a fuzzy translation, so each one
renders as the source language: Catalan's coverage would fall from about
46% to about 12%, and Spanish, French and Japanese with it. Setting the
option re-extracts the strings in a form the existing catalogues do not
match, and four fifths of nine languages' work stops being used.
.
Tidy formatting is not worth that. The wrapping stays.
+/
template spinePo4aConfig() {
string po4aConfig(M)(M doc_matters) {
import std.algorithm : sort;
import std.array : array, join;
import std.conv : to;
import std.file : exists;
import std.path : baseName;
string _src_lang = doc_matters.src.language;
/+ ↓ the languages po4a is to produce, which is every language the
manifest lists except the one being translated from
+/
string[] _targets;
foreach (_lang; doc_matters.pod.manifest_list_of_languages) {
if (_lang != _src_lang) {
_targets ~= _lang;
}
}
/+ ↓ the files the document is made of: its master, and every insert the
markup names. In manifest order rather than directory order, so the
configuration is the same however a filesystem chooses to list a
directory.
+/
string[] _files;
_files ~= doc_matters.src.filename;
string[] _inserts;
foreach (_insert; doc_matters.srcs.file_insert_list) {
_inserts ~= _insert.baseName;
}
_inserts = _inserts.sort.array;
_files ~= _inserts;
/+ ↓ paths are relative to tools/po4a/, where this file belongs +/
enum string _to_text = "../../media/text";
string _o;
_o ~= "# po4a configuration for " ~ doc_matters.src.filename_base ~ "\n";
_o ~= "# generated by spine from pod.manifest and the markup; not kept in git\n";
_o ~= "# run from the directory this file is in\n";
_o ~= "\n";
/+ ↓ --keep 0 is not optional here, it is the difference between
regenerating a document and destroying it.
.
po4a will not write a translated file that falls below a
completeness threshold, and that threshold defaults to 80%. A
partially translated document is the normal state of one being
worked on, and sisu's own behaviour covers it: an untranslated
string falls back to the source text, so a file at 3% is mostly the
source language and entirely readable. (Measured on live-manual at
the default: 181 of its 189 translated files would be discarded, and
nine languages would collapse to eight surviving files. It would not
look like a failure either, because what remains reads as the
document reverting to its source language.)
.
The Makefile this replaces passed --keep 0 for exactly this reason.
+/
_o ~= "[options] --keep 0 --package-name " ~ doc_matters.src.filename_base ~ "\n";
_o ~= "\n";
_o ~= "[po4a_langs] " ~ _targets.join(" ") ~ "\n";
_o ~= "[po4a_paths] pot/$master.pot $lang:po/$lang/$master.po\n";
_o ~= "\n";
foreach (_f; _files) {
_o ~= "[type: text] " ~ _to_text ~ "/" ~ _src_lang ~ "/" ~ _f
~ " $lang:" ~ _to_text ~ "/$lang/" ~ _f ~ "\n";
}
/+ ↓ index.html.in is not markup and no << line names it, so it is found
by asking whether the source language has one. live-manual does, the
Makefile it replaces carried it as xhtml, and the sample
repository's whitelist admits index.html.in.pot and .po by name.
Left out, regenerating would quietly drop those catalogue entries.
+/
string _index_in = doc_matters.pod.manifest_path
~ "/media/text/" ~ _src_lang ~ "/index.html.in";
if (_index_in.exists) {
_o ~= "[type: xhtml] " ~ _to_text ~ "/" ~ _src_lang ~ "/index.html.in"
~ " $lang:" ~ _to_text ~ "/$lang/index.html.in\n";
}
return _o;
}
}