help: what spine takes, what an artefact carries

--help now names the five source forms before the options, and after
them states the contract: what a .ssp and a .ocda.db each carry and do
not, that both record the digest of the markup they were built from,
which five actions need that markup and what happens when they cannot
have it, and the three ways to verify.

And the version, 0.24.1 to 0.25.0, for abstraction format 2.0 and what
it made possible: (one database per document holding every language of
it, carrying the markup, images, configuration, manifest and
translation catalogues it was built from, with the implications that
carries)

(assisted by Claude-Code)

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) {