Hi all,
I'd like to propose a small series of documentation improvements around how we
explain the request-processing lifecycle and where each module fits into
it. This is doc-only but one piece touches the module page template, so I want
to float it here before doing the invasive part.
Modules participate in the request lifecycle by hooking specific phases
(translate_name, access_checker, fixups, handler, and so on).
1. developer/request.xml is in good shape — it already documents the current
trunk hook sequence. But there's no diagram of the lifecycle to help
visualize how it all flows, and nothing ties the individual hooks together
visually.
2. Individual module pages give no at-a-glance indication of which phase(s) a
module participates in.
What I'm proposing:
Step 1: A lifecycle diagram. An SVG on developer/request.xml showing the hook
sequence grouped into phases.
Step 2: Per-module "phase strip". A small horizontal strip on each module page
showing the lifecycle phases in order, with the module's own phase(s)
highlighted, linking back to developer/request. Mocked up, it reads like:
[Conn][Setup][Mapping][SECURITY][Prep][Handler][Log]
...with the relevant cell(s) highlighted per module.
That could be text, or it could be an image in the same style as the main flow
diagram.
Mechanically that means:
- an optional <lifecycle><phase>...</phase></lifecycle> element in the
modulesynopsis DTD
- rendering it in synopsis.xsl near the existing status/identifier metadata;
- phase labels via the lang/*.xml message catalogs (localizable);
- a little CSS in manual.css.
Because the phase data really lives in each module's ap_hook_* calls, I’d start
by hand-curating a dozen or so high-traffic modules as a prototype, and
then if that goes well, script up something that populates all the remaining
doc xml files.
So ... here's what I'm asking:
- Sanity check on the phase vocabulary and names (I've mirrored the section
names developer/request already uses).
- Opinions on the strip: inline-SVG vs. CSS cells; placement in the metadata
block; whether an optional DTD element is the right carrier. (I have no strong
preference on inline-SVG vs. CSS cells yet, just want the list's read on which
fits the build better.)
— Rich
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
