diff options
Diffstat (limited to 'org/spine.org')
| -rw-r--r-- | org/spine.org | 91 |
1 files changed, 81 insertions, 10 deletions
diff --git a/org/spine.org b/org/spine.org index f89885b..49ef331 100644 --- a/org/spine.org +++ b/org/spine.org @@ -61,6 +61,8 @@ string program_name = "spine"; <<spine_args_init_opts>> <<spine_args_init_settings>> <<spine_args_get_options_aa>> +<<spine_args_get_help>> + <<read_spine_ssp_back_into_abstraction>> <<read_spine_ocda_db_back_into_abstraction>> <<spine_args_get_options_aa2str>> <<spine_args_program_info>> @@ -766,9 +768,83 @@ auto helpInfo = getopt(args, if (opts["po4a-cfg"]) { _run_banner = false; } -if (helpInfo.helpWanted) { - defaultGetoptPrinter("Some information about the program.", helpInfo.options); -} +#+END_SRC + +***** help info + +#+NAME: spine_args_get_help +#+BEGIN_SRC d + if (helpInfo.helpWanted) { + 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; + } +#+END_SRC + +**** read ssp & ocda.db back CHECK +***** read ssp back CHECK + +#+NAME: read_spine_ssp_back_into_abstraction +#+BEGIN_SRC d /+ ↓ 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 faithful, and it is made against the writer's own record definition, @@ -815,7 +891,7 @@ if (settings["ssp-round-trip"].length > 0) { } #+END_SRC -**** read ocda.db back CHECK +***** read ocda.db back CHECK #+NAME: read_spine_ocda_db_back_into_abstraction #+BEGIN_SRC d @@ -2314,12 +2390,7 @@ if (doc.matters.opt.action.ocda_db) { #+NAME: spine_ocn_alignment_non_synchronized #+BEGIN_SRC d -/+ ↓ 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) { |