Make manpages work

[asmeurer]

No description provided.

[jzwinck]

What does this ticket mean? Does it mean making man foo show me the manpage for the version of foo installed in my current Conda environment?

If that's what this is asking for, is it as simple as setting MANPATH=$CONDA_PREFIX/share/man?

[asmeurer]

I believe that's what it was. It would be nice to not require setting an environment variable, but I couldn't figure out a way to do it.

[jzwinck]

Maybe another way would be to create a script $CONDA_PREFIX/bin/man which sets the variable and launches the regular man. I'm not sure that's better in any way though.

[asmeurer]

Yeah, that would work. Another way is to build a custom man that searches the environment manpath by default as a conda package. The script bin/man would be the simplest. What would be the best way to ship it? As a simple man package? Or maybe just as part of conda?

The advantage of not requiring an environment variable is that it "just works". No need to source the activate script or put something in your bash profile.

[jzwinck]

There are two types of users, I think:

• People who only ever use the "root" environment already need to add to their $PATH to make it work without source activate. These people currently need to add to their $MANPATH too. This could be solved either by documentation (when adding to $PATH, add to $MANPATH), or by including a man wrapper script in the root environment when Conda is installed.
• People who use non-root environments. These people do source activate already, so having it set their environment variable appropriately seems like a good solution. This would make their installation do the right thing even if they choose to use Conda to install an actual package that reads man pages (unlikely but possible).

[alexhsamuel]

I think man already provides the required functionality... almost. It's only vaguely specified in man's own man page:

       In addition, for each directory in the command search path (we'll  call
       it  a  "command  directory")  for  which  you do not have a MANPATH_MAP
       statement, man automatically looks for a manual page directory "nearby"
       namely as a subdirectory in the command directory itself or in the par-
       ent directory of the command directory.

On OS/X and some Python distros (Ubuntu 16), if a conda $PREFIX/bin/ directory is in my $PATH, man seems to look in $PREFIX/share/man/ automatically. On other Linux distros (RHEL 6), it seems to look in $PREFIX/man/. Apparently conda packages typically install man pages to the former, so things seem to Just Work™ on OS/X but not some Linuxes. The easiest fix might be to create a symlink to $PREFIX/share/man at $PREFIX/man on Linux, though I suppose this would break any packages that actually installed things there.

[asmeurer]

