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: 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