ores.doc.shell-recipe

One document that is both the recipe a reader opens and the source of the scripts the shell loads. A recipe is a literate document first: it says what a command is for, what it asks for, and where it is addressed. The script is the same document's export, so the prose and the runnable line cannot describe different commands.

The facet consumes a domain_entity, junction or operation model and writes one org document per model into doc/recipes/shell/<menu>/. It reads the same shell projection the generated command unit reads, so the document is a view of that unit rather than a second description of it: a command the unit gains arrives in the document that documents it, in the same commit.

The facet renders only where ores.cpp.shell-command rendered something for the same model. That dependency is stated as #+requires_facet: rather than as a second per-model opt-in, because two flags for one decision drift: a model that opts into the unit and not the document would ship commands with no recipe, and the reverse would ship a recipe for commands that do not exist.

Opt-in is the unit's, in other words: :ores.cpp.shell-command.enabled: in the model's properties drawer. The facet itself is enabled by default and resolves to nothing wherever the unit does.

Each command's block carries :tangle <menu>-<command>.ores. The tangle run honours that per block and moves the result into projects/ores.shell/scripts/library/<menu>/, so the document states the script's name and the build owns its directory. The library is what compass shell -f loads.

• ores.doc — the parent technical space's catalogue of documentation facets.
• ores.cpp.shell-command — the unit this facet documents.