dispatch: pod materialised if source required

actions requiring source first materialise the pod

One route per argument, decided by what was asked for. --source, --pod,
--pod2, --show-abstraction and --ocda-db need original markup, so an
.ocda.db given with any of them is written back out as a pod and parsed.
Asked only to render, it is read as an abstraction as before.

To ensure consistency, where a pod is materialized by an argument, that
pod is used for the whole run, including for html and epub that could
have been built from the loaded abstraction instead.

--show-abstraction and --ocda-db join the markup side deliberately.
They could be satisfied by re-serialising the abstraction already
loaded, and were. But an artefact is a statement about the source:
written from a loaded abstraction it says only that the loader is
self consistent, where written from the markup it says what this
spine (whatever current version) makes of that document today.

The chain is checkable against itself: --ocda-db from a database now
goes database, pod, parse, database, and returns the same 9,908,224
bytes it started from. --show-abstraction likewise re-emits the .ssp
files byte for byte.

A .ssp carries no markup by construction and a database written
before the format carried it has none, so both are refused for those
actions, once and by name, and the rest of the run goes on.

(assisted by Claude-Code)

1 files changed, 22 insertions, 24 deletions

diff --git a/src/sisudoc/spine.d b/src/sisudoc/spine.d
index a93e48e..fa6ef03 100644
--- a/src/sisudoc/spine.d
+++ b/src/sisudoc/spine.d
@@ -706,21 +706,19 @@ string program_name = "spine";
     @trusted bool source_or_pod() {
       return (opts["pod"] || opts["pod2"] || opts["source"]) ? true : false;
     }
-    /+ ↓ the actions that need the markup and not only the abstraction.
+    /+ ↓ the actions that need the markup source and not only the abstraction.
          .
-         --source, --pod and --pod2 write the markup out. --show-abstraction
-         and --ocda-db write an artefact, and an artefact is a statement
-         about the source: derived from a loaded abstraction it would say
-         only that the loader is consistent with itself, where derived from
-         the markup it says what this spine makes of that document today,
-         which is the question worth answering and the one --ocda-verify
-         asks.
+         --source, --pod and --pod2 write the markup out. --show-abstraction and
+         --ocda-db write an artefact, and an artefact is a statement about the
+         source: if this were derived from a loaded abstraction it would say only
+         that the loader is consistent with itself, where derived from the markup
+         it says what this spine makes of that document today, which is the
+         question posited by --ocda-verify.
          .
-         Given a database that carries source, these route the argument
-         through the pod: it is written back out and parsed. Given one that
-         does not, or a .ssp, which carries no markup at all, they are
-         refused, and any rendering asked for in the same run still happens
-         from the abstraction.
+         Given a database that carries source, these route the argument through
+         the pod: it is written back out and parsed. Given one that does not, or a
+         .ssp, which carries no markup at all, they are refused, and any rendering
+         asked for in the same run still happens from the abstraction.
     +/
     @trusted bool needs_markup_source() {
       return (source_or_pod || show_abstraction || ocda_db) ? true : false;
@@ -1117,11 +1115,11 @@ string program_name = "spine";
        with the pod.
        .
        The actions that need the source markup are --source, --pod, --pod2,
-       --show-abstraction and --ocda-db, and a 2.0 database has it. The pod
-       is written to a directory of this run's making and takes the place of
-       the argument, so everything after this point is handling a pod, and
-       the document is built by the same code over the same bytes as the
-       original. That is what makes "identical output" a consequence.
+       --show-abstraction and --ocda-db, which are included in a 2.0 database. The
+       pod is written to a directory of this run's making and takes the place of
+       the argument, so everything after this point is handling a pod, and the
+       document is built by the same code over the same bytes as the original.
+       That is what makes "identical output" a consequence.
        .
        One route per argument, never a mix. An argument that materialises is
        a pod for the whole run: every output asked for comes from the markup,
@@ -1160,11 +1158,11 @@ string program_name = "spine";
           writeln("pod from database: ", arg.baseName, " -> ", _mat.pod_dir);
         }
       } else {
-        /+ ↓ the argument stays, and is read as an abstraction below: what
-             was asked for that needs the markup cannot be done, and what
-             does not still can. Which actions those are is said once, by
-             the artefact loop this argument now falls to, rather than
-             twice here as well.
+        /+ ↓ the argument stays, and is read as an abstraction below: what was
+             asked for that needs the markup cannot be done, and what does not
+             (need markup) still can. Which actions those are is specified once,
+             by the artefact loop this argument now falls to, rather than twice
+             here as well.
         +/
         _args_after ~= arg;
         stderr.writeln("WARNING: ", arg.baseName, " ", _mat.note);
@@ -1866,7 +1864,7 @@ string program_name = "spine";
     if (!(_opt_action.skip_output)) {
       outputHubInitialize!()(_opt_action, program_info);
     }
-    /+ ↓ what is left here needs the markup and could not get it.
+    /+ ↓ what is left here needs the source markup and could not get it.
          A .ocda.db that carries source never reaches this loop: it was
          written back out as a pod above and is being parsed. So an artefact
          here is a .ssp, which carries no markup by construction, or a