cafkafk/nixpkgs
cafkafk/nixpkgs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
nixpkgs/nixos/modules/misc/mandoc.nix

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

197 lines
8.4 KiB
Nix
Raw Normal View History

nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
{ config, lib, pkgs, ... }:
let
nixos/mandoc: add package option
2021-10-02 15:28:48 +02:00
makewhatis = "${lib.getBin cfg.package}/bin/makewhatis";
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
cfg = config.documentation.man.mandoc;
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
toMandocOutput = output: (
lib.mapAttrsToList
(
name: value:
if lib.isString value || lib.isPath value then "output ${name} ${value}"
else if lib.isInt value then "output ${name} ${builtins.toString value}"
else if lib.isBool value then lib.optionalString value "output ${name}"
else if value == null then ""
else throw "Unrecognized value type ${builtins.typeOf value} of key ${name} in mandoc output settings"
)
output
);
nixos/mandoc: fix paths don't exist failure
2023-08-03 08:48:29 +02:00
in
{
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
meta.maintainers = [ lib.maintainers.sternenseemann ];
options = {
documentation.man.mandoc = {
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
enable = lib.mkEnableOption "mandoc as the default man page viewer";
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
manPath = lib.mkOption {
type = with lib.types; listOf str;
default = [ "share/man" ];
example = lib.literalExpression "[ \"share/man\" \"share/man/fr\" ]";
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
description = ''
Change the paths included in the MANPATH environment variable,
nixos/mandoc: use MANPATH environment variable
2023-08-03 08:52:10 +02:00
i. e. the directories where {manpage}`man(1)`
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
looks for section-specific directories of man pages.
You only need to change this setting if you want extra man pages
(e. g. in non-english languages). All values must be strings that
are a valid path from the target prefix (without including it).
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
The first value given takes priority. Note that this will not
add manpath directives to {manpage}`man.conf(5)`.
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
'';
};
nixos/mandoc: add package option
2021-10-02 15:28:48 +02:00
package = lib.mkOption {
type = lib.types.package;
default = pkgs.mandoc;
defaultText = lib.literalExpression "pkgs.mandoc";
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
description = ''
nixos/misc: invariant option docs MD conversions
2022-07-20 12:32:04 +02:00
The `mandoc` derivation to use. Useful to override
nixos/mandoc: add package option
2021-10-02 15:28:48 +02:00
configuration options used for the package.
'';
};
nixos/mandoc: use MANPATH environment variable
2023-08-03 08:52:10 +02:00
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
settings = lib.mkOption {
description = "Configuration for {manpage}`man.conf(5)`";
default = { };
type = lib.types.submodule {
options = {
manpath = lib.mkOption {
type = with lib.types; listOf str;
default = [ ];
example = lib.literalExpression "[ \"/run/current-system/sw/share/man\" ]";
description = ''
Override the default search path for {manpage}`man(1)`,
{manpage}`apropos(1)`, and {manpage}`makewhatis(8)`. It can be
used multiple times to specify multiple paths, with the order
determining the manual page search order.
This is not recommended in favor of
{option}`documentation.man.mandoc.manPath`, but if it's needed to
specify the manpath in this way, set
{option}`documentation.man.mandoc.manPath` to an empty list (`[]`).
'';
};
output.fragment = lib.mkEnableOption ''
Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
elements and only emit the subtree below the <body> element in HTML
output of {manpage}`mandoc(1)`. The style argument will be ignored.
This is useful when embedding manual content within existing documents.
'';
output.includes = lib.mkOption {
type = with lib.types; nullOr str;
default = null;
example = lib.literalExpression "../src/%I.html";
description = ''
A string of relative path used as a template for the output path of
linked header files (usually via the In macro) in HTML output.
Instances of `%I` are replaced with the include filename. The
default is not to present a hyperlink.
'';
};
output.indent = lib.mkOption {
type = with lib.types; nullOr int;
default = null;
description = ''
Number of blank characters at the left margin for normal text,
default of `5` for {manpage}`mdoc(7)` and `7` for
{manpage}`man(7)`. Increasing this is not recommended; it may
result in degraded formatting, for example overfull lines or ugly
line breaks. When output is to a pager on a terminal that is less
than 66 columns wide, the default is reduced to three columns.
'';
};
output.man = lib.mkOption {
type = with lib.types; nullOr str;
default = null;
example = lib.literalExpression "../html%S/%N.%S.html";
description = ''
A template for linked manuals (usually via the Xr macro) in HTML
output. Instances of ‘%N’ and ‘%S’ are replaced with the linked
manual's name and section, respectively. If no section is included,
section 1 is assumed. The default is not to present a hyperlink.
If two formats are given and a file %N.%S exists in the current
directory, the first format is used; otherwise, the second format is used.
'';
};
output.paper = lib.mkOption {
type = with lib.types; nullOr str;
default = null;
description = ''
This option is for generating PostScript and PDF output. The paper
size name may be one of `a3`, `a4`, `a5`, `legal`, or `letter`.
You may also manually specify dimensions as `NNxNN`, width by
height in millimetres. If an unknown value is encountered, letter
is used. Output pages default to letter sized and are rendered in
the Times font family, 11-point. Margins are calculated as 1/9 the
page length and width. Line-height is 1.4m.
'';
};
output.style = lib.mkOption {
type = with lib.types; nullOr path;
default = null;
description = ''
Path to the file used for an external style-sheet. This must be a
valid absolute or relative URI.
'';
};
output.toc = lib.mkEnableOption ''
In HTML output of {manpage}`mandoc(1)`, If an input file contains
at least two non-standard sections, print a table of contents near
the beginning of the output.
'';
output.width = lib.mkOption {
type = with lib.types; nullOr int;
default = null;
description = ''
The ASCII and UTF-8 output width, default is `78`. When output is a
pager on a terminal that is less than 79 columns wide, the
default is reduced to one less than the terminal width. In any case,
lines that are output in literal mode are never wrapped and may
exceed the output width.
'';
};
};
};
};
nixos/mandoc: use MANPATH environment variable
2023-08-03 08:52:10 +02:00
extraConfig = lib.mkOption {
type = lib.types.lines;
default = "";
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
description = ''
Extra configuration to write to {manpage}`man.conf(5)`.
nixos/mandoc: use MANPATH environment variable
2023-08-03 08:52:10 +02:00
'';
};
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
};
};
config = lib.mkIf cfg.enable {
environment = {
nixos/mandoc: add package option
2021-10-02 15:28:48 +02:00
systemPackages = [ cfg.package ];
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
etc."man.conf".text = lib.concatStringsSep "\n" (
(map (path: "manpath ${path}") cfg.settings.manpath)
++ (toMandocOutput cfg.settings.output)
++ [ cfg.extraConfig ]
);
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
# create mandoc.db for whatis(1), apropos(1) and man(1) -k
# TODO(@sternenseemman): fix symlinked directories not getting indexed,
# see: https://inbox.vuxu.org/mandoc-tech/20210906171231.GF83680@athene.usta.de/T/#e85f773c1781e3fef85562b2794f9cad7b2909a3c
extraSetup = lib.mkIf config.documentation.man.generateCaches ''
nixos/mandoc: add man.conf settings option
2023-08-04 21:03:46 +02:00
for man_path in ${
lib.concatMapStringsSep " " (path:
"$out/" + lib.escapeShellArg path
) cfg.manPath} ${lib.concatMapStringsSep " " (path:
lib.escapeShellArg path) cfg.settings.manpath
}
nixos/mandoc: fix paths don't exist failure
2023-08-03 08:48:29 +02:00
do
[[ -d "$man_path" ]] && ${makewhatis} -T utf8 $man_path
done
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
'';
nixos/mandoc: use MANPATH environment variable
2023-08-03 08:52:10 +02:00
# tell mandoc the paths containing man pages
nixos/mandoc: don't create leading double slashes in MANPATH
2023-12-24 18:39:37 +01:00
profileRelativeSessionVariables."MANPATH" = map (path: if builtins.substring 0 1 path != "/" then "/${path}" else path) cfg.manPath;
nixos/mandoc: init Adds a NixOS module which allows using mandoc as the main manual viewer. It can be used as a drop-in replacement for documentation.man which relies on GNU's man-db and provides more or less the same features. The generateCaches option requires a different implementation for mandoc, so it is hard to share code between the two modules -- hence it has been implemented separately. Using both at the same time makes little sense and wouldn't quite work, so there's an assertion to prevent it. To make makewhatis(8) index manual pages which are symlinks to the nix store, we need to set READ_ALLOWED_PATH to include `builtins.storeDir`. For background and discussion see: https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
2021-09-19 19:51:03 +02:00
};
};
}
Reference in a new issue Copy permalink