since support for kbd elements was added with explicit intent in #175128
it seems like a good idea to support this in nixos-render-docs instead
of just dropping it in favor of `*F12*` etc. since it's a very rare
thing in the manual and purely presentational it makes sense to use
bracketed spans instead of a new myst role.
the html-elements.lua plugin is now somewhat misnamed, but it'll go away
very soon so we don't want to bother renaming it.
pandoc drops .title classes when rendering to docbook, so these are
effectively just paragraphs anyway. without support for including them
in a table of contents the complexity of parsing them in
nixos-render-docs won't be warranted.
pandoc renders these to multiple docbook paragraphs in a single
definition for the term, not multiple *actual* definitions for the same
term. this is most likely not what is intended here, so let's use
multiple paragraphs instead.
The nixos-generate-config command mentioned in the manual fails with error:
nixos-generate-config: no need to specify `/` with `--root`, it is the default
This was introduced in 611b8c4472
(#161034). Now, the command should be called without any arguments.
$ parted /dev/nvme1n1 -- mkpart primary linux-swap -8GiB 100%
Warning: The resulting partition is not properly aligned for best performance: 3108850352s % 2048s != 0s
Ignore/Cancel?
Information: You may need to update /etc/fstab.
When using GB than parted seems to round up itself.
Without configuring the block size a default of 512 bytes is used, which can
slow down the transfer speed massively.
In a test I've done with a semi-decent USB stick, I only get a transfer speed
of around 180 KB/sec when not specifying the block size but see 27 MB/sec when
setting the block size to 1 MB. This makes the transfer of the minimal
installation ISO take half a minute instead of an hour.
The command in example is expected to be run from nixpkgs checkout, but
there's no explanation of this. Let's just use system nixpkgs: most
users will have it just working and those who use git checkouts will
figure it out.
The wpa_supplicant service in the NixOS installer is unusable because
the control socket is disabled and /etc/wpa_supplicant.conf ignored.
The manual currently recommends manually starting the daemon and using
wpa_passphrase, but this requires figuring out the interface name,
driver and only works for WPA2 personal networks.
By enabling the control socket, instead, a user can configure the
network via wpa_cli (or wpa_gui in the graphical installer), which
support more advanced network configurations.
The essential commands from the NixOS installer as a package
With this package, you get the commands like nixos-generate-config and
nixos-install that you would otherwise only find on a NixOS system, such
as an installer image.
This way, you can install NixOS using a machine that only has Nix.
It also includes the manpages, which are important because the commands
rely on those for providing --help.
