Why "man" doesn't list manuals in ~/.guix-profile/share/man and ~/.guix-home/profile/share/man?

Why "man" doesn't list manuals in ~/.guix-profile/share/man and ~/.guix-home/profile/share/man?

[Rodrigo Morales]

* The problem

I've installed =git= in my system through =guix home=.

#+HEADER: :prologue "exec 2>&1"
#+HEADER: :epilogue ":"
#+HEADER: :dir ~/source-code/emacs
#+BEGIN_SRC sh
git --version
which git
#+END_SRC

#+RESULTS:
#+begin_example
git version 2.41.0
/home/rdrg/.guix-home/profile/bin/git
#+end_example

I can read the man page of =git=

#+BEGIN_SRC sh
man git | head -n 10
#+END_SRC

#+RESULTS:
#+begin_example
GIT(1)                            Git Manual                            GIT(1)

NAME
       git - the stupid content tracker

SYNOPSIS
       git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
#+end_example

However, when I search for the man page for =git=, I only find the man
page for =guix-git=.

#+BEGIN_SRC sh
man -k 'git'
#+END_SRC

#+RESULTS:
#+begin_example
guix-git (1)         - manual page for guix git (GNU Guix) 1.4.0-10.4dfdd82
#+end_example

The man page =guix-git= is different to that of =git=.

#+BEGIN_SRC sh
man guix-git  | head -n 10
#+END_SRC

#+RESULTS:
#+begin_example
GUIX(1)                          User Commands                         GUIX(1)

NAME
       guix - manual page for guix git (GNU Guix) 1.4.0-10.4dfdd82

SYNOPSIS
       guix git COMMAND ARGS...

DESCRIPTION
       Operate on Git repositories.
#+end_example

Because I installed =git= through =guix home=, the manual page exists
in ~/.guix-home/profile/share/man/man1/git.gz (please see proof below)

#+BEGIN_SRC sh
find ~/.guix-profile/share/man ~/.guix-home/profile/share/man
-wholename '*/git\.*'
#+END_SRC

#+RESULTS:
#+begin_example
/home/rdrg/.guix-home/profile/share/man/man1/git.1.gz
#+end_example

The problem is that, =man -k= is not able to find the manual page of =git=.

* Environmental variable =MANPATH=

In my system, ...

... =man= is able to find a total of 1748 manual pages.

#+HEADER: :prologue "exec 2>&1"
#+HEADER: :epilogue ":"
#+BEGIN_SRC sh
man -k '' | wc -l
#+END_SRC

#+RESULTS:
#+begin_example
1748
#+end_example

... the variable =MANPATH= contains three paths.

#+BEGIN_SRC sh
echo "$MANPATH" | tr ':' '\n' | sort -u
#+END_SRC

#+RESULTS:
#+begin_example
/home/rdrg/.guix-home/profile/share/man
/home/rdrg/.guix-profile/share/man
/run/current-system/profile/share/man
#+end_example

... when I set =MANPATH= to the third path shown above, =man= finds
1748 man pages. Note that this number is equal to the number that was
shown when =MANPATH= is not modified, this indicates that all manual
pages are coming from this directory.

#+HEADER: :prologue "exec 2>&1"
#+HEADER: :epilogue ":"
#+BEGIN_SRC sh
export MANPATH="/run/current-system/profile/share/man"
man -k '' | wc -l
#+END_SRC

#+RESULTS:
#+begin_example
1748
#+end_example

... when I set =MANPATH= to the first path shown above, =man= finds 0 pages.

#+HEADER: :prologue "exec 2>&1"
#+HEADER: :epilogue ":"
#+BEGIN_SRC sh
export MANPATH="/home/rdrg/.guix-home/profile/share/man"
man -k '' | wc -l
#+END_SRC

#+RESULTS:
#+begin_example
: nothing appropriate.
0
#+end_example

... when I set =MANPATH= to the second path shown above, =man= finds 0 pages.

#+HEADER: :prologue "exec 2>&1"
#+HEADER: :epilogue ":"
#+BEGIN_SRC sh
export MANPATH="/home/rdrg/.guix-profile/share/man"
man -k '' | wc -l
#+END_SRC

#+RESULTS:
#+begin_example
: nothing appropriate.
0
#+end_example

From this I conclude that =man= is only listing pages that exist in
=/run/current-system/profile/share/man=, but is not searching manual
pages in the other two directories.

* The question

Why, in my system, =man= pages in ~/.guix-home/profile/share/man
aren't shown when searching through =man -k=?

* Additional context

In Emacs, I usually use the command =man= and I wanted to open the man
page for =git-show=, but it was not being listed. I looked at the
function definition and noticed that the completion list of the
command was built by repeatedly executing =man -k {{string}}= (see the
definition of the Emacs function Man-completion-table).

Why "man" doesn't list manuals in ~/.guix-profile/share/man and ~/.guix-home/profile/share/man?

[nathan via]

* The solution

install man-db into your home profile

* The explanation

mandb -k and whatis use a database of cached info called index.something. multiple databases can be loaded and MANPATH can be used to find them.
index.db is only created if man-db is in profile. (guix/guix/profiles.scm, manual-database/optional procedure)