Brew installed software (keg-only) which includes /usr/local/Cellar/*/share/man/ – No manual entry for readline

command linehomebrewterminal

I installed the keg-only readline

> brew info readline
readline: stable 7.0.1 (bottled) [keg-only]
Library for command-line editing
https://tiswww.case.edu/php/chet/readline/rltop.html
/usr/local/Cellar/readline/7.0 (45 files, 2M)
  Poured from bottle on 2016-11-22 at 22:40:10
/usr/local/Cellar/readline/7.0.1 (46 files, 2M)
  Poured from bottle on 2016-12-03 at 22:44:53
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/readline.rb
==> Caveats
This formula is keg-only, which means it was not symlinked into /usr/local.

macOS provides the BSD libedit library, which shadows libreadline.
In order to prevent conflicts when programs look for libreadline we are
defaulting this GNU Readline installation to keg-only.


Generally there are no consequences of this for you. If you build your
own software and it requires this formula, you'll need to add to your
build variables:

    LDFLAGS:  -L/usr/local/opt/readline/lib
    CPPFLAGS: -I/usr/local/opt/readline/include

This package installs manpages:

> brew ls -v readline | grep man
/usr/local/Cellar/readline/7.0.1/share/info/rluserman.info
/usr/local/Cellar/readline/7.0.1/share/man/man3/history.3
/usr/local/Cellar/readline/7.0.1/share/man/man3/readline.3
/usr/local/Cellar/readline/7.0.1/share/readline/fileman.c
/usr/local/Cellar/readline/7.0.1/share/readline/manexamp.c

I can't see the manual. I get No manual entry for readline.

Howto view the manual with man readline?

Best Answer

The -M option for man allows you to specify a path. The exact command you're looking for is:

man -M 3 /usr/local/Cellar/readline/7.0.1/share/man/man3/readline.3

Note that the number after the -M specifies the "man page section", which is the last character in the file path. For example, I have two versions of sshd installed and I read can both their man pages with the following commands:

man -M 8 /usr/share/man/man8/sshd.8
man -M 8 /usr/local/Cellar/openssh/7.3p1/share/man/man8/sshd.8

I'm curious why brew didn't symlink readline, since brew's readline is the only one installed - presumably past versions (I'm on Sierra) of macOS did have readline? I'd tend to be conservative here, and honour brew's decision as far as possible - just in case Apple decide to install readline again with a future OS upgrade. That being said, you could manually symlink readline:

ln -s /usr/local/Cellar/readline/7.0.1/share/man/man3/readline.3 /usr/local/share/man/man3/readline.3

The risk with this is that - if Apple do install readline in the future - you'll end up with Apple's readline in your $PATH (and not brew's, since it's keg-only and hasn't been linked), but brew's readline will occur first in your $MANPATH, before the man page for Apple's readline.

Related Question