nixos-render-docs: add structural includes, use for manual

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.

3 files changed, 18 insertions, 25 deletions

diff --git a/nixos/doc/manual/installation/installation.md b/nixos/doc/manual/installation/installation.md
new file mode 100644
index 0000000000000..140594256609f
--- /dev/null
+++ b/nixos/doc/manual/installation/installation.md
@@ -0,0 +1,11 @@
+# Installation {#ch-installation}
+
+This section describes how to obtain, install, and configure NixOS for first-time use.
+
+```{=include=} chapters
+obtaining.chapter.md
+installing.chapter.md
+changing-config.chapter.md
+upgrading.chapter.md
+building-nixos.chapter.md
+```
diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml
deleted file mode 100644
index ba07d71d0ca35..0000000000000
--- a/nixos/doc/manual/installation/installation.xml
+++ /dev/null
@@ -1,18 +0,0 @@
-<part xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="ch-installation">
- <title>Installation</title>
- <partintro xml:id="ch-installation-intro">
-  <para>
-   This section describes how to obtain, install, and configure NixOS for
-   first-time use.
-  </para>
- </partintro>
- <xi:include href="../from_md/installation/obtaining.chapter.xml" />
- <xi:include href="../from_md/installation/installing.chapter.xml" />
- <xi:include href="../from_md/installation/changing-config.chapter.xml" />
- <xi:include href="../from_md/installation/upgrading.chapter.xml" />
- <xi:include href="../from_md/installation/building-nixos.chapter.xml" />
-</part>
diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md
index e1908017a7e44..cf783c2d22b6f 100644
--- a/nixos/doc/manual/installation/installing.chapter.md
+++ b/nixos/doc/manual/installation/installing.chapter.md
@@ -602,11 +602,11 @@ With a partitioned disk.
 
 ## Additional installation notes {#sec-installation-additional-notes}
 
-```{=docbook}
-<xi:include href="installing-usb.section.xml" />
-<xi:include href="installing-pxe.section.xml" />
-<xi:include href="installing-kexec.section.xml" />
-<xi:include href="installing-virtualbox-guest.section.xml" />
-<xi:include href="installing-from-other-distro.section.xml" />
-<xi:include href="installing-behind-a-proxy.section.xml" />
+```{=include=} sections
+installing-usb.section.md
+installing-pxe.section.md
+installing-kexec.section.md
+installing-virtualbox-guest.section.md
+installing-from-other-distro.section.md
+installing-behind-a-proxy.section.md
 ```