plenv should update MANPATH so that man pages installed in a plenv-managed Perl are found

[mjgardner]

Perl module distributions can and do install man page versions of their documentation (e.g., via cpanm's --man-pages option). But the man command won't find those installed in a plenv-managed Perl unless you manually change your MANPATH environment variable to include them (e.g., export MANPATH=~/.plenv/versions/5.34.0/man:$MANPATH). plenv ought to manage this when switching Perl versions.

[Grinnz]

This seems reasonable, in a similar way to plenv's adjustments to PATH, but there isn't precedent of local::lib doing it (probably just nobody cared enough).

[Grinnz]

Also I'm not familiar enough with man so this may be ignorance, but is changing MANPATH sufficient? don't man pages need to be indexed?

[mjgardner]

Also I'm not familiar enough with man so this may be ignorance, but is changing MANPATH sufficient? don't man pages need to be indexed?

They don't need to be; if they are (by the makewhatis utility) then man -k will search that. apropos is equivalent to man -k.

[mikkoi]

The issue is more complicated because there is no one-way access to man pages, unlike with $PATH. There are several utilities that use man pages. We can only assume they all use environment variable $MANPATH. They probably do if they are all GNU utilities. See StackExchange. But $MANPATH itself is complicated:

ENVIRONMENT
    MANPATH
        If $MANPATH is set, its value is used as the path to
        search for manual pages.

[man](https://man7.org/linux/man-pages/man1/man.1.html)

(In GNU/Linux) $MANPATH does not work like $PATH. $MANPATH overrides the default manual path which is derived from /etc/manpath.config. $MANPATH value is not prepended to the global default values.

A permanent $MANPATH change in plenv init - is not possible. We need to define $MANPATH separately for every perl environment (version). When a new perl version is built and installed, we need to create a man executable in /plenv/shims/. This would be the same as all the other shims:

#!/bin/bash
[[ -n "$PLENV_DEBUG" ]] && set -x
PLENV_ROOT='/home/<USER>/.anyenv/envs/plenv' exec '/home/<USER>/.anyenv/envs/plenv/libexec/plenv' exec "${0##*/}" "$@"

Then we need to create a man executable for every new perl version during its build and installation. This requires some logic because different systems behave differently. This is what Debian manpath man page says:

ENVIRONMENT
       MANPATH
              If  $MANPATH  is  set,  manpath displays its value rather than determining it on the fly.  If $MANPATH is
              prefixed by a colon, then the value of the variable is appended to the list determined from  the  content
              of  the configuration files.  If the colon comes at the end of the value in the variable, then the deter‐
              mined list is appended to the content of the variable.  If the value of the variable  contains  a  double
              colon (::), then the determined list is inserted in the middle of the value, between the two colons.

[manpath](https://man7.org/linux/man-pages/man1/manpath.1.html)

[mikkoi]

Plenv plugin to solve the issue: plenv-man