Why does "User Contributed Perl Documentation" show up when I look for 'man' pages

Question

When I

man -f <some string>

in addition to the expected Unix man pages, I get a bunch of odd looking entries that all have the header "User Contributed Perl Documentation". For example

man -f ip

in addition to things like

ip(4)            - Internet Protocol
ip2cc(1)         - lookup country from IP address or hostname
ipconfig(8)      - view and control IP configuration state
...

also lists things like

IP::Authority(3pm)       - fast lookup of authority by IP address
IP::Country(3pm)         - fast lookup of country codes from IP addresses
IP::Country::Fast(3pm)   - fast lookup of country codes by IP address
IP::Country::MaxMind(3pm) - Look up country by IP Address
IP::Country::Medium(3pm) - cached lookup of country codes by IP address and domain name

all of which are idenfified as "User Contributed Perl Documentation".

My 'man' path (from man --path), on OS X 10.8.2 is

/usr/local/git/share/man:/usr/share/man:/usr/local/share/man:/opt/X11/share/man:/usr/texbin/man

which is the same as it is on other machines that don't show these additional pages.

Where are these coming from? Can I limit my results to only Unix shell pages by default?

Answer 1

Perl encourages library authors to include documentation in pod format in each source file. This documentation can be translater automatically to other formats including man pages, and many systems provide the documentation of installed Perl modules as man pages.

Man pages of Perl modules are in section 3pm. You can skip the whole of section 3 (library functions of any language) by passing the -S option to man and specifying a value that doesn't include 3, e.g.

man -S 1:8:4:5:6:7 foo

Setting the MANSECT environment variable has the same effect. I don't think there's a way to exclude section 3pm while retaining section 3 on OSX.

Answer 2

Those are manpages for Perl modules (dead giveaway: the 3pm is section 3 (library functions), *P*erl *M*odule), most of which are user-contributed to Perl (look at CPAN), together with their documentation.