MANPATH not handled correctly

[Steve Kargl]

MANPATH is not handled correctly.  According to the documentation
in apropos(1) and whatis(1):

  MANPATH   The standard search path used by man(1) may be changed by
            specifying a path in the MANPATH environment variable.  Invalid
            paths, or paths without manual databases, are ignored.
            Overridden by -M.  If MANPATH begins with a colon, it is
            appended to the default list; if it ends with a colon, it is
            prepended to the default list; or if it contains two adjacent
            colons, the standard search path is inserted between the
            colons.  If none of these conditions are met, it overrides the
            standard search path.

I have a manpage named mkpic in $HOME/man/man1.  I also have the FreeBSD
installed manpages, e.g., /usr/share/man/man1/cat.1.gz.  If I have
'setenv MANPATH :$HOME/man' in my .cshrc file, then the following occurs:  

% setenv | grep MANPATH
MANPATH=:/home/kargl/man
% apropos mkpic
(Warning: MANPATH environment variable set)
mkpic(1) - construct a contour image in MIFF image format
% apropos cat
(Warning: MANPATH environment variable set)
matrix(3) - Array and matrix allocation for FFT library

So, the above description of MANPATH is incorrect as :/home/kargl/man
should have been appended to the default MANPATH.

Interestingly, manpath(1) seems to described what actually happens
(long lines wrapped):

% unsetenv MANPATH
% manpath
/home/kargl/man:/usr/local/man:/usr/share/man:/usr/share/openssl/man:\
   /usr/local/lib/perl5/site_perl/man:/usr/local/lib/perl5/5.20/perl/man:\
   /usr/local/share/xpdf/man
% setenv MANPATH :$HOME/sman
% manpath
(Warning: MANPATH environment variable set)
:/home/kargl/man

The expected result according apropos(1) and whatis(1) for last command is

% manpath
/home/kargl/man:/usr/local/man:/usr/share/man:/usr/share/openssl/man:\
   /usr/local/lib/perl5/site_perl/man:/usr/local/lib/perl5/5.20/perl/man:\
   /usr/local/share/xpdf/man:/home/kargl/man

Instead of (un)fixing the documentation for apropos(1) and whatis(1), it
would be preferable to fix manpath to match the description in those
manpages.  In addition, the Warning should be removed or at least an
option should be available to suppress the (useless/annoying) Warning.
This would restore man(1), apropros(1), and whatis(1) to its historical
behavior prior to svn revision 213317.

If the documentation for apropos(1) and whatis(1) is unfixed, then manpath(1)
should have HISTORY and BUGS sections.  The BUGS section should explicitly
not that MANPATH is no longer a changeable environmental variable by a
user without incurring the Warning.

-- 
Steve
20161221 https://www.youtube.com/watch?v=IbCHE-hONow