flags: --ocda-db and matching --ocda-db-round-trip

flags names tidied so that each names the artefact it acts on.

--ocda-db and --abstraction-db do the same thing. --ocda-db is the
official flag (--abstraction-db remains but undocumented)

--db-round-trip becomes --ocda-db-round-trip, so that it agrees with
--ssp-round-trip: each names the artefact it reads rather than one
naming a container and the other a format.

--abstraction-source is untouched named after he stage as it takes .sst,
a pod, .ssp or .ocda.db, rather than any one artefact.

(assisted by Claude-Code)

1 files changed, 15 insertions, 6 deletions

diff --git a/src/sisudoc/spine.d b/src/sisudoc/spine.d
index c1a3f63..0494a34 100644
--- a/src/sisudoc/spine.d
+++ b/src/sisudoc/spine.d
@@ -55,6 +55,7 @@ homepage    "https://sisudoc.org"
 +/
 @safe:
 import std.algorithm;
+import std.array;
 import std.datetime;
 import std.getopt;
 import std.file;
@@ -231,7 +232,7 @@ string program_name = "spine";
     "output"                      : "",
     "pod-compression"             : "",
     "ssp-round-trip"              : "",
-    "db-round-trip"               : "",
+    "ocda-db-round-trip"          : "",
     "ocda-verify"                 : "",
     "abstraction-source"          : "",
     "www-http"                    : "",
@@ -256,7 +257,10 @@ string program_name = "spine";
   auto helpInfo = getopt(args,
     std.getopt.config.passThrough,
     "abstraction",                "document abstraction",                                           &opts["abstraction"],
-    "abstraction-db",             "document abstraction (write ocda.db sqlite file)",               &opts["abstraction-db"],
+    /+ ↓ undocumented alias of --ocda-db, which names the artefact it writes
+         kept working but filtered out of help listing
+    +/
+    "abstraction-db",             "",                                                               &opts["abstraction-db"],
     "allow-downloads",            "allow a url argument to be fetched (zip or db)",                 &opts["allow-downloads"],
     "assert",                     "set optional assertions on",                                     &opts["assertions"],
     "cgi-bin-root",               "path to cgi-bin directory",                                      &settings["cgi-bin-root"],
@@ -297,7 +301,7 @@ string program_name = "spine";
     "odt",                        "open document format text",                                      &opts["odt"],
     "output",                     "=/path/to/output/dir specify where to place output",             &settings["output"],
     "ssp-round-trip",             "=/path/to/file.ssp read a .ssp back and re-emit it on stdout",   &settings["ssp-round-trip"],
-    "db-round-trip",              "=/path/to/file.ocda.db read it back and emit .ssp on stdout",    &settings["db-round-trip"],
+    "ocda-db-round-trip",         "=/path/to/file.ocda.db read it back and emit .ssp on stdout",    &settings["ocda-db-round-trip"],
     "ocda-verify",                "=/path/to/file.ocda.db does this spine still make this abstraction from the markup it carries", &settings["ocda-verify"],
     "no-verify",                  "do not check carried markup against the abstraction it was built with", &opts["no-verify"],
     "abstraction-source",         "=/path/to/(.sst|pod|.ssp|.ocda.db) identify it, and load it if it is an abstraction", &settings["abstraction-source"],
@@ -384,6 +388,11 @@ string program_name = "spine";
     _run_banner = false;
   }
   if (helpInfo.helpWanted) {
+    /+ ↓ the undocumented alias is registered so that it still works, and is
+         not listed, so that --ocda-db is the one flag the help offers
+   +/
+    auto _options_documented
+      = helpInfo.options.filter!(o => o.optLong != "--abstraction-db").array;
     defaultGetoptPrinter(
       "spine: structure, parse, publish and search document collections.\n"
       ~ "\n"
@@ -398,7 +407,7 @@ string program_name = "spine";
       ~ "  <doc>.ocda.db      the abstraction, as sqlite\n"
       ~ "\n"
       ~ "A url is fetched only with --allow-downloads.\n",
-      helpInfo.options
+      _options_documented
     );
     /+ ↓ 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
@@ -498,7 +507,7 @@ Verifying:
        .ssp on stdout. compared against the .ssp for the same document, this
        says whether the two artefacts really do carry the same thing
   +/
-  if (settings["db-round-trip"].length > 0) {
+  if (settings["ocda-db-round-trip"].length > 0) {
     import sisudoc.ocda.abstraction.ssp;
     import sisudoc.ocda.abstraction.db_in;
     mixin spineAbstractionDbRead;
@@ -517,7 +526,7 @@ Verifying:
         _rt_lang = _langs[0];
       }
     }
-    auto _doc = dbReadFile(settings["db-round-trip"], _rt_lang);
+    auto _doc = dbReadFile(settings["ocda-db-round-trip"], _rt_lang);
     if (_doc.format.length == 0 && _doc.section_order.length == 0) {
       import core.stdc.stdlib : exit;
       stdout.flush;