Asdf: What is the best practice for making man pages accessible that are installed via asdf?

[ipatch]

I've been using asdf for a little while now, and something I have noticed is that certain man pages for certain languages / tools aren't accessible after installing such language, i.e. elixir for example.

Presently I am using asdf v0.4.0 on macOS 10.12.6 and macOS does a little trickery to get the man pages loaded. For one, if a MANPATH environment variable is set the paths specified in /private/etc/man.conf are no longer searchable.

What does this mean? I.e. if I install the homebrew version of git it's manual / man page will become accessible via man git. However if I add say $HOME/.asdf/installs/elixir/1.5.2/man to an environment variable called MANPATH then I can no longer access the man page for git using the command man git.

The trivial solution that I have come up with is to symlink the $USER specific man pages for various languages I have installed via asdf to /usr/local/share/man which then makes them accessible, and I can run man elixir and man git.

However when I installed python 3.6.3 via asdf it was intelligent enough to add the man pages from my locally installed python and link them to the proper path. I have no idea how python set this up, is it something specific to python or something specific to the asdf-python version?

[Stratus3D]

@ipatch I'm not actually sure what the state of asdf-python is when it comes to man pages, but it sounds like it's doing the right thing. This is something that all asdf plugins should do. We need to figure out what should be done, and then make the necessary changes to asdf and/or the plugin creation guide.

[ipatch]

Spent a little time messing around with man pages this evening on macOS and something I noticed is that if there is a /path/to/super/fancy/bin and /path/to/super/fancy/man then man should be able to pick up on the man page contained in the /path/to/super/fancy/man directory. A good use for this explanation is installing GNU Coreutils with homebrew, and it will install man pages in a non standard path. This is useful for the fact that asdf can setup man pages for binaries contained within the ~/.asdf/bin. Haven't tested this on other systems yet, but this setup works well on macOS without having to fiddle with system setting files.

[ipatch]

Got to spend some more time working with man pages on macOS, and it appears macOS may actually be able to honor the $MANPATH env var if set properly. However, something I have noticed is that if man pages are placed in certain directories then macOS will dynamically update the search path for man pages, which is quite handy when you know how it works. 👍

That said, personally 🙋‍♂️ I'd avoid fiddling with the $MANPATH env var because I don't know how portable it would be across various environments, ie. shells, and terminals, and also systems, ie. Linux, Darwin, etc etc.

So going back to the beginning of this circle _bare with me_ I primarily use asdf for erlang, elixir, ocaml, and ruby. Personally, I have migrated away from using asdf to manage Node.js runtimes, and Python environments with other version manager tools. So when I still need to work with erlang and elixir it's quite nice to pop open a man page to figure some stuff out, which is something I haven't been able to do when installing erlang or elixir via asdf.

So from hacking away at man pages this morning, I came to the conclusion that when I install elixir on macOS there are indeed man pages located in the install dir path;

👇path to where asdf installs precompiled language files for elixir on my macOS box.

/opt/Code/github/public/version-managers/asdf/installs/elixir/[MAJOR.MINOR.PATCH]

add whatever major minor and patch version of elixir is installed on the system, for my use case it would be 1.7.4. The "stock" contents of a elixir 1.7.4 install on my box looks like,

╰─λ pwd                                                                                       
/opt/Code/github/public/version-managers/asdf/installs/elixir/1.7.4

╰─λ l                                                                                         
total 44K
drwxr-xr-x 11 capin staff  352 Nov  4 12:18 ./
drwxr-xr-x  3 capin staff   96 Nov  4 12:18 ../
drwxr-xr-x  3 capin staff   96 Nov  4 12:18 .mix/
drwxr-xr-x 11 capin staff  352 Oct 25 03:40 bin/
drwxr-xr-x  8 capin staff  256 Nov  4 12:18 lib/
drwxr-xr-x  9 capin staff  288 Oct 25 03:41 man/
-rw-r--r--  1 capin staff  15K Oct 25 03:40 CHANGELOG.md
-rw-r--r--  1 capin staff  12K Oct 25 03:40 LICENSE
-rw-r--r--  1 capin staff  825 Oct 25 03:40 NOTICE
-rw-r--r--  1 capin staff 7.3K Oct 25 03:40 README.md
-rw-r--r--  1 capin staff    5 Oct 25 03:40 VERSION

and the first thing pops out to me is the man directory. There are in fact a couple of man pages within that directory that are useful for working with mix, iex, and elixir commands from a shell. However, with a stock install of asdf on macOS, /usr/bin/man is unable to locate those man pages in the directory listed above. However, extending from my previous comments, if I run

man -d iex

I'll see something like, towards the end / bottom of STDOUT

OUTPUT

No manual entry for iex

However v2, if I remove /path/to/asdf/shims and /path/to/asdf/bin from $PATH and add /opt/Code/github/public/version-managers/asdf/installs/elixir/1.7.4/bin to my $PATH, and verify the above path to the elixir bins are indeed in my $PATH

echo $PATH

The above should output the newly added bin directory where asdf installed the elixir bins, not the symlinked shell scripts that reside in the shims directory. Now I can execute,

man -d iex

and notice how macOS uses manpath mappings to locate certain man pages for binaries located in various paths throughout the system. So noticing that, and doing a little troubleshooting, ie. trial & error I came to the conclusion if I add a share/man/man1 directory in within the elixir install path, ie.

/opt/Code/github/public/version-managers/asdf/installs/elixir/[MAJOR.MINOR.PATCH]/share/man/man1

and then run

man -d iex

I get something like the below;

OUTPUT

not executing command:
  (cd '/opt/Code/github/public/version-managers/asdf/installs/elixir/1.7.4/share/man' && (echo ".ll 11.2i"; echo ".nr LL 11.2i"; /bin/cat '/opt/Code/github/public/version-managers/asdf/installs/elixir/1.7.4/share/man/man1/iex.1') | /usr/bin/tbl | /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c | (/usr/bin/less -is || true))

now that macOS has mapped /path/to/asdf/install/elixir/version/share/man/man1

I can read the man page for iex from within any directory on my system without having to explicitly set the path to the man page, and I did not need to fiddle with any super user; ie. root owned files on the system for man page configuration. So all in all I made some progress with understanding how man pages work on macOS. However v3, this isn't a permanent solution but rather an explanation of what is going on with man pages on macOS, and hopefully begins a dialogue of how we should get asdf to read man pages from languages, runtimes, various other utilities asdf manages.

cheers 🍻
Chris

[Stratus3D]

Wow! Thanks for taking the time to document all that. That sounds promising. I guess we need to figure out if this is something OSX specific or if this is behavior baked into man. If it's something in man itself that does this is there any reason we shouldn't add /share/man/man1 to each version?

[ipatch]

Wow! Thanks for taking the time to document all that. That sounds promising. I guess we need to figure out if this is something OSX specific or if this is behavior baked into man. If it's something in man itself that does this is there any reason we shouldn't add /share/man/man1 to each version?

Yeah man, when I get some more free time, I explore things on a Debian 9.x box I have access to, and see if the same things apply, just not quite sure when this will happen, will post updates in this issue.

cheers
Chris

[maristgeek]

FWIW, MANPATH generally gets respected in Ubuntu and Fedora