Add a generated omarchy(1) man page - #8064
Open
aleksejunas wants to merge 2 commits into
Open
Conversation
tools/man-gen is a small Go program that reads `omarchy commands --all --json` and emits a groff man page. omarchy-dev-generate-manpage wires it up as `omarchy dev generate-manpage`. man/man1/omarchy.1 is the generated output, checked in so it can be reviewed as a diff — it is not hand-written and should not be hand-edited; regenerate it instead. Verified with `groff -man -ww -z` (zero warnings) and `man`. Per-group descriptions in the generator are a hand-maintained copy of GROUP_DESCRIPTIONS in bin/omarchy, since the JSON carries no group-level metadata. They need to be kept in sync manually when groups change there; this pass reconciled them against the current bin/omarchy (dropped stale groups, added missing ones). tools/man-gen/README.md documents this. Packaging the file to /usr/share/man/man1/ is a PKGBUILD change in the separate omarchy-pkgs repo and isn't included here.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a generated omarchy(1) manual page based on CLI command metadata.
Changes:
- Adds the Go man-page generator and documentation.
- Adds a developer regeneration command.
- Checks in the generated man page.
Tip
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
tools/man-gen/main.go |
Generates groff markup from command JSON. |
tools/man-gen/README.md |
Documents regeneration and verification. |
tools/man-gen/go.mod |
Defines the generator’s Go module. |
tools/man-gen/.gitignore |
Ignores generator binaries. |
bin/omarchy-dev-generate-manpage |
Adds the regeneration command. |
man/man1/omarchy.1 |
Provides the generated manual page. |
Suppressed comments (1)
tools/man-gen/README.md:22
- AGENTS.md:22-24 requires Markdown prose to use full lines rather than hard wrapping. Keep this paragraph on one line.
`omarchy commands --json` has no group-level metadata (a command's JSON only
carries its own group key), so the per-group one-line descriptions used in
the `.SS` headings are a hand-maintained copy of `GROUP_DESCRIPTIONS` in
`bin/omarchy`. When you add, rename, or remove a group there, update
`groupDescriptions` in `main.go` to match — nothing enforces this
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| } | ||
| if len(notes) > 0 { | ||
| fmt.Fprintln(w, ".br") | ||
| fmt.Fprintln(w, escText(strings.Join(notes, " "))) |
Author
There was a problem hiding this comment.
Confirmed, fixed in 227c5f4 — dropped the redundant escText pass over already-escaped notes.
Comment on lines
+129
to
+133
| if (r >= 0xE000 && r <= 0xF8FF) || // BMP PUA | ||
| (r >= 0xF0000 && r <= 0xFFFFD) || // Supplementary PUA-A | ||
| (r >= 0x100000 && r <= 0x10FFFD) { // Supplementary PUA-B | ||
| continue | ||
| } |
Author
There was a problem hiding this comment.
Confirmed, fixed in 227c5f4 — stripPUA now replaces a run of PUA runes with a <icon> placeholder instead of dropping them, so the example stays syntactically complete.
| ## Regenerating | ||
|
|
||
| ``` | ||
| omarchy commands --all --json | go run ./tools/man-gen -version "$(cat version)" -out man/man1/omarchy.1 |
Author
There was a problem hiding this comment.
Confirmed (reproduced the cannot find main module error locally), fixed in 227c5f4 — README now uses the same cd-into-the-module invocation as the wrapper script.
Comment on lines
+5
to
+6
| The output is generated, not hand-written — don't edit `man/man1/omarchy.1` | ||
| directly, edit this generator instead and regenerate. |
- escAliases already emits groff-escaped text (\- for hyphens); joining it
into `notes` and running the whole thing through escText again turned
those into \e-, rendering as a literal backslash in the output (e.g.
"theme\-switcher" instead of "theme-switcher"). Stop re-escaping notes
that are already safe.
- stripPUA dropped Nerd Font icon runes entirely, which could leave a
trailing flag with no value at all (`-g` with nothing after it). Replace
runs of PUA runes with a `<icon>` placeholder instead, so the example
stays syntactically complete.
- README's regenerate command was `go run ./tools/man-gen` from the repo
root, which fails ("cannot find main module") since tools/man-gen is its
own module. Match the wrapper script's cd-into-the-module invocation.
- Un-wrap two hard-wrapped paragraphs per AGENTS.md's markdown style.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR mot basecamp/omarchy (branch: man-page)
Tittel
Add a generated omarchy(1) man page
Beskrivelse
Adds
omarchy(1), generated fromomarchy commands --all --jsonrather thanhand-written.
tools/man-gen/— a small Go program that reads the JSONomarchy commands --all --jsonalready produces and emits groff markup.bin/omarchy-dev-generate-manpage— wires it up asomarchy dev generate-manpage.man/man1/omarchy.1— the generated output, checked in so it's reviewableas a diff. Not hand-written — don't hand-edit it. Regenerate with
omarchy dev generate-manpageinstead;tools/man-gen/README.mdhas thedetails.
Verified with
groff -man -ww -z(zero warnings) andman ./man/man1/omarchy.1.One caveat I want to be upfront about
The per-group section headings (
.SSin the page, e.g. "theme - Thememanagement") come from a hand-maintained copy of
GROUP_DESCRIPTIONSinbin/omarchy, becauseomarchy commands --jsondoesn't carry group-levelmetadata — only each command's own group key. I reconciled the copy against
today's
bin/omarchybefore opening this, but nothing keeps the two in syncautomatically going forward. A group that's renamed or added later will
silently fall back to a generic "
<Group>commands" heading here untilsomeone updates
tools/man-gen/main.goto match. Happy to add atest/clicheck that fails when the two drift, if that's useful — didn't want to add
it speculatively without knowing if you'd want it.
What this doesn't do
omacom-io/omarchy-pkgsrepo, not here. I've opened a companion PR therethat installs this file to
/usr/share/man/man1/— seeInstall the omarchy(1) man page omarchy-pkgs#200.
generator when commands change;
man/man1/omarchy.1is a snapshot as ofthis commit. Two ways to close that gap that I did not implement, in
case they're useful:
test/clicheck that regenerates and diffs against the committedfile, failing CI-adjacent review if they've drifted.
omarchy-pkgs's PKGBUILD insteadof committing a static file at all (would need
goas amakedependsand a
build()step there — a bigger change to a production releasepipeline, so I left it as a suggestion rather than code).