docs: record how a recipe tier is narrowed and when it is withheld
`Invocation` gains the two rules a command author has to know about
the recipe tier. A step can be told not to inherit a parameter, in
either of two spellings read and removed by `recipe._unset_names`
before `select_parameters` runs -- and neither can be an absent value,
because `''` and `None` are values commands accept. And a run wide
parameter naming a file the recipe itself writes is withheld without
being asked: `recipe.PRODUCERS` maps a command to the parameter naming
what it writes and the run wide parameter that names the same file,
and `_withheld_by_production` decides from whether the file exists and
which step writes that path, in the four row table now on the page.
The note on why that decision is made once, before the first step,
rather than at each step: a batch file left by an earlier run is
otherwise indistinguishable from the one this run has just written,
and a recipe has to do the same thing twice.
The sample provenance report in `Invocation` and in the invocation
whitepaper is updated to the column order the report now uses --
parameter, source, value.
docs: describe how a command gets its sessions and its parameters
The developer wiki covered the command registry, the reusable classes
and logging, and said nothing about the step between a command line and
a running command: which sessions a command acts on, and where each of
its parameter values comes from. That is now one whitepaper and one
working guide, in the shape the logging pages already set.
`Whitepaper-Invocation` is the full account, in thirteen sections: the
two entry points and the dispatcher, the three steering parameters and
where they are normalised, the one parser and why it imports nothing
but the standard library, the five parameter tiers and the three
dictionaries the merge returns, the order inside `runCommand` and why
it is that order, how each command class is handed its parameters, the
provenance report, the routes a command can arrive by, and the
container splice. Every snippet is quoted from the tree and annotated.
`Invocation` is the working guide condensed from it -- the ideas, the
calls, the rules, the pitfalls -- so that a command author gets the key
points without reading the whitepaper.
Three existing pages carried statements that are no longer true or were
never complete:
- `Developer-utilities` located `SessionList` in `general/core.py`; it
is in `general/batch_io.py`. The page also described the class without
saying how to obtain one, so it now shows `resolve_sessions()`.
- `Command-registry` described the docstring as documentation. It is
also the answer to "what may this command be given", since the
parameter tiers are narrowed to what a command declares -- and for a
matlab or bash command the documented parameters are the whole
interface, there being no python signature to read. That is the fact
a command author most needs from that page.
- `Home` lists both new pages.
github issue: 69