this converts meta.doc into an md pointer, not an xml pointer. since we
no longer need xml for manual chapters we can also remove support for
manual chapters from md-to-db.sh
since pandoc converts smart quotes to docbook quote elements and our
nixos-render-docs does not we lose this distinction in the rendered
output. that's probably not that bad, our stylesheet didn't make use of
this anyway (and pre-23.05 versions of the chapters didn't use quote
elements either).
also updates the nixpkgs manual to clarify that option docs support all
extensions (although it doesn't support headings at all, so heading
anchors don't work by extension).
the conversion procedure is simple:
- find all things that look like options, ie calls to either `mkOption`
or `lib.mkOption` that take an attrset. remember the attrset as the
option
- for all options, find a `description` attribute who's value is not a
call to `mdDoc` or `lib.mdDoc`
- textually convert the entire value of the attribute to MD with a few
simple regexes (the set from mdize-module.sh)
- if the change produced a change in the manual output, discard
- if the change kept the manual unchanged, add some text to the
description to make sure we've actually found an option. if the
manual changes this time, keep the converted description
this procedure converts 80% of nixos options to markdown. around 2000
options remain to be inspected, but most of those fail the "does not
change the manual output check": currently the MD conversion process
does not faithfully convert docbook tags like <code> and <package>, so
any option using such tags will not be converted at all.
A centralized list for these renames is not good because:
- It breaks disabledModules for modules that have a rename defined
- Adding/removing renames for a module means having to find them in the
central file
- Merge conflicts due to multiple people editing the central file
In the last year `programs.oh-my-zsh` gained more complexity and since
the introduction of features like `customPkgs` which builds a
`ZSH_CUSTOM` path from a sequence of derivation a documentation may be
fairly helpful to make the knowledge how to use the module and how to
package new ZSH plugins visible.
See https://github.com/NixOS/nixpkgs/pull/43282#issuecomment-410770432
If multiple third-party modules shall be used for `oh-my-zsh` it has to
be possible to create another env which composes all the packages.
Now it can be done like this:
```
{ pkgs, ... }:
{
programs.zsh.enable = true;
programs.zsh.ohMyZsh = {
enable = true;
customPkgs = with pkgs; [
lambda-mod-zsh-theme
nix-zsh-completions
];
theme = "lambda-mod";
plugins = [ "nix" ];
};
}
```
Please keep in mind that this is not compatible with
`programs.zsh.ohMyZsh.custom`, only one of these options can be used
ATM.
Each package should store its outputs into
`$out/share/zsh/<output-name>`. Completions (and ZSH-only) extensions
should live in the `fpath` (`$out/share/zsh/site-functions`), plugins in
`.../plugins` and themes in `.../themes` (please refer to
fdb6bf6ed68c2f089ae6c729dfeaa3eddea2ce6a and 406d64aad162b3a4881747be4e24705fb5182573).
All scripts in `customPkgs` will be linked together using `linkFarm` to
provide a single directory for all scripts from all derivations in
`customPkgs` as suggested in https://github.com/NixOS/nixpkgs/pull/43282#issuecomment-410396365.
The default cache directory set by oh-my-zsh is $ohMyZsh/cache which
lives in the Nix store in our case. This causes issues with several
completion plugins provided by oh-my-zsh.
Originially, `programs.zsh` sets default values for some
initialisation scripts.
Nix resolves the case of multiple values by concatenating them all.
It is however impossible to predict where the default script will be
inserted; but we never want the default value to override the
user-specified ones.
Now, it doesn't set default values; almost everything is hardcoded at
the begining of the file.
* programs.zsh: add enableOhMyZsh option to automate setup of oh-my-zsh in global zshrc
* programs.zsh: make oh-my-zsh plugins configurable
* programs.zsh: add ohMyZshCustom option
* programs.zsh: add ohMyZshTheme option
* programs.zsh: applying minor fixes to evaluate expressions properly
* programs.zsh: fix ordering of oh-my-zsh config and execution
* programs.zsh: move all oh-my-zsh params into its own scope named programs.zsh.oh-my-zsh
