this adds support for structural includes to nixos-render-docs.
structural includes provide a way to denote the (sub)structure of the
nixos manual in the markdown source files, very similar to how we used
literal docbook blocks before, and are processed by nixos-render-docs
without involvement of xml tooling. this will ultimately allow us to
emit the nixos manual in other formats as well, e.g. html, without going
through docbook at all.
alternatives to this source layout were also considered:
a parallel structure using e.g. toml files that describe the document
tree and links to each part is possible, but much more complicated to
implement than the solution chosen here and makes it harder to follow
which files have what substructure. it also makes it much harder to
include a substructure in the middle of a file.
much the same goes for command-line arguments to the converter, only
that command-lined arguments are even harder to specify correctly and
cannot be reasonably pulled together from many places without involving
another layer of tooling. cli arguments would also mean that the manual
structure would be fixed in default.nix, which is also not ideal.
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.
- Update download URLs
- Replace "USB stick"/"USB Drive" with "USB flash drive" as that seem more correct
https://en.wikipedia.org/wiki/USB_flash_drivehttps://elementary.io/docs/installation#choose-operating-system
- Don't mention CD as easiest option anymore,
as all modern systems should be able to boot from USB,
but many don't have a CD drive. Burning CDs is also usually wasteful as you
can't burn them again.
- Remove link to NixOS Wiki (Making_the_installation_media) as it is not needed
- Add Etcher and USBImager as graphical tools to create install drive
- Make dd command consistent and use block size of 4 MB for faster flashing
- More consistent text
- Add instructions for "Booting from the install medium"
Inspired by 9a91b0f495/docs/installation.md (booting-from-the-install-drive-booting-from-the-installation-medium-clear-float-2)
- Add instructions for "Graphical Installation"
- Restructure headings and anchors for "Manual Installation"
- Adding legacy anchors for "Manual Installation" to not break links
Co-authored-by: j-k <dev@j-k.io>
Co-authored-by: Sandro <sandro.jaeckel@gmail.com>
Co-authored-by: Robert Schütz <github@dotlambda.de>
Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
Co-authored-by: Thiago Kenji Okada <thiagokokada@gmail.com>
$ 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.
