Skip to content

docs: describe man1/ as the shell-command pages it actually ships - #1591

Open
FBISiri wants to merge 1 commit into
basicmachines-co:mainfrom
FBISiri:docs/man1-section-actual-pages
Open

FBISiri wants to merge 1 commit into
basicmachines-co:mainfrom
FBISiri:docs/man1-section-actual-pages

Conversation

@FBISiri

@FBISiri FBISiri commented Sep 21, 2026

Copy link
Copy Markdown
Contributor

docs/manual-pages.md describes man1/ as the section holding bm(1) and
bm-status(1). Neither page is bundled. This points the docs at the pages
that man1/ actually ships. Docs only, no code touched. Fixes #1590.

What I checked at 3bf2d523

bm man list is bundled_pages(), which is
MAN_DIR.glob("man[1-9]/*.md") (src/basic_memory/man/__init__.py:116). So
the shipped set is exactly what is on disk:

$ ls src/basic_memory/man/man1/
apropos(1).md  cat(1).md  find(1).md  grep(1).md
head(1).md     ls(1).md   tail(1).md  tree(1).md

$ ls src/basic_memory/man/man3/ | wc -l
22

Eight section-1 pages, 22 section-3 pages, 30 total — all shell commands or
MCP tools. No bm-status(1), no bm(1). bm man bm-status therefore takes
the bundled-miss path in show() and falls through to the manual project,
which on a plain install prints:

No manual entry for bm-status  (try: bm man list)

The groff sources do exist, but not as man[1-9]/*.md pages:

$ ls src/basic_memory/man/
basic-memory.1  bm.1  __init__.py  man1/  man3/

$ cat src/basic_memory/man/basic-memory.1
.so man1/bm.1

bm.1 and basic-memory.1 sit at the man/ root, and bm man install
globs them with _MAN_SOURCE_DIR.glob("*.1")
(cli/commands/man.py:239) to copy into ~/.local/share/man/man1/. That
is a separate pipeline from bundled_pages(), which is why man bm works
after bm man install while bm man bm does not.

Question for @phernandez — which fix do you want?

There are two defensible reads of #1590 and they lead to different patches:

(A) The docs are wrong. man1/ was always meant to be the shell-command
section, bm(1)/bm-status(1) in that line is leftover text from an earlier
plan, and the fix is to describe what ships. That is this PR: 13 lines, no
behaviour change.

(B) The docs are right and the packaging is behind. bm(1) is supposed
to be readable through bm man, the groff source is already sitting in the
tree, and the real gap is that bundled_pages() only ever looks in
man[1-9]/, so a page at the man/ root can never surface. Then the fix is
to wire bm.1 into the bundled set (or add a bm(1).md), and bm-status(1)
becomes a page to write rather than a line to delete.

I can't tell from outside which one is intended, because both are consistent
with the current tree — the man/-root groff files could be deliberately
install-only, or just not wired up yet. The Roadmap section's "Groff for
section 3" item reads like the two pipelines are meant to converge eventually,
which nudges me toward (B) being the long-term intent and (A) being correct
for today. But that's a guess about your plan, not something the code tells
me.

If you want (B), say so and I'll redo this as (B) instead — happy to close
this one.

DCO sign-off is included on the commit. I'll sign the CLA whenever the bot
asks.

docs/manual-pages.md describes man1/ as holding `bm(1)` / `bm-status(1)`,
but no such page is bundled: man1/ ships eight shell-command pages and
`bm man bm-status` returns "No manual entry". Point the docs at the pages
that are actually there.

Fixes basicmachines-co#1590

Signed-off-by: Siri <masteragentsiri@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: manual-pages.md documents bm-status(1), which is not a bundled page

1 participant