Skip to content

[Homebrew] Replace the placeholder man command with a real viewer - #87

Draft
brandonpayton wants to merge 2 commits into
mainfrom
feature/man-formula-candidate-qk044
Draft

[Homebrew] Replace the placeholder man command with a real viewer#87
brandonpayton wants to merge 2 commits into
mainfrom
feature/man-formula-candidate-qk044

Conversation

@brandonpayton

@brandonpayton brandonpayton commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Why

The shell currently gets a placeholder man command from posix-utils-lite.
That command only copies a raw file from one hard-coded directory. It does not
provide normal section lookup, roff formatting, compressed pages, manual-page
search, or terminal paging.

This change uses mandoc, a small ISC-licensed manual-page toolset, to provide the
normal man experience through Kandelo's Homebrew package path.

What changes

  • Add upstream mandoc 1.14.6 from its official archive and verified checksum.
  • Cross-build it with an explicit Kandelo feature table. Upstream's configure
    script runs compiled probes, so using host probe results would describe the
    build machine instead of the WebAssembly target.
  • Use the tap's normal zlib dependency for compressed pages and less
    dependency for interactive paging.
  • Instrument man for its real fork/exec pager path.
  • Use Homebrew's normal global share/man links. The page itself remains in
    the package's versioned Cellar directory, so opening one page can materialize
    only the bottle that owns it.
  • Keep direct filename lookup as the normal viewing path. Automatically building
    one global mandoc.db would scan every deferred package and defeat lazy
    bottle retrieval. Users can still run makewhatis, and whatis/apropos
    work against the resulting database.
  • Remove the placeholder man link from posix-utils-lite and bump that
    Formula to revision 1 so an old bottle cannot silently keep providing it.

The paired Kandelo change in
Automattic/kandelo#1077
removes the placeholder package/rootfs entry and verifies the exact lazy VFS
behavior: global manual-page links remain metadata-only, the first page read
fetches its owning bottle, and unrelated bottles remain deferred.

Runtime coverage

The Formula covers:

  • default and explicit manual sections;
  • man -w path lookup;
  • .so aliases;
  • gzip-compressed pages;
  • both man and mdoc source formats;
  • demandoc and soelim;
  • truthful failure for a missing page;
  • Homebrew's exact global-symlink-to-Cellar layout;
  • makewhatis, whatis, and apropos;
  • Chromium formatting; and
  • a real PTY pager session through less.

Validation

Exact head: 694ab114827e895ee87af842be20c62f5eee692a

  • mandoc source cross-build against ABI 41: passed
  • Wasm ABI and required-fork artifact guards: passed
  • Node.js runtime checks for the complete command surface above: passed
  • Chromium formatting on the same binary build path: passed
  • real PTY less fork/exec and quit flow on the same binary build path: passed
  • Formula support suite: 94 runs / 853 assertions, no failures
  • brew style Formula/mandoc.rb: passed
  • Ruby syntax and git diff --check: passed

Rollout

This remains a draft. No bottle publication workflow has been dispatched.

Before publication, the posix-utils-lite source pin must be updated to the
final Kandelo commit that removes the placeholder. The coordinated rollout is:

  1. finish the current Dinit rollout;
  2. land the paired Kandelo change and pin its immutable source revision here;
  3. publish the revised posix-utils-lite bottle;
  4. publish the mandoc bottle; and
  5. select mandoc in the lazy shell closure.

Package upstream mandoc 1.14.6 as the real man, formatter, lookup, and pager implementation. Cross-build with explicit Kandelo target capabilities, normal zlib and less dependencies, and required fork instrumentation for the pager path.

Keep manual-page lookup deterministic over Homebrew MANPATH without generating a global database that would materialize every deferred bottle. Remove only the old posix-utils-lite man alias and prove Node, Chromium, section selection, roff formatting, and real PTY paging.
Exercise section lookup, aliases, compressed and mdoc pages, helper tools, database-backed search, and the exact Homebrew Cellar symlink layout. Bump posix-utils-lite so its next bottle truthfully drops the retired placeholder man command.
@brandonpayton
brandonpayton force-pushed the feature/man-formula-candidate-qk044 branch from c2421e9 to 694ab11 Compare July 23, 2026 17:14
@brandonpayton brandonpayton changed the title [Homebrew] Provide a real manual-page viewer [Homebrew] Replace the placeholder man command with a real viewer Jul 23, 2026
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.

1 participant