/+ - 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 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; } }