[OS X TeX] MANPATH, MANPATH_MAP and i-Packages

[Bruno Voisin]

I think this issue has already been raised, but I'm not quite sure  
what the answer/solution was.

The search for man pages has become more complicated in Tiger than it  
used to be. MANPATH is now defined in /usr/share/misc/man.conf,  
through a combination of several mechanisms:

- A few MANPATH entries are defined statically for all executables:

> # Every automatically generated MANPATH includes these fields
> #
> MANPATH /usr/share/man
> MANPATH	/usr/local/share/man
> MANPATH	/usr/X11R6/man

- The man page for any executable inside /dir/bin is searched  
automagically inside /dir/man:

> # If people ask for "man foo" and have "/dir/bin/foo" in their PATH
> # and the docs are found in "/dir/man", then no mapping is required.

- That is, except when an explicit MANPATH_MAP entry defines the  
relation an executable directory and a man page directory:

> # The below mappings are superfluous when the right hand side is
> # in the mandatory manpath already, but will keep man from statting
> # lots of other nearby files and directories.
> #
> MANPATH_MAP	/bin			/usr/share/man
> MANPATH_MAP	/sbin			/usr/share/man
> MANPATH_MAP	/usr/bin		/usr/share/man
> MANPATH_MAP	/usr/sbin		/usr/share/man
> MANPATH_MAP	/usr/local/bin		/usr/local/share/man
> MANPATH_MAP	/usr/local/sbin		/usr/local/share/man
> MANPATH_MAP	/usr/X11R6/bin		/usr/X11R6/man
> MANPATH_MAP	/usr/bin/X11		/usr/X11R6/man
> MANPATH_MAP	/usr/bin/mh		/usr/share/man

In fact, when installing the TeX i-Package (and CLI activation has  
been selected) a MANPATH_MAP setting is indeed added at the end of  
man.conf, corresponding to the TeX-related binaries:

> ## TeX modifications start at Mon Aug 28 17:22:38 CEST 2006
> ## Do not remove previous line
> MANPATH_MAP	/usr/local/teTeX/bin/powerpc-apple-darwin-current	/usr/ 
> local/teTeX/man
> ## Do not remove next line
> ## teTeX modifications end at Mon Aug 28 17:22:38 CEST 2006

Problem is, the other i-Packages put their executables inside /usr/ 
local/bin and their man pages inside /usr/local/man, not /usr/local/ 
share/man as expected by man.conf. Hence, the man pages are not  
found. I realized this when trying "man tiff2ps", where /usr/local/ 
bin/tiff2ps and /usr/local/man/man1/tiff2ps.1 had indeed been  
installed by the libtiff i-Package (aka TIFF Reference Library).

What would be the best solution:

- Comment out the offending line

> MANPATH_MAP	/usr/local/bin		/usr/local/share/man

in man.conf, so that the default association of /usr/local/bin and / 
usr/local/man is restored.

- Or create a symlink /usr/local/share/man to /usr/local/man.

- Or add a line

MANPATH 	/usr/local/man

so that /usr/local/man is included inside the search path for man  
pages for all executables.

I suspect the second solution would break in case some other  
installation (not through i-Installer) did attempt to put something  
inside /usr/local/share/man. And, regarding the third solution, I'm  
not sure whether I understood correctly how MANPATH works (ie, is it  
always taken into account, even when a MANPATH_MAP tells otherwise).

Any thoughts?

Bruno Voisin
------------------------- Info --------------------------
Mac-TeX Website: http://www.esm.psu.edu/mac-tex/
          & FAQ: http://latex.yauh.de/faq/
TeX FAQ: http://www.tex.ac.uk/faq
List Archive: http://tug.org/pipermail/macostex-archives/