conversions were done using https://github.com/pennae/nix-doc-munge
using (probably) rev f34e145 running
nix-doc-munge nixos/**/*.nix
nix-doc-munge --import nixos/**/*.nix
the tool ensures that only changes that could affect the generated
manual *but don't* are committed, other changes require manual review
and are discarded.
This was enabled by default in 18a7ce76fc
with the reason that it would be "useful regardless of the desktop
environment.", which I'm not arguing against.
The reason why this should not be enabled by default is that there are a
lot of systems that NixOS runs on that are not desktop systems.
Users on such systems most likely do not want or need this feature and
could even consider this an antifeature.
Furthermore, it is surprising to them to find out that they have this
enabled on their systems.
They might be even more surprised to find that they have polkit enabled
by default, which was a default that was flipped in
a813be071c. For some discussion as to why
see https://github.com/NixOS/nixpkgs/pull/156858.
Evidently, this default is not only surprising to users, but also module
developers, as most if not all modules for desktop environments already
explicity set services.udisks2.enable = true; which they don't need to
right now.
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.
It seems that with the latest update to `udisks2`, the ExecStart path
for the daemon changed from `/lib/udisks2` to `/libexec/udisks2`. This
commit reflects that change for our purposes.
The ability for unprivileged users to mount external media is useful
regardless of the desktop environment. Also, since udisks2 is
activated on-demand, it doesn't add any overhead if you're not using it.
Using pkgs.lib on the spine of module evaluation is problematic
because the pkgs argument depends on the result of module
evaluation. To prevent an infinite recursion, pkgs and some of the
modules are evaluated twice, which is inefficient. Using ‘with lib’
prevents this problem.