I somehow missed that MANPATH_MAP thing. So if it just works without setting any environment variables, conda should install manpages for itself. The code to generate them is already there in conda-docs (it's a side effect of the way these pages are generated). It does rely on help2man, which is still (as far as I know) still only in my anaconda.org channel, so you'd want to fix conda/conda-docs#340 first (build a Continuum and/or conda-forge package for it).

IIRC, a symlink on Linux shouldn't be a big deal because conda writes through symlinks, so any package that has files in man/ would be installed to share/man/ just fine (please correct me if this is wrong).

[alexhsamuel]

Isn't the issue here broader than just conda's own man pages? Tons of conda packages contain man pages of their own; they should become available when those packages are installed in the active environment.

[jakirkham]

It might already be doing the right thing as @jzwinck points out because man seems to be pretty smart about searching. For example, I have xz in my current conda environment. If I run man -d xz, gob of info comes out (most of it specific to my setup). However, this snippet at the end looks promising.

not executing command:
  (cd '/zopt/conda2/envs/nanshenv/share/man' && (echo ".ll 14.1i"; echo ".nr LL 14.1i"; /bin/cat '/zopt/conda2/envs/nanshenv/share/man/man1/xz.1') | /usr/bin/tbl | /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c | (/usr/bin/less -is || true))

In other words, it found the man file for xz in my environment ( /zopt/conda2/envs/nanshenv ) and would normally show this file ( /zopt/conda2/envs/nanshenv/share/man/man1/xz.1 ) with less (if I wasn't in debug mode).

In short, maybe this should be closed as it already works?

[jakirkham]

cc @scopatz (figured you might find this interesting)

[asmeurer]

The other issue here is to ship conda's manpages with conda.

[alexhsamuel]

@jakirkham, please see my comment above. It already works on some platforms but not others, depending on how the system's man is configured.

[asmeurer]

If man isn't configured properly there isn't much conda can do, unless they want to ship their own man package. Setting environment variables automatically is finicky at best (you have to activate an environment). I think the best thing for conda to do would be to add documentation on how to configure it properly if it isn't.

[jzwinck]

@asmeurer That isn't my view. I think people who use multiple environments are told to use source activate and that should reliably give them the man pages for their chosen environment. There doesn't need to be a document for each user to find individually--Conda is already asking them to do something special so that Conda can set environment variables.

I'm not familiar with the MANPATH_MAP feature discussed above, but it looks relevant. Otherwise this could be fixed by one of the approaches I mentioned.

I don't think claiming that "man is not configured properly" on mega-popular distros like Ubuntu 14.04 or RHEL6 is going to help most Conda users.

[asmeurer]

@jzwinck this is about the manpages for conda itself. No activate commands are required to use conda. Most conda users, probably even most conda users who are advanced enough to use man, use environments regularly. I personally never run activate in at least 90% of my terminal sessions, meaning any environment variable that only gets set by sourcing activate at least once would never be set for me.

[jakirkham]

Am in a similar boat as well. Something in activation does something screwy on our cluster, which effects users trying to start NoMachine. So we have to limp along on environment variables alone.

[jzwinck]

@asmeurer Your comment to me on 22 Aug 2016 said that this issue is about manpages for foo where foo is something installed in the Conda environment. Now you're saying it's about man conda?

I am confused about what this issue is for. What I personally am interested in is having man foo display the correct manual for foo if foo is installed in the currently activated environment.

[asmeurer]

I think it's for both. Maybe it should be split. The original motivation was for manpages for conda itself.

[asmeurer]

Looked at this a little more. MANPATH_MAP seems a no-go, because you have to write it to the man configuration file, which (at least on my Mac) requires sudo permissions. Unless I missed some user-writable config file.

man supposedly looks in "nearby" directories (from man man):

In addition, for each directory in the command search path (we'll call it a "command directory") for which you do not have a MANPATH_MAP statement, man automatically looks for a manual page directory "nearby" namely as a subdirectory in the command directory itself or in the parent directory of the command directory.

But I couldn't get it to work at all. Anyone know what I might be doing wrong here? I don't have NOAUTOPATH set in my man.conf.

Setting MANPATH in activate would work #5654. I really hate making activate required for environments, but I think this actually makes sense, from the man manpage:

Thus, with the proper use of MANPATH_MAP, when you issue the command man xyz, you get a manual page for the program that would run if you issued the command xyz.

So man is supposed to work based off the PATH.

Another option would be to ship a conda package for man with some sort of patch applied that automatically modifies MANPATH_MAP for conda environments to point to <env>/share/man.

[jakirkham]

Whatever solution gets picked, it would be really important to make sure this didn't somehow mess up the user's ability to search through standard system locations as well. The last thing we want is a user to run something like man chmod and it to come back empty (or with an error) just because there is no chmod in the environment.

[asmeurer]

Hmm, apparently MANPATH overrides the search path (instead of prepending like PYTHONPATH). But apparently man --path prints the default path, so if setting the MANPATH is implemented, it would need to be set to PATH_TO_CONDA_ENV/share/man:<output of man --path>.

[asmeurer]

So I found out why my "nearby" wasn't working. Apparently my MANPATH was already set (thanks Fink). If I unset it, it actually works out of the box:

$ man --path
/Users/aaronmeurer/anaconda3/share/man:/Users/aaronmeurer/anaconda/envs/hunspell/share/man:/Users/aaronmeurer/anaconda/envs/emacs/share/man:/sw/share/man:/usr/local/texlive/2016/bin/x86_64-darwin/man:/usr/local/share/man:/usr/share/man:/opt/X11/share/man:/Library/Frameworks/Maple.framework/Versions/Current/man:/Library/Frameworks/Python.framework/Versions/2.7/share/man:/Library/Frameworks/Python.framework/Versions/2.6/share/man:/Library/Frameworks/Python.framework/Versions/2.5/share/man:/Library/Frameworks/Python.framework/Versions/3.0/share/man:/Library/Frameworks/Python.framework/Versions/3.2/share/man:/Applications/Xcode.app/Contents/Developer/usr/share/man:/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/man

(yes I have a lot of garbage on my PATH, but the important thing is it found /Users/aaronmeurer/anaconda3/share/man from the /Users/aaronmeurer/anaconda3/bin on the front of my PATH)

Can others confirm that this works? If so, then this already works out of the box, and if it doesn't, then the solution is "go unset MANPATH" (similar to "go unset PYTHONPATH" or "go unset PYTHONHOME" advice for Python related problems).

[janxkoci]

On my Ubuntu 18.04 man pages for conda packages don't work, my man --path says:
/home/jena/miniconda3/man:/usr/share/man:/usr/local/man:/usr/local/share/man

So it searches in $CONDA_PREFIX/man instead of $CONDA_PREFIX/share/man

What is the recommended way to make this work? I also have some gentoo HPCs with conda, would be great to have them working too..

[jvhaarst]

To me it looks like man is broken on Ubuntu 18.04.1, so this isn't conda's fault.

To reproduce:

Do a man -d for a command, and see that it tries to look for man subdirectories:

path directory /home/haars001/miniconda2/envs/isoseq/bin is not in the config file
and doesn't have ../man, man, ../share/man, or share/man subdirectories

But:

ls /home/haars001/miniconda2/envs/isoseq/bin/../man
man1  man3
ls /home/haars001/miniconda2/envs/isoseq/bin/../share/man
man1  man3  man5  man7  man8

Somehow I can't imagine that something as old and basic as man-db will have a bug like this, the code that is doing the lookup is 17 years old..
But I'll file a bugreport, and see what happens.

[vilhelmen]

I'm running conda 4.5.12 out of an Ubuntu 18.04.1 container and I'm seeing the ../man path being picked up by mandb, but not the ../share/man path. I'm not sure why we'd be getting different results @jvhaarst

Maybe mandb is giving up after finding the first match of ../man? It looks like this is the case, unless I'm reading this wrong:
https://salsa.debian.org/debian/man-db/blob/master/src/manp.c#L946

path directory /opt/conda/bin is not in the config file
but does have a ../man, man, ../share/man, or share/man subdirectory
adding /opt/conda/man to manpath

[msarahan]

At this point, almost all of the infrastructure (recipes) omits manpages from packages. It would be noble to get this to work, but I'm afraid it may be quite a lot of effort (and would require a community-led effort, as I can't see an enterprise need driving the Anaconda team's effort here).

[vilhelmen]

FWIW, I'm going to mention it to the mandb maintainer and just hardcode some manpaths and generally be irritated about it.

[vilhelmen]

Amazingly, I've already head back and there's now a fix in the master branch for man-db, though who knows if 18.04 will ever see it. The system works!

[jvhaarst]

Colin Watson (the maintainer of man-db) indeed seems to have fixed this bug.
For me it's nice that recipes that do contain man pages work in the future.

[epruesse]

@jvhaarst - do you know which version is required?

[vilhelmen]

The commit is here and looking at dates the last release was 2.8.5 which was about two weeks before, so I'd guess 2.8.6, whenever that is.

[janxkoci]

FIY this tutorial fixed it for me on HPC with CentOS (I will now test few other machines with Gentoo, OpenSUSE, and Ubuntu 18.04).

I did:

(base) [koci@head ~]$ unset MANPATH
(base) [koci@head ~]$ manpath -q
/home/users/koci/miniconda3/man:/usr/local/share/man:/usr/share/man/overrides:/usr/share/man
(base) [koci@head ~]$ export MANPATH=$(manpath -q)
(base) [koci@head ~]$ export MANPATH=${CONDA_PREFIX}/share/man:${MANPATH}

Now man pages for packages from base conda environment work as expected (I will check environments later but I assume that would be separate issue anyway).

Update: So on CentOS and Ubuntu the command echo $MANPATH gave empty string, so I had to issue both the export ... commands as above, while Gentoo and OpenSUSE had already some $MANPATH set, so I just appended it using only the last command above.

[beeankha]

Closing this as a duplicate of #642

[janxkoci]

@beeankha I don't really agree that the linked issue is a duplicate of this one, however I just tested man pages for programs I installed with conda and they were working without me doing any fixing. So the original issue from this thread was probably already resolved anyway...

Edit: I tested it on my laptop with elementary OS 6.1 (based on Ubuntu 20.04). In the past, Ubuntu would need the full fix I mentioned above.

[beeankha]

Gotcha, thank you for the clarification, @janxkoci , and sorry about mislabeling this issue as a duplicate!