man: support building manual page index cache

The apropos software is useful to get a list of manpages matching a
description or to get a list of all manpages. The latter feature is
used by Emacs to get manpage completion (`M-x man`).

To have apropos working, a database of all available manpages must be
built with mandb. This is what this commits does.

A similar change was done for NixOS:
edc6a76cc0

modules/misc/news.nix

@@ -1664,6 +1664,15 @@ in
           available in menus.
         '';
       }
+
+      {
+        time = "2020-09-09T06:54:59+00:00";
+        condition = config.programs.man.enable;
+        message = ''
+          A new option 'programs.man.generateCaches' was added to
+          support the apropos command.
+        '';
+      }
     ];
   };
 }

modules/programs/man.nix

@@ -14,11 +14,59 @@ with lib;
           <literal>home.packages</literal>.
         '';
       };
+
+      generateCaches = mkOption {
+        type = types.bool;
+        default = false;
+        description = ''
+          Whether to generate the manual page index caches using
+          <citerefentry>
+            <refentrytitle>mandb</refentrytitle>
+            <manvolnum>8</manvolnum>
+          </citerefentry>. This allows searching for a page or
+          keyword using utilities like <citerefentry>
+            <refentrytitle>apropos</refentrytitle>
+            <manvolnum>1</manvolnum>
+          </citerefentry>.
+          </para><para>
+          This feature is disabled by default because it slows down
+          building. If you don't mind waiting a few more seconds when
+          Home Manager builds a new generation, you may safely enable
+          this option.
+        '';
+      };
     };
   };
 
   config = mkIf config.programs.man.enable {
     home.packages = [ pkgs.man ];
     home.extraOutputsToInstall = [ "man" ];
+
+    # This is mostly copy/pasted/adapted from NixOS' documentation.nix.
+    home.file = mkIf config.programs.man.generateCaches {
+      ".manpath".text = let
+        # Generate a directory containing installed packages' manpages.
+        manualPages = pkgs.buildEnv {
+          name = "man-paths";
+          paths = config.home.packages;
+          pathsToLink = [ "/share/man" ];
+          extraOutputsToInstall = [ "man" ];
+          ignoreCollisions = true;
+        };
+
+        # Generate a database of all manpages in ${manualPages}.
+        manualCache = pkgs.runCommandLocal "man-cache" { } ''
+          # Generate a temporary man.conf so mandb knows where to
+          # write cache files.
+          echo "MANDB_MAP ${manualPages}/share/man $out" > man.conf
+
+          # Run mandb to generate cache files:
+          ${pkgs.man-db}/bin/mandb -C man.conf --no-straycats --create \
+            ${manualPages}/share/man
+        '';
+      in ''
+        MANDB_MAP ${config.home.profileDirectory}/share/man ${manualCache}
+      '';
+    };
   };
 }

tests/default.nix

@@ -52,6 +52,7 @@ import nmt {
     ./modules/programs/kakoune
     ./modules/programs/lf
     ./modules/programs/lieer
+    ./modules/programs/man
     ./modules/programs/mbsync
     ./modules/programs/ncmpcpp
     ./modules/programs/ne

tests/modules/programs/man/apropos.nix

@@ -0,0 +1,22 @@
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+{
+  config = {
+    programs.man = {
+      enable = true;
+      generateCaches = true;
+    };
+
+    nmt.script = ''
+      assertFileExists home-files/.manpath
+
+      CACHE_DIR=$(cat $TESTED/home-files/.manpath | cut --delimiter=' ' --fields=3)
+
+      if [[ ! -f "$CACHE_DIR/index.bt" ]]; then
+          fail "Expected man cache files to exist (in $CACHE_DIR) but they were not found."
+      fi
+    '';
+  };
+}

tests/modules/programs/man/default.nix

@@ -0,0 +1,4 @@
+{
+  man-apropos = ./apropos.nix;
+  man-no-manpath = ./no-manpath.nix;
+}

tests/modules/programs/man/no-manpath.nix

@@ -0,0 +1,13 @@
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+{
+  config = {
+    programs.man = { enable = true; };
+
+    nmt.script = ''
+      assertPathNotExists home-files/.manpath
+    '';
+  };
+}