docs: document log.rule() and how a report's prose is written
`ReportLog.rule()` draws the full width rule that separates one part of a
session report from the next. It takes `before` and `after` for the
blank lines around it, and `char` for what it is drawn with, so a report
can divide at more than one weight without the rules going to different
lengths.
*Logging* gains a row in the vocabulary table, a short block on
horizontal division beside the one on nesting, and two new pitfalls: a
paragraph of prose folded into one string with its own `\n `, and a
parameter block written as one format string. The existing pitfall on
hand-typed indentation now names rules too, since that is the same
mistake and it has a method now.
*Whitepaper-Logging* gains two sections. "Furniture is drawn, not typed"
covers `blank`, `rule` and `framed` together, and states the property
`rule` exists to protect -- the width does not change with the
character. "Prose in a report" covers the preamble at the head of a
session report: a module level triple-quoted constant rather than a
string carrying its own wrapping, `textwrap.fill` where it has
substitutions in it, and the parameters a command quotes back kept as a
list the report loops over rather than a format string that drifts from
`options`.
The section on `raw()` is now two shapes rather than three. Framing was
one of them, and it is no longer something `raw()` is reached for.
*Developer utilities* gains the three calls in its example block.
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
docs: updated for the new logging infrastructure
Adds a logging whitepaper -- the first entry of a new whitepapers
section on the home page -- describing how logging is implemented: the
runlog and the comlog, the report object and its vocabulary, the log
files and their lifecycle, the settings, the life of a log for a
processing command, a utility command and a recipe, a worked example of
every logging method in both kinds of command, where the logs land, and
every setting with what it does.
Adds a shorter Logging page with the same material in working form: the
key ideas, the shape of each kind of command, the vocabulary table, the
rules, the pitfalls, and how to get the most out of the available
instruments.
Developer utilities and classes gains the logging classes and examples
of the report methods beside the lines they render. Command registry and
command types states that a processing function returns a log object,
in the shared signature, the type table and each of the three processing
sections.
Python only; the bash entry point's logging is not covered.
github issue: 77
update: add information of qx_registry, command types and SessionList class