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

[marc-medley]

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.

[Bo98]

Yeah this has been a thing forever. man <whatever> will work because you are in the shell environment where .zshrc has been run, but x-man-page etc is run completely outside of the shell environment so doesn't know about any environment variables.

You've indeed found the way to solve that, but there is perhaps more we can do here in at least documentation.

What's changed here is that the solution you propose didn't exist prior to Ventura as far as I know, so is relatively new.

[MikeMcQuaid]

@marc-medley just to summarise and make sure I've understood:

• everything is fine and works as expected on macOS Ventura Intel (I don't have a machine so cannot verify this)
• creating that file in /usr/local/etc/man.d fixes things on macOS Ventura ARM

[marc-medley]

@MikeMcQuaid

• everything is fine and works as expected on macOS Ventura Intel (I don't have a machine so cannot verify this)
• creating that file in /usr/local/etc/man.d fixes things on macOS Ventura ARM

correct.

[Bo98]

• everything is fine and works as expected on macOS Ventura Intel (I don't have a machine so cannot verify this)

This will be because /usr/local/share/man is in the default MANPATH. Non-default prefix on Intel probably doesn't work.

[marc-medley]

… /usr/local/share/man is in the default MANPATH

Some MANPATH details common to both ARM & Intel macOS Ventura:

• MANPATH is an empty variable in a default zsh shell environment. echo $MANPATH at the beginning of .zshrc is empty. set lists MANPATH='' and manpath=( ).
• manpath -d and man manpath show that the construction of the "search path for manual pages" in the shell environment is assembled from the PATH environment variable .and. /etc/man.conf .and. /usr/local/etc/man.d/*.conf.
  • man manpath: "MANPATH If set, causes the [manpath] utility to display a warning and the value, overriding any other configuration found on the system."
• /etc/man.conf contains a MANPATH config directive for /usr/local/share/man which is why the Homebrew man pages are found successfuly on macOS Intel.
  • /etc/man.conf has existed for a long time. At least back to 2005.
  • /usr/local/etc/man.d/*.conf is on a man page dated January 9, 2021. So, perhaps this has been supported since macOS Monterey (released on October 25, 2021)?

/etc/man.conf

# Every automatically generated MANPATH includes these fields
#
MANPATH	/usr/share/man
MANPATH	/usr/local/share/man
MANPATH	/usr/X11/man
MANPATH	/Library/Apple/usr/share/man
#
# Uncomment if you want to include one of these by default
#
# MANPATH	/opt/*/man
# MANPATH	/usr/lib/*/man
# MANPATH	/usr/share/*/man

[Bo98]

• /usr/local/etc/man.d/*.conf is on a man page dated January 9, 2021. So, perhaps this has been supported since macOS Monterey (released on October 25, 2021).

Ventura switched the implementation from an old GPL man (original homepage dead but references remain at https://directory.fsf.org/wiki/Man) to FreeBSD's man as of this commit: https://github.com/freebsd/freebsd-src/tree/f555b39e6bb7cbfbe1905e90f64c4dfc4456fabb/usr.bin/man (which has the Jan 2021 date in man.1)

[heller]

Hello! New contributor here, please be gentle. :-)

I have reproduced this issue under macOS Sonoma 14.0 on an M1 MacBook Air.

Since the FILES section of man man also mentions /etc/man.conf, and my system doesn't currently have a /usr/local/share directory at all, I decided to explore that alternative. Uncommenting the suggested line MANPATH /opt/*/man did not work, nor did MANPATH /opt/*/share/man. It does work to explicitly use MANPATH /opt/homebrew/share/man.

What I thought was weird is that, with /etc/man.conf in its default state, even if I remove Homebrew's MANPATH line from my ~/.zshrc and completely restart the computer, the shell's man still figures out how to load Homebrew's man pages in /opt/homebrew/share/man based on $PATH (I discovered this via man -d brew).

This is because, according to man manpath:

The manpath utility constructs the manual path from two sources:
     1.   From each component of the user's PATH for the first of:
          -   pathname/man
          -   pathname/MAN
          -   If pathname ends with /bin: pathname/../share/man and pathname/../man
     2.   The configuration files listed in the FILES section for MANPATH entries.

So, starting from /opt/homebrew/bin, it finds /opt/homebrew/share/man. Perhaps Homebrew simply sets $MANPATH in .zshrc for everyone because it's required on some platforms, but at least on Sonoma it doesn't seem to be needed anymore.

[heller]

Here are three possible approaches. From reading this discussion it seems that the first one might be preferred? Do we have to detect different systems and decide between 1 and 2 on the fly?

1. During install or update, mkdir -p /usr/local/etc/man.d/ and create/verify homebrew.man.conf there.
2. Append to /etc/man.conf.
3. Advise the user to do one of those things manually.

I can open a separate issue about possibly removing the MANPATH line from .zshrc and other dotfiles, but will avoid adding extra noise if somebody here knows off the top of their head that it ought to be left alone.

[MikeMcQuaid]

3. Advise the user to do one of those things manually.

This seems like the best option here given the relatively niche nature of the feature and fact that Intel Macs are no longer sold.

[marc-medley]

Some thoughts relative to three possible approaches…

1. During install or update, mkdir -p /usr/local/etc/man.d/ and create/verify homebrew.man.conf there.

On older macOS systems, the existance of /usr/local/etc/man.d/homebrew.man.conf would be ignored. i.e. no negative functional impact.

On Intel Ventura, the existance of /usr/local/etc/man.d/homebrew.man.conf has no negative functional impact. (I can provide more info here if needed.)

This option provides a useability convenience for Homebrew users on macOS Ventura and future macOS versions. ... without a negative impact on Intel macOS & past macOS versions.

2. Append to /etc/man.conf

I would be hesitant to modify /etc/man.conf because this file is part of the macOS distribution. And, the /usr/local/etc/man.d/*.conf is expressly provided for "Local configuration files". And, /usr/local/etc/man.d/*.conf allows isolation on a per-distribution basis. e.g., …/disto-name.man.conf.

3. Advise the user to do one of those things manually.

Independent of any Homebrew install/update process, some user documentation/info in-context (e.g., brew doctor and/or webpage(s)) seems like a good idea.

[heller]

3. Advise the user to do one of those things manually.

This seems like the best option here given the relatively niche nature of the feature and fact that Intel Macs are no longer sold.

Sorry if I was too slow editing my earlier post, but I did in fact reproduce this on Apple Silicon.

[MikeMcQuaid]

Sorry if I was too slow editing my earlier post, but I did in fact reproduce this on Apple Silicon.

@heller Sorry, missed that: can you repeat?

[marc-medley]

Sorry if I was too slow editing my earlier post, but I did in fact reproduce this on Apple Silicon.

Sorry, missed that: can you repeat?

@heller Does/did placing a homebrew.man.conf file (contents shown below) in /usr/local/etc/man.d fix this on an Apple ARM-based macOS Sonoma computer?

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

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

[heller]

@heller Sorry, missed that: can you repeat?

My fault, I should have been more clear. I was responding to this from @MikeMcQuaid:

3. Advise the user to do one of those things manually.

This seems like the best option here given the relatively niche nature of the feature and fact that Intel Macs are no longer sold.

I interpreted "Intel Macs are no longer sold" to mean that perhaps Mike thought that the issue only affects Intel Macs, and would therefore affect fewer and fewer users as time goes by.

[heller]

@heller Does/did placing a homebrew.man.conf file (contents shown below) in /usr/local/etc/man.d fix this on an Apple ARM-based macOS Sonoma computer?

Yes, this causes the Terminal.app contextual menu "Open man Page" to display a manpage for brew as expected.

[marc-medley]

Yes, this causes the Terminal.app contextual menu "Open man Page" to display a manpage for brew as expected.

@heller Thank you for confirming.

[marc-medley]

…given the relatively niche nature of the feature and fact that Intel Macs are no longer sold.

@MikeMcQuaid I think that the ‘niche … feature’ and ‘Intel Macs are no longer sold’ framings are somewhat misleading. Below is my perspective for your consideration:

‘niche’ → ‘ubiquitous’

…given the relatively niche nature of the feature

Terminal.app is not an "addon" application for macOS. Terminal is ‘ubiquitous’ across all macOS official distributions.

The Terminal Open man Page and x-man-page:// are not add-on features installed by a few users. These features are part of the Terminal itself. As such, these features are ‘ubiquitous’ across all macOS systems for all (non-restricted) macOS users.

This is a stardard, built-in, out-of-the-box feature for all macOS systems. It's a ‘ubiquitous’ macOS feature.

‘ARM’ & ‘Intel’ Mac

given … fact that Intel Macs are no longer sold.

A value of having Intel Macs and ARM Macs side by side is software regression testing.

The issue authored here is about a software regression where a Homebrew feature that had ubiquitously worked before stopped working.

For macOS Homebrew on Intel, this feature "Just works!" out-ot-the-box everywhere. Now it's broken for Homebrew installed on Apple Silicon.

This issue is not fundamentally about some missing documentation. The issue here is about a software regression bug which can be fixed for macOS Ventura (and newer) systems.

The side-by-side macOS Intel Homebrew and macOS ARM Homebrew Ventura systems enabled the investigation into the root cause and the discovery of a low-complexity software solution for this issue.

Downstream vs Upstream Fix

In general, an upstream fix at a single orginating source is preferred to a downstream fix in many diverse locations.

Placement of a homebrew.man.conf file in /usr/local/etc/man.d as part of macOS Homebrew installations has the following advantages:

• homebrew.man.conf is used automatically when applicable
• homebrew.man.conf is automatically, safely ignored when not applicable
• likewise, MANPATH directives in homebrew.man.conf are automatically used or safely ignored when applicable
• does not require any which macOS version? or which Mac hardware? type logic to be part of the Homebrew distribution.

Summary

The Terminal "Open man Page" & x-man-page://1/man feature is ‘ubiquitous’ in that it ships as part of macOS without needing the installation of any other software such as Xcode.

A side-by-side Intel and ARM Homebrew installation enabled the discovery of this bug and fault isolation to find a durable uncomplicated fix of adding homebrew.man.conf to /usr/local/etc/man.d.

Genuinely fixing the fundamental issue upstream at the distribution source for macOS homebrew users makes homebrew easier for any particular user. Ease of use promotes use.

[MikeMcQuaid]

The Terminal Open man Page and x-man-page:// are not add-on features installed by a few users. These features are part of the Terminal itself. As such, these features are ‘ubiquitous’ across all macOS systems for all (non-restricted) macOS users.

This is a stardard, built-in, out-of-the-box feature for all macOS systems. It's a ‘ubiquitous’ macOS feature.

It's standard but it's not widely used. If it was: this would not be the first complaint I've heard about this not working in my 14 years maintaining Homebrew 😉. There's a difference between a feature that's widely enabled and a feature that's widely used by Homebrew users. This is clearly not one of those features.

Placement of a homebrew.man.conf file in /usr/local/etc/man.d as part of all Homebrew installations has the following advantages:

It also has the disadvantage of requiring Homebrew to write files outside of HOMEBREW_PREFIX or the user's home directory during installation, something it takes great pains to not do.

If we were to go down this route: it would make an argument for writing to e.g. /etc/paths.d/homebrew which we have no plans to do.

Genuinely fixing the fundamental issue upstream at the distribution source for all homebrew users makes homebrew easier for any particular user. Ease of use promotes use.

It just doesn't make Homebrew easier for any user, that's an exaggeration. It only makes things easier for the users who want to use this feature with manages for Homebrew-installed software. This is not a significant proportion of Homebrew users. Honestly, it's not even clear it's literally any users beside yourself.

---

As a result, the solution we should take here is a simple one that's in keeping with how things in Homebrew are already, typically done. To me that's a solution that only involves automatically writing files somewhere within the HOMEBREW_PREFIX or documentation/messaging that tells users to manually do so themselves, if needed, outside HOMEBREW_PREFIX.

[heller]

As a Homebrew user who wasn't aware of this feature until a few days ago, it would certainly be surprising for my next brew up to tell me to re-run it with sudo so that it could change a file outside of its installation path.

How do we decide whether to add something like this as an INFO-level-ish output of brew doctor? It could create an extra step for many users who are troubleshooting unrelated problems.

Homebrew supports several flavors of Linux, and at the moment I don't know if the proposed homebrew.man.conf documentation would be accurate for all of them.

[MikeMcQuaid]

As a Homebrew user who wasn't aware of this feature until a few days ago, it would certainly be surprising for my next brew up to tell me to re-run it with sudo so that it could change a file outside of its installation path.

Yup, strongly agreed.

How do we decide whether to add something like this as an INFO-level-ish output of brew doctor? It could create an extra step for many users who are troubleshooting unrelated problems.

Agreed, brew doctor isn't the right fit here.

My thinking is this is probably best placed in somewhere like https://docs.brew.sh/Tips-N%27-Tricks

[marc-medley]

Homebrew supports several flavors of Linux, and at the moment I don't know if the proposed homebrew.man.conf documentation would be accurate for all of them.

@heller Valid point. In my comments, the scope for homebrew.man.conf file use was intended to be macOS only since Apple's standard Terminal.app is a prerequisite.

There was a time (circa 2009-2018) when Homebrew was Mac OS X/OS X/macOS only. As a long-time mac/homebrew user, I still tend to think of homebrew as a "mac app".

My recent comment has been updated to clarify the macOS scope, which is also the same scope as the original post. Thanks.

[marc-medley]

@MikeMcQuaid Your comments, along with the comments of others, have provided several valuable insights. Much to think about.

I will be pondering/rethinking this issue over the weekend and will provide some re-focused comments sometime next week.

btw, I'm an old school command line user. My command line adventures started in 1975 with ed and g/re/p on a PDP system with AT&T UNIX. This likely makes me an even rarer bird than your comments imply.

Thanks for your many years with Homebrew. Respect.

[MikeMcQuaid]

Thanks for your many years with Homebrew. Respect.

@marc-medley Thanks for the kind words ❤️ and well done on surviving 40 years of Unix 😅

[marc-medley]

@MikeMcQuaid, @heller As noted above, I am working through some additional (hopefully, well thought-out & relevant) comments for your consideration.

I will be pondering/rethinking this issue over the weekend and will provide some re-focused comments sometime next week.

I would appreciated being allowed this week for adding such comments before this issue is closed out. Would this be possible? Thanks.

[MikeMcQuaid]

@marc-medley As noted on the other issue: let's continue talking now this is closed and can reopen if we agree on something actionable. Thanks!

[marc-medley]

@MikeMcQuaid

let's continue talking now this is closed and can reopen if we agree on something actionable.

OK. Works for me. Thanks.