== Command-line interface === Name, synopsis, and description *loom* extracts generated files from annotated source fences. Invocation is `loom [--help|--version] [directory]`; the default directory is `.`. The description below is defined once as format-neutral text and included in both Clojure's help message and the manual page. It must remain safe inside a Clojure string and as ordinary roff prose: no quotes, backslashes, or leading roff control characters. Whole-line inclusions preserve indentation; inline inclusions must expand to exactly one logical line. ```text #| id: loom-cli-help-description Read loom.edn and tangle named code blocks in watched source files. ``` Follow `<>` for the Clojure assembly. It trims the deliberate multiline string boundaries around this shared text, retaining the existing help output rather than adding blank lines. === Options and arguments - `--help` or `-h` prints usage and succeeds; help is checked first, anywhere in the argument list. - `--version` prints `loom 0.1.0` and succeeds when help was not requested. - Otherwise the first argument selects the project directory. Current code is not a strict option parser: additional arguments are not interpreted and an unrecognised option in first position is treated as a directory name. - A project failure prints `loom:` and contextual error data to stderr and exits with status 1. Successful invocations return normally. === Files and configuration The directory must contain `loom.edn`. `watch` is a required vector of regex strings matched against entire relative source paths. Optional `source-roots` restricts traversal; source paths are sorted and deduplicated before reading. See `<>` for this repository's actual configuration and `<>` for validation. Leading fence annotations accept `file`, `id`, `executable`, and `presentation`. Only a file annotation creates an output target; ID-only fragments are reusable, and anonymous examples are ignored by the executable index. An explicit ID wins over the file path for naming; last repeated annotations win. Presentation is checked and discarded by the CLI. Executable values must be `true` or `false` and require a file annotation. Closing fences need at least the opening count of backticks. Syntax is a small fixed convention, not a general Markdown parser. `:annotation` defaults to `:standard`. `:naked` emits only expanded source; `:supplemented` currently behaves like standard. Extension overrides match the final suffix, case-sensitively; dotfiles and extensionless files use the default. See the adoption guide for choosing modes, not a second configuration listing. === Output, diagnostics, and guarantees `Writing` identifies a new or changed target. `Unchanged` means byte-identical content was not replaced, preserving modification time, inode, and permissions. No targets prints `No target files found.` without starting workers. A shared target ID warns that references include all named blocks; root bodies remain separate per output path. Missing configuration, invalid annotations, unterminated fences, missing or cyclic inclusions, zero-line or multiline inline expansions, escaping/symlink output paths, aliased targets, and staging failures are errors. Validation precedes staging, all staging precedes publication, and replacements occur in target order. Replacement is atomic per file where supported, *not* a multi-file transaction: a later move failure can leave earlier outputs updated. Existing modes survive regeneration; only explicitly requested new files gain an executable bit. === A generated brief manual page This root uses naked `.1` output and includes the same description ID as the CLI. View it locally with `man -l tangled/man/loom.1`. The Nix package installs it under `share/man/man1`; no separate manpage generator is required. ```roff #| file: tangled/man/loom.1 .TH LOOM 1 "" "Loom 0.1.0" "User Commands" .SH NAME loom \- extract files from literate sources .SH SYNOPSIS .B loom .RI [ --help | --version ] .RI [ directory ] .SH DESCRIPTION <> .SH OPTIONS .TP .B --help, -h Print usage and exit. Takes precedence wherever it appears. .TP .B --version Print the version and exit unless help was requested. .TP .I directory Project directory, defaulting to the current directory. .SH FILES .TP .I loom.edn Source selection, annotation modes, and extension overrides. .SH OUTPUT Writing identifies new or changed files; Unchanged preserves identical files. Existing permissions are retained. New files are executable only when declared. .SH EXIT STATUS Zero on success or help/version; one on a project failure. Publication is atomic per replacement, not a multi-file transaction. ```