brew: Terminal.app "Open man Page" context menu and 'x-man-page' URI scheme not working in Apple Silicon for brew formulae

brew doctor output

Your system is ready to brew.

Verification

• My “brew doctor output” above says Your system is ready to brew. and am still able to reproduce my issue.
• I ran brew update twice and am still able to reproduce my issue.
• This issue’s title and/or description do not reference a single formula e.g. brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.

brew config output

HOMEBREW_VERSION: 4.1.14
ORIGIN: https://github.com/Homebrew/brew
HEAD: affc4c01aada2c973b63e084e7696e896edf2b7b
Last commit: 29 hours ago
Core tap JSON: 02 Oct 22:39 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_EDITOR: /usr/bin/nano
HOMEBREW_MAKE_JOBS: 8
Homebrew Ruby: 2.6.10 => /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby
CPU: octa-core 64-bit arm_firestorm_icestorm
Clang: 15.0.0 build 1500
Git: 2.39.3 => /Applications/Xcode.app/Contents/Developer/usr/bin/git
Curl: 8.1.2 => /usr/bin/curl
macOS: 13.6-arm64
CLT: 15.0.0.0.1.1694021235
Xcode: 15.0
Rosetta 2: false

What were you trying to do (and why)?

I was trying on open the Terminal.app “Man Page” view for formulae installed via brew.

Approaches that I use were the “Open man Page” via context menu item and the x-man-page URI scheme. These approaches are detailed in the “step-by-step reproduction instructions”.

Why?

1. Because the Terminal “Man Page” nicely presents the complete man page in a single dedicated searchable window.
2. Because x-man-page:// links in Markdown files provide quick incontext information lookup.

What happened (include all command output)?

The “Man Page” would open with the message “No manual entry for ABC”, where ABC is anything related to the brew installation. e.g., brew, gnuplot, octave, etc.

This issue was discovered on an Apple ARM macOS system. This issue was verified to not be present on an Intel x86_64 macOS system.

Additional Findings

I was puzzled because the command man brew on the command line itself would function as expected using the default less pager.

I found that MANPATH in the .zshrc was not resolving the issue on macOS Ventura with Terminal 2.13.

After reading documentation and some trial-and-error, I found that the addition of a ‘homebrew.man.conf’ to ‘/usr/local/etc/man.d’ resolved the issue.

/usr/local/etc/man.d/homebrew.man.conf

### Homebrew
MANPATH /opt/homebrew/share/man
MANPATH /opt/homebrew/Cellar/*/*/share/man

Apparently, the Terminal “Open man Page” context menu item and x-man-page URI scheme have a more limit man search which appears to just include /etc/man.conf and /usr/local/etc/man.d/*.conf.

What did you expect to happen?

I expected a new Terminal “man Page” window to open with the man content of the brew-installed-item because the man brew-installed-item command was functional in the command line interface.

For example, the not-brew-installed swift opens to the following Terminal man page window:

Expectations & Possible Homebrew Solution

It seems reasonable to expect that an automated Homebrew installation would include the addition of a homebrew.man.conf file in /usr/local/etc/man.d.

It also seems reasonable to expect that brew doctor provide some user messaging (if homebrew.man.conf is not present) which enables the user to manually add this file. For example, the brew doctor might mention something like:

A homebrew.man.conf file was not found in /usr/local/etc/man.d. A homebrew.man.conf file is needed for the Terminal “Open man Page” and the x-man-page:// URI Scheme to function on ARM-based macOS systems.

### Create /usr/local/etc/man.d directory if not already present
sudo nano /usr/local/etc/man.d/homebrew.man.conf

homebrew.man.conf

### Homebrew
MANPATH /opt/homebrew/share/man
MANPATH /opt/homebrew/Cellar/*/*/share/man

I also posted the /usr/local/etc/man.d/homebrew.man.conf approach on the AskDifferent StackExchange forum.

---

One More Note:

The “FILES” listed at the bottom of the man man page appear to be the full search scope for the Terminal “Open man Page” and the x-man-page:// URI Scheme features.

If one looks inside /etc/man.conf, it is evident why the brew on macOS Intel works OK. The /etc/man.conf contains MANPATH /usr/local/share/man which is where macOS Intel Homebrew puts the man folders.

It is the new macOS ARM-based homebrew man files placement which can no longer be found under the /etc/man.conf & /usr/local/etc/man.d/*.conf umbrella. Thus, the addition of homebrew.man.conf in /usr/local/etc/man.d could appropriately be part of the newer Homebrew installation. i.e. the Terminal app did not “change” or “break”, rather ARM Homebrew moved to a new-improved location.

Step-by-step reproduction instructions (by running brew commands)

**Terminal: Context Menu**

1. `brew install EXAMPLE_FORMULA` or use an existing formula.
2. Selected the EXAMPLE_FORMULA test on the command line.
3. Context click on the `EXAMPLE_FORMULA` and select then "Open man Page" context menu item.

**Markdown**

1. Create a markdown file (or use an existing one) which contains a `x-man-page://` line. For example: `[brew](x-man-page://1/brew)`
2. Click on the resulting hyperlink in MacDown, VSCodium Markdown or similar markdown editor. Or, convert the Markdown to HTML and click that link.

**Browser**

1. Type `x-man-page://1/brew` into an internet browser address line.
2. Type return.

**CLI**

1. Type `open x-man-page://1/brew` in the terminal command line.
2. Type return.

**Text Only: Context Menu**

Note: The "Open man Page in Terminal" can be enabled macOS system-wide service for anywhere text is selected. For this case, the Settings > Keyboard > Services > Text : "Open man Page in Terminal" needs to be enabled.

1. Type 'brew' text into some mac app such as BBedit, CotEditor, or Pages.
2. Selected the 'brew' text.
3. Context click on the `EXAMPLE_FORMULA` and select then "Open man Page" menu item.