man not searching ~/.local/share/man/ for man pages

Question

On a previous install of Ubuntu 20.04, man would also search in the XDG_ home folder location in addition to the normal paths, e.g. /home/naftuli/.local/share/man/man?/*. For instance, I often installed Rust man pages via:

rsync -av ~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/share/man/man1/ \
    ~/.local/share/man/man1/

I'm now on Ubuntu 22.04 (elementary OS 7.0), I've done the same thing, yet man can't seem to find them:

$ man cargo
No manual entry for cargo

I have uploaded my /etc/manpath.config for both 20.04 and 22.04 to this Gist, and the diff does not seem significant:

diff --git a/manpath.config-20.04 b/etc/manpath.config
index a3e2255..e1747a2 100644
--- a/manpath.config-20.04
+++ b/etc/manpath.config
@@ -109,7 +109,7 @@ MANDB_MAP   /snap/man               /var/cache/man/snap
 # particular order. Sections with extensions should usually be adjacent to
 # their main section (e.g. "1 1mh 8 ...").
 #
-SECTION                1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7
+SECTION                1 n l 8 3 0 2 3posix 3pm 3perl 3am 5 4 9 6 7
 #
 #---------------------------------------------------------
 # Range of terminal widths permitted when displaying cat pages. If the
@@ -129,4 +129,4 @@ SECTION             1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7
 #---------------------------------------------------------
 # Flags.
 # NOCACHE keeps man from creating cat pages.
-#NOCACHE
\ No newline at end of file
+#NOCACHE

Is there other configuration I might be missing? I did not have to do anything special on 20.04 to have it find man pages in ~/.local/share/man.

Answer 1

I'm not exactly sure what my configuration was on my previous install, as I do not have the hardware with me at the moment, but I was able to discover a way to fix the path.

Using the MANPATH Environment Variable

As per manpath(1), the MANPATH environment variable allows a "temporary" (i.e. as long as the environment variable is set) path modification for man. The variable content follows the pattern of PATH, being colon-delimited, but also allows prepending, appending, and inserting the system man path within the hierarchy.

• To prepend an entry into the man path, have your MANPATH variable end with a colon: export MANPATH="$HOME/.local/share/man:
• To append an entry into the man path, have your MANPATH variable start with a colon: export MANPATH=":$HOME/.local/share/man
• To insert the system man path at an arbitrary point, use two colons: export MANPATH="/snap/man::$HOME/.local/share/man.

I'd personally prefer to have man look in my home directory first before looking for system man pages, so I am setting it like so in my ~/.bashrc file:

# note the colon at the end
export MANPATH="$HOME/.local/share/man:"

Using PATH to Show the Way

According to this blog post, MANPATH_MAP entries in /etc/manpath.config tell man how to find directories containing manual files relevant to a particular entry within PATH. man then uses these path relationships to find man files, and this is likely what the difference was for me in my previous install.

For example, consider the following entry:

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

What this results in is that when looking for a manual page, man will examine the relative path between the executable found in PATH and the given entry.

In my new install, I hadn't yet created ~/.local/bin, which is where I typically keep shell scripts and other local executables in my home directory. After creating this directory, and after spawning a new shell, I was able to run man cargo and have it find the manual pages in ~/.local/share/man.

It's a bit unintuitive, I probably never would have figured this out without diving very deeply into man, but it does work!