aslice man pages
This directory holds the man page sources. Status: specified interface and build workflow; generated CLI help and installation remain implementation work.
Two rules define the system:
- The man pages and the CLI help are one source.
aslice help <command>renders the same text asman aslice-<command>. There is no separate help text to drift out of sync — if a command's behavior changes, this file changes, and both views update together. - Pages are written for people. The reader is tired, something is broken, and the page's job is to be the shortest correct path back.
Format and building
Pages are Markdown in pandoc's man-page dialect: a three-line % title block, then NAME, SYNOPSIS, DESCRIPTION, and the sections the page needs. Build them with:
pandoc -s -f markdown-smart -t man man/aslice-install.1.md -o share/man/man1/aslice-install.1
The specified aslice build will run this command for every *.1.md here and installs the results into the prefix's share/man/man1/. Disabling Pandoc's smart extension preserves literal -- option prefixes and straight quotes in prose and option labels. aslice shellenv adds that directory to MANPATH. No other tooling is involved, and the source remains readable as plain Markdown on the web and in editors.
Writing style
- Start with what it does, then how to drive it, then the edge cases. NAME answers "what is this" in one line; DESCRIPTION answers "why do I care" in a short paragraph before any option appears. Overview before deep dive — the same shape as the manual.
- Options are documented, not narrated. One entry per flag, what it changes, what it costs. No filler ("This option allows the user to…").
- Say what a command will not do. The most valuable sentences on these pages are the honest limits: "never auto-rollback," "cannot touch the OS's own stack," "there is no always-allow." If a page doesn't state its command's limits, it's unfinished.
- Examples are realistic. Real package names, real flags, in the order a person would type them.
- Cross-reference aggressively. Every related command gets a SEE ALSO entry; the manual and the design docs get cited by section where the page is a summary of deeper material.
- Plain, direct English. Second person is fine, imperative is better. No marketing words, no hedging, no throat-clearing. If a sentence could appear in a blog post about "streamlining workflows," it doesn't belong here.
Conventions
- One page per user-facing command family:
aslice-use(1)coversuse/pin/default/versions/whichbecause they're one mental operation. - Overloaded spellings are called out on both pages (see
pinin aslice-use(1) and aslice-uninstall(1)). - Exit statuses and files get their own sections whenever they're non-obvious.
- When behavior differs between interactive and non-interactive runs, the page says so explicitly — scripts are readers too.
When you add a command, add its page in the same PR. A command without a page doesn't ship.
Database maintenance and reconstruction: aslice-db(1), including role selection, read-only inspection, coordinated backup, and confirmed restore.
Command families
| Family page | Commands |
|---|---|
| aslice-install(1) | install, reinstall |
| aslice-upgrade(1) | upgrade, outdated |
| aslice-uninstall(1) | uninstall, autoremove, mark, pin, unpin |
| aslice-apply(1) | plan install, lock export, apply |
| aslice-adopt(1) | adopt --from-homebrew |
| aslice-graft(1) | graft approvals, graft revoke |
| aslice-inspect(1) | search, info, flavors, leaves, why, provenance, audit |
| aslice-needs-restarting(1) | needs-restarting |
| aslice-profile(1) | history, rollback, switch-generation, link, unlink, profile prefer, exec, exec --replacement |
| aslice-use(1) | use, pin, default, versions, which |
| aslice-gc(1) | gc, clean, store verify |
| aslice-doctor(1) | doctor, log |
| aslice-db(1) | db list, db schema, db query, db check, db maintain, db compact, db backup, db restore |
| aslice-recover(1) | recover, operation status, operation stop |
| aslice-self-update(1) | self-update, decommission |
| aslice-repo(1) | repo add, repo list, repo enable, repo disable, repo remove, repo re-pin, repo keys, repo audit, repo allow-system-patch, repo deny-system-patch, repo build, repo sign, repo publish |
| aslice-orchard(1) | orchard add, orchard pin, orchard lint, orchard doctor, orchard freshness, orchard ci, orchard dependents, orchard deprecate, orchard disable, orchard undeprecate, orchard tombstone, orchard rename, orchard port |
| aslice-author(1) | create, lint, build, test, livecheck, bump-pr |
| aslice-farm(1) | farm plan, farm coordinator, farm agent, farm enroll |
| aslice-machine(1) | machine apply, machine export, machine import |
| aslice-service(1) | service list, service status, service start, service stop, service restart, service run |
| aslice-ca-update(1) | ca-update, ca-update --keychain, ca-update --keychain-remove, ca-update --crypto, ca-update --apple-certs, ca-update --from-file |
| aslice-system-patch(1) | system-patch list, system-patch status, system-patch restore, system-patch prepare, system-patch finalize |
| aslice-shell(1) | shellenv, init, config get, config set, help |
The complete syntax index is DESIGN §12.1. Related spellings resolve to their family page; CLI routing and installed man aliases remain implementation work.