/*
This module is the result of a more serious endeavour into
using mandoc as a complete replacement for man-db. Using
mandoc for viewing manual pages already kind of works by
just adding mandoc to environment.systemPackages — which
results in a lot of ugly environment clashes.
man-db and mandoc only partially implement the same interface,
so it's not just a matter of switching out the used package
in documentation.man. However, a separate module is entirely
possible and even simpler than the one for man-db.
However with generating the mandoc.db for apropos(1),
whatis(1) and -k of man(1), we hit a bump in the road:
makewhatis(8) does some sanity checking of the indexed
man pages which also includes checking that the realpath(3)
of any given man page is below the indexed directory.
This means that all man pages which are located in /nix/store
(i. e. all of them) will get skipped.
This behavior is easily patched and there is also a similar
feature intended for homebrew which could be (ab)used. While
I try to get this particular fix/feature into upstream mandoc,
the patched package and the experimental module reside in
vuizvui. When everything is sorted, I'll (hopefully) be able
to contribute this module to nixpkgs upstream as well.
Therefore this is also a user module in vuizvui despite its
non-me-specific nature — I hope this will only be temporary!
I do promise to fix your system configurations should you
use this particular module, though.
*/
{ config, lib, pkgs, ... }:
let
inherit (pkgs.vuizvui.sternenseemann)
mandoc
;
inherit (pkgs.vuizvui.profpatsch)
getBins
;
bins = getBins mandoc [ "makewhatis" ];
cfg = config.vuizvui.user.sternenseemann.documentation.mandoc;
docCfg = config.documentation;
in {
options = {
vuizvui.user.sternenseemann.documentation.mandoc = {
enable = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Whether to install the man utilities from
mandoc as well as manual
pages for installed packages from their
man outputs.
This can be used as a drop-in replacement
for documentation.man
with a few smaller differences.
'';
};
manPath = lib.mkOption {
type = with lib.types; listOf str;
default = [ "share/man" ];
example = lib.literalExample "[ \"share/man\" \"share/man/fr\" ]";
description = ''
Change the manpath, i. e. the directories where man looks
for section-specific directories of man pages.
You only need to change this setting if you want non-english
man pages or a combination of different languages. All values
must be strings that are a valid path from the target prefix
(without including it). The first value given takes priority.
'';
};
generateCaches = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Whether to generate a mandoc.db indexing
the installed man pages for apropos(1),
whatis(1) and the -k
option of man(1) using
makewhatis(8).
'';
};
};
};
config = lib.mkIf cfg.enable {
assertions = [
{
assertion = !(cfg.enable && docCfg.man.enable);
message = ''
vuizvui.user.sternenseemann.documentation.mandoc is a
replacement for documentation.man meaning they can't be
enabled at the same time.
'';
}
];
environment = {
# globally install man pages
pathsToLink = [ "/share/man" ];
extraOutputsToInstall = [ "man" ]
++ lib.optional docCfg.dev.enable "devman";
# tell mandoc about man pages
systemPackages = [ mandoc ];
etc."man.conf".text = lib.concatMapStrings
(path: "manpath /run/current-system/sw/${path}\n")
cfg.manPath;
# create mandoc.db for whatis(1), apropos(1) and man(1) -k
# TODO(sterni): remove -p for production™
extraSetup = lib.optionalString cfg.generateCaches ''
${bins.makewhatis} -p -T utf8 \
${lib.concatMapStringsSep " "
(path: "\"$out/${path}\"")
cfg.manPath}
'';
};
};
}