How to make `MANPATH=~/.nmap/doc man 1 nmap` look for nmap.1?

Question

I recently decided that since quite often I experiment with the latest version of nmap, it might be a good idea to keep its SVN checkout in ~/.nmap without installing and just run svn up; make to make it up to date. I added ~/.nmap to $PATH and just realized that with this setup, I cannot run man nmap anymore. I read up on $MANPATH and realized that this doesn't seem to work for me:

[14:51:28][~/.nmap]$ manpath                                          
manpath: warning: $MANPATH set, prepending /etc/man_db.conf
/home/d/virtualenv/share/man:/usr/local/man:/usr/local/share/man:/usr/share/man:/usr/man:/home/d/.nmap/docs/man-xlate/:/home/d/.nmap/docs
[14:51:32][~/.nmap]$ strace  man 1 nmap 2>&1 | egrep 'nmap.1|write'
stat("/home/d/.nmap/docs/zenmap.1", {st_mode=S_IFREG|0664, st_size=5943, ...}) = 0
stat("/home/d/.nmap/docs/nmap.1", {st_mode=S_IFREG|0664, st_size=183621, ...}) = 0
access("/usr/share/man/man1/nmap.1.gz", R_OK) = -1 ENOENT (No such file or directory)
write(2, "No manual entry for nmap in sect"..., 38No manual entry for nmap in section 1

Why is that and how can I fix it? I noticed that man also looks for a file named index.db in ~/.nmap/docs and cannot find it, perhaps this is a clue?

Answer 1

The problem is that the docs directory doesn't have the directory structure man requires (nmap.1 should be in a man1 subdirectory), same as when using the -M option:

    -M path, --manpath=path
          Specify an alternate manpath to use.  By default,  man  uses
          manpath  derived code to determine the path to search.  This
          option  overrides  the  $MANPATH  environment  variable  and
          causes option -m to be ignored.

          A  path  specified as a manpath must be the root of a manual
          page hierarchy structured into sections as described in  the
          man-db  manual  (under  "The  manual page system").  To view
          manual pages outside such hierarchies, see the -l option.

When using make install the manpages are installed to the correct category subdirectories. so pointing MANPATH to the docs directory directly won't work.