Adding directories to the MANPATH is hard.

[hugomg]

Fish treats the MANPATH environment specially and expands it into an array. This unfortunately makes it very easy to mess up the MANPATH and make all system manpages stop working.

The way MANPATH works is that like this:

• If MANPATH is unset then man will search for man pages in some default system directories, as specified in /etc/manpath.config)
• If MANPATH is a colon separated list of directories, man searches for manual pages in those directories and DOES NOT search in the default system directories

If you want to put some custom directories in the MANPATH while still having man use the system manpages then you must make sure that MANPATH either starts or ends with a colon or has a :: in the middle. From man manpath:

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  deter‐
              mined 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.

Now lets go back to Fish. Right now, the first thing that comes to mind if you want to add a directory to the MANPATH is to append it to the end of the array

set -gx MANPATH $MANPATH /my/custom/directory

But this will not have the desired result if MANPATH was not previously set! After running this command man will stop displaying the system manpages that it was displaying before. It will only display manpages from the custom directory.

In this older issue there are some proposed workarounds but none of them are ideal:

 # Put a colon in the directory name
 set -gx MANPATH $MANPATH ":/my/custom/dir"

 # Add an empty element to the array
 set -gx MANPATH $MANPATH "" "/my/custom/dir"

If MANPATH is unset, using these workarounds ensure that MANPATH starts with a colon, which is what we want. But now we will be doing the wrong thing if MANPATH did have a value beforehand! In this case, we will end up with a :: in the middle of the MANPATH, which also has a special meaning.

---

Is there any big reason for why MANPATH should be an array instead of a regular colon-separated string? Right now Fish makes it easy to iterate over MANPATH or remove paths from the MANPATH but its very hard to just append something to the MANPATH, which I suspect is a much more common thing people will want to do.

[ridiculousfish]

Thanks for the detailed explanation. Maybe we should remove MANPATH from the arrayify-whitelist

[hugomg]

A quick question: I just found out that

 set -gx MANPATH "$MANPATH:/my/custom/dir"

works fine as a workaround but if I get rid of the quotes it becomes a noop:

 set -gx MANPATH $MANPATH:/my/custom/dir

I thought fish was supposed to expand unset variables to the empty string?

---

edit: this workaround is actually broken when MANPATH has length > 1 because it will expand to a space-separated list instead of a colon-separated one.

[ridiculousfish]

See this comment for an explanation of how fish handles unset variables.

[hugomg]

One possible workaround that seems to work is to set MANPATH to an array of length 1 containing an empty string in the cases when MANPATH is previously unset because when MANPATH always has length >= 1 then doing set -gx MANPATH $MANPATH "/blah" always does the right thing.

if [ 0 -eq (count $MANPATH)]; set -gx MANPATH ""; end

[zanchey]

Annoyingly, MANPATH is platform-dependent - the double-colon trick doesn't work on BSD or OS X.

[Lucretiel]

I like @hugomg's idea, because it can be applied in-general to the colon-separation whitelist, without making MANPATH a special snowflake.

[faho]

For $PATH it's completely unnecessary - we always set that, for CDPATH my instinct is that it's more unusual to add to it, so it would still leave MANPATH as a "relatively special snowflake", especially when considering all other variables.

Plus, if I understand @zanchey's comment correctly, an empty element in our listified MANPATH doesn't actually do the same thing on BSD or OSX as it does on Linux, so this still wouldn't work.

The three solutions I can see here

• Do nothing (i.e. reject the problem)
• Always set MANPATH to the "default" value as given by manpath (assuming that's available everywhere) - i.e. set -gx MANPATH (manpath | string split ":")
• Remove MANPATH from the listify list

Of those, the second seems like it has the smallest impact.

[hugomg]

While option 2 is least impactful, is MANPATH really special to justify its inclusion in the listify list?