diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/sisudoc/spine.d | 70 |
1 files changed, 63 insertions, 7 deletions
diff --git a/src/sisudoc/spine.d b/src/sisudoc/spine.d index 95e48c7..18beda2 100644 --- a/src/sisudoc/spine.d +++ b/src/sisudoc/spine.d @@ -383,7 +383,68 @@ string program_name = "spine"; _run_banner = false; } if (helpInfo.helpWanted) { - defaultGetoptPrinter("Some information about the program.", helpInfo.options); + defaultGetoptPrinter( + "spine: structure, parse, publish and search document collections.\n" + ~ "\n" + ~ " spine [options] <source> ...\n" + ~ "\n" + ~ "A <source> is markup, or an artefact made from it:\n" + ~ "\n" + ~ " <doc>.sst, .ssm markup, one document\n" + ~ " <pod>/ a pod: markup, images, conf, manifest\n" + ~ " <pod>.sisupod the same, zipped (.zip also read)\n" + ~ " <doc>.ssp the abstraction, as text\n" + ~ " <doc>.ocda.db the abstraction, as sqlite\n" + ~ "\n" + ~ "A url is fetched only with --allow-downloads.\n", + helpInfo.options + ); + /+ ↓ the contract, after the options: what an artefact carries and what + can be done with it. It belongs in --help because it is the answer + to "I have this file, what can spine do with it", which is the + question somebody holding one actually has. + +/ + writeln(q"┃ +The artefacts, and what they carry: + + <doc>.ssp the abstraction as text, one file per language. Describes + its images by name, size and digest; does not carry them, + and does not carry the markup. + <doc>.ocda.db the abstraction as sqlite, one file per document holding + EVERY language of it, and carrying the markup it was + built from, the images, conf/document_make, pod.manifest + and the translation catalogues. A document source in its + own right: a pod can be written back out of it. + +Both record the digest of the markup they were built from, so what they came +from is checkable. A .ocda.db also records the digest of the .ssp, so the +chain .sst -> .ssp -> .ocda.db is checkable end to end. + +Actions that need the markup rather than only the abstraction: + + --source --pod --pod2 --show-abstraction --ocda-db + +Given a .ocda.db that carries markup, these write the pod back out and build +from it, so the document is made by the same code over the same bytes as the +original. Given a .ssp, which carries no markup, they are refused and the +rest of the run goes on. + +Verifying: + + --ocda-verify=<file> re-parse the markup the file carries and ask whether + it still makes the abstraction the file holds. + Writes nothing; the exit status is the answer. + --no-verify build anyway when it does not, with a warning. The + check is otherwise automatic and runs before + anything is written. + + --strict document checks that warn become failures, ocn + alignment between languages among them. +┃"); + /+ ↓ --help is a question answered on stdout, not a run: the + scope(success) banner would be the last line of the answer + +/ + _run_banner = false; } /+ ↓ read a .ssp back into the abstraction and emit it again, on stdout. the two should be byte identical: that is the check that the reader is @@ -1986,12 +2047,7 @@ string program_name = "spine"; mixin spineAbstractionRead; spineAbstractionDb!()(doc, sspRoundTripDocument(doc)); } - /+ ↓ the ocn alignment profile of this language, kept for the - check that runs once every language of the document has been - abstracted. Taken whatever the outputs are: the languages of - a document share their object numbering whether or not - anything is being written. - +/ + /+ ↓ the ocn alignment profile of this language, as (for parallel processing) above +/ { auto _ocn_p = _ocna.ocnProfile(doc); if (doc.matters.opt.action.ocda_db) { |