NAME

Proc::Spawner::Docs - a map of the design documents shipped in doc/ (EXPERIMENTAL)

DESCRIPTION

Besides the POD of its modules, the distribution ships its design notes as Markdown files under doc/. CPAN tools do not show those files as documentation, so this page lists them, says who wrote each one and what it is for, and links to them on MetaCPAN's source browser. The links go to the newest release; a ?raw=1 link shows the file as it is stored.

The notes were written with Claude, at first by two working sessions with their own file prefixes: the executor session (prefix pspawn-: Proc::Spawner, Proc::Spawner::Graph, Proc::ShellSpawn) and the parser session (prefix large-subset-: Proc::ShellSubset::Large). Since 2026-11-02 one session maintains everything. The base parser's notes (doc/parsers/) come from an earlier session.

Status words used below: current (describes the code of this release), reference (a rule set or a procedure that stays valid), history (kept for the record; may use the module names of its day: ShellSpawn is now Proc::ShellSpawn, ShellSubsetLarge is now Proc::ShellSubset::Large, and so on).

An experiment: the same document in two forms

doc/large-subset/large-subset-state.md and doc/large-subset/large-subset-state.md.html

The same text twice. The .md.html copy is the Markdown with a Markdeep footer (and a charset line at the top): a browser that opens it renders the Markdown itself, by a script loaded from https://casual-effects.com/markdeep/. The pair is here to see which form reads better on MetaCPAN. .md, .md.html, .md.html, raw.

Which version a figure belongs to

Every measured figure in these documents names the code it was measured on: pre-0.01 (the modules under their former names, before the first distribution), 0.01, 0.02 (the parsers of 0.01), early-post-0.02 (0.02 plus items P1-P4 of the page "Shell Corpus Gaps", the evening of 2026-11-02; that code was not kept), and 0.03. The table is at the end of doc/README.md.

Start here

doc/README.md

The index of the design notes, with the rename table of the modules. Current.

doc/test-pools.md

How to rebuild every test pool taken from public collections (tldr, NL2Bash, ShellCheck's tests, three books of examples) from pinned sources, and the per-test record of how dash and bash differ. Reference.

The executor: Proc::Spawner, Proc::Spawner::Graph, Proc::ShellSpawn (prefix pspawn-)

pspawn-spawner.md

The architecture: how Proc::Spawner (posix_spawn and the one event loop), its graph and Proc::ShellSpawn (running parse trees) fit together; what is not done yet. Current.

pspawn-known-issues.md

Every known issue, open and fixed, of the executor and the parsers, with its ID (X…, L…, E…). Current.

pspawn-design.md

The executor's internals: file actions, the event loop, which posix_spawn features are used and why. Reference (older names).

pspawn-graph.md

The spawn-graph notation, its pictures, and the hand-written graphs used in the tests. Reference.

pspawn-extensions.md

The extension points (handlers named by sub names, the tables of command kinds and command names) and the decisions behind them. Reference.

perl-signals-findings.md

Perl's signal and child-process model and its defects, met while writing the event loop; candidate reports for Perl itself. Reference.

pspawn-run-shortcomings.md

Why the earlier executor (the module Run) was replaced. History.

pspawn-upstream-reports.md

Reports from the executor session to the parser session. History.

The base parser: Proc::ShellSubset, Proc::ShellSubset::Small (doc/parsers/)

shell-subset-spec.md

The grammar of Proc::ShellSubset (Proc::ShellSubset::Small is the same with its options frozen), the decided rules, and the parse tree. Reference (older names).

shell-subset-test-provenance.md

Where each borrowed test comes from: the snippet IDs, the pinned sources and their licences, how the tests were chosen. The scripts are in doc/parsers/tools/. Reference.

shell-subset-corpus-stats.md

The first corpus measurements (2026-10-29/30, pre-0.01). History.

The large parser: Proc::ShellSubset::Large (doc/large-subset/, prefix large-subset-)

README.md

The index of this directory. Current.

large-subset-state.md

The state of the union: the rules for matching dash and bash and which rule beats which, the corpus figures, the work list, the open questions. Current (also as .md.html, see above).

large-subset-spec.md

What the large grammar accepts beyond Proc::ShellSubset, its tree additions, and the run-time rules of the executor. Current.

large-subset-dialect-features.md

Every probed difference between dash and bash, blatant or subtle, with who or what decided the verdict (a probe, bash's manual, ShellCheck, or a judgement still open). Current.

large-subset-ceiling.md

How the corpus measurement was made honest step by step (what is left out, and why). Its yardsticks section is superseded by large-subset-state.md. History, partly reference.

large-subset-investigation.md

The study that started the large parser: how much more of sh can Perl run itself. History.

large-subset-marks.md

A snapshot of the decisions marked on two checklist pages. History.

large-subset-upstream-reports.md

Bugs the parser session found in other components, and its requests to the executor session. History.

Not Markdown

doc/checklists/*.html are the decision pages (items, plans, and Claude's answers; the marks lived in the published pages and show empty here). doc/large-subset/tools/ and doc/parsers/tools/ hold the measurement and test-pool scripts; doc/large-subset/dialect-cases/ the probes run in both shells.

SEE ALSO

Proc::Spawner, Proc::ShellSpawn, Proc::ShellSpawn::Builtins, Proc::ShellSubset, Proc::ShellSubset::Large.