Submit Hint Search The Forums LinksStatsPollsHeadlinesRSS
14,000 hints and counting!

Fix missing man pages for self-installed utilities UNIX
The rule is to install any custom UNIX utilities in /usr/local, but unfortunately due to the way man is set up, the man pages for things installed in /usr/local may not be found.

The problem is that the man configuration file (/usr/share/misc/man.conf) defines a number of MANPATH_MAP directives. Here are some of them:
MANPATH_MAP    /usr/bin                /usr/share/man
MANPATH_MAP    /usr/sbin               /usr/share/man
MANPATH_MAP    /usr/local/bin          /usr/local/share/man
This means, for instance, that if you type man grep, man examines your PATH variable and finds that the grep executable is in /usr/bin. The MANPATH_MAP directive instructs it to look in the /usr/share/man directory to find the man page for grep. This overrides man's default behavior, which would be to look in the "nearby" directory /usr/man, which does not exist.

However, in the case of software installed in /usr/local, the man pages are more commonly (at least in my experience) installed in /usr/local/man, not /usr/local/share/man, so that MANPATH_MAP directive does the opposite of what we want.

If you keep all your /usr/local man pages in /usr/local/man rather than /usr/local/share/man, the simple solution is just to comment out that one MANPATH_MAP directory. You'll need to use sudo, since the /usr/share/misc/man.conf file is owned by root.
    •    
  • Currently 3.25 / 5
  • 1
  • 2
  • 3
  • 4
  • 5
  (4 votes cast)
 
[12,276 views]  

Fix missing man pages for self-installed utilities | 11 comments | Create New Account
Click here to return to the 'Fix missing man pages for self-installed utilities' hint
The following comments are owned by whoever posted them. This site is not responsible for what they say.
Fix missing man pages for self-installed utilities
Authored by: tforrest on Mar 06, '06 07:30:42AM
What if you have software that installs man pages in usr/local/man and usr/local/share/man?

[ Reply to This | # ]
Fix missing man pages for self-installed utilities
Authored by: Ben Smith on Mar 06, '06 07:39:38AM

Personally I solved this problem by adding this to /Users/<my user>/.bash_profile

MANPATH=$MANPATH:/usr/local/man

-Ben



[ Reply to This | # ]
Fix missing man pages for self-installed utilities
Authored by: jonbauman on Mar 07, '06 05:16:52PM

Setting the MANPATH variable is somewhat deprecated, so I'd recommend against it. The problem is that setting it completely overrides the nice heuristics that man uses to locate manual pages. This is particularly important if you are installing your own versions of standard utilities because if you set things up correctly, man will automatically choose the manpage for the version that comes first in your PATH.

I think the best solution is to make a symbolic link from /usr/local/share/man to /usr/local/man. Then, man's heuristics will correctly find the manpages for any command in /usr/local/bin.

---
jon

[ Reply to This | # ]

Fix missing man pages for self-installed utilities
Authored by: tirerim on Mar 06, '06 07:44:17AM
Alternatively, you can just set your MANPATH manually. In my .cshrc file, I have

setenv MANPATH /usr/local/man:/usr/share/man:/usr/X11R6/man:/usr/local/share/man:/usr/local/clamXav/man:/opt/local/share/man

which simply tells man to look in all of those directories. This also takes care of things that make their own subdirectories in /usr/local, the DarwinPorts directory hierarchy (/opt), etc. Note that for bash users, you'll have to use something like

export MANPATH=/usr/local/man:/usr/share/man:/usr/X11R6/man:/usr/local/share/man:/usr/local/clamXav/man:/opt/local/share/man

instead.

[ Reply to This | # ]

Fix missing man pages for self-installed utilities
Authored by: artemio on Mar 06, '06 08:49:08AM
Probably the most flexible option is to leave alone /usr/share/misc/man.conf and the $MANPATH variable, move all the stuff in /usr/local/man/ (if any) to the corresponding place in /usr/local/share/man/, and then

cd /usr/local/
rm -r man
sudo ln -s share/man man

This turns /usr/local/man into a symlink to /usr/local/share/man/. This way, if a third party app needs to install something in /usr/local/man/, it'll be fooled into installing it in the "official" location /usr/local/share/man/.

Cheers,

Artemio

P.S. To transfer all the stuff in /usr/local/man/ to /usr/local/share/man/, try

cd /usr/local/man
tar czvf - . | tar xzvf - -C ../share


[ Reply to This | # ]
Fix missing man pages for self-installed utilities (correction)
Authored by: artemio on Mar 06, '06 08:54:52AM
There was a typo in the instructions I gave to transfer all the stuff in /usr/local/man/ to /usr/local/share/man/. The correct command is:

cd /usr/local
tar czvf - man/ | tar xzvf - -C share


[ Reply to This | # ]
Fix missing man pages for self-installed utilities
Authored by: vogunaescht on Mar 06, '06 09:41:45AM
Or put the same environment variable into ~/.MacOSX/environment.plist, which might look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>MANPATH</key>
        <string>/usr/local/man:/usr/X11R6/man:/usr/share/man</string>
</dict>
</plist>
Change the MANPATH string to your likeing.

[ Reply to This | # ]
Fix missing man pages for self-installed utilities
Authored by: n8gray on Mar 06, '06 12:00:02PM
Instead of just choosing one directory, have man search both. Put this in your /usr/share/misc/man.conf:
MANPATH /usr/local/man
MANPATH /usr/local/share/man

MANPATH_MAP /usr/local/bin /usr/local/share/man   #either one is fine here
This will tell man to try /usr/local/share/man first, but then fall back to the normal man path, which now includes /usr/local/man.

[ Reply to This | # ]
Fix missing man pages for self-installed utilities
Authored by: baltwo on Mar 06, '06 01:41:15PM

Why not keep it simple and just modify your ~/.profile which allows you to directly modify the PATH and MANPATH variables. BTW, most users don't have a /.MacOSX/environment.plist file—I don't. Here's my .profile file; tailor yours to suit your specific needs:

##
# DELUXE-USR-LOCAL-BIN-INSERT
# (do not remove this comment)
##
echo $PATH | grep -q -s "/usr/local/bin"
if [ $? -eq 1 ] ; then
PATH=$PATH:/usr/local/bin:/Developer/Tools
export PATH
fi
export MANPATH="/usr/share/man:/usr/local/share/man:/usr/X11R6/man"



[ Reply to This | # ]
Fix missing man pages for self-installed utilities
Authored by: jacobolus on Mar 07, '06 12:21:35AM
~/.MacOSX/environment.plist is really the best way. It will set any environment variables for all programs that are launched, so you will never need to worry about wonkyness if you use a different shell sometime, etc. More information can be found at developer.apple.com.

[ Reply to This | # ]
Fix missing man pages for self-installed utilities
Authored by: baltwo on Mar 07, '06 11:55:56PM

That 4 1/2 year old document is less than helpful and most users wouldn't know about it. Do you want an exercise in futility? If so, try to find the list of envrionmental variables one can set in OS X and what are appropriate values. IMHO, this is one of OS X's weak points, especially for a Unix-based OS.



[ Reply to This | # ]