diff options
author | pennae <github@quasiparticle.net> | 2023-02-11 08:48:06 +0100 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2023-02-12 13:02:42 +0100 |
commit | 1229e735ac51dbe79724f7648655a2089c9c67b9 (patch) | |
tree | ba4f6a33e11574bde4108f67928b3f24ccfee901 /nixos/doc/manual/administration | |
parent | 8b7f0e559ad9419815d0a4c8d231e2bf464c0ad2 (diff) |
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.
Diffstat (limited to 'nixos/doc/manual/administration')
-rw-r--r-- | nixos/doc/manual/administration/containers.chapter.md | 8 | ||||
-rw-r--r-- | nixos/doc/manual/administration/running.md | 14 | ||||
-rw-r--r-- | nixos/doc/manual/administration/running.xml | 21 | ||||
-rw-r--r-- | nixos/doc/manual/administration/troubleshooting.chapter.md | 12 |
4 files changed, 24 insertions, 31 deletions
diff --git a/nixos/doc/manual/administration/containers.chapter.md b/nixos/doc/manual/administration/containers.chapter.md index ea51f91f698fb..50493b562b542 100644 --- a/nixos/doc/manual/administration/containers.chapter.md +++ b/nixos/doc/manual/administration/containers.chapter.md @@ -21,8 +21,8 @@ which is often not what you want. By contrast, in the imperative approach, containers are configured and updated independently from the host system. -```{=docbook} -<xi:include href="imperative-containers.section.xml" /> -<xi:include href="declarative-containers.section.xml" /> -<xi:include href="container-networking.section.xml" /> +```{=include=} sections +imperative-containers.section.md +declarative-containers.section.md +container-networking.section.md ``` diff --git a/nixos/doc/manual/administration/running.md b/nixos/doc/manual/administration/running.md new file mode 100644 index 0000000000000..48e8c7c6668b7 --- /dev/null +++ b/nixos/doc/manual/administration/running.md @@ -0,0 +1,14 @@ +# Administration {#ch-running} + +This chapter describes various aspects of managing a running NixOS system, such as how to use the {command}`systemd` service manager. + +```{=include=} chapters +service-mgmt.chapter.md +rebooting.chapter.md +user-sessions.chapter.md +control-groups.chapter.md +logging.chapter.md +cleaning-store.chapter.md +containers.chapter.md +troubleshooting.chapter.md +``` diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml deleted file mode 100644 index d9fcc1aee263f..0000000000000 --- a/nixos/doc/manual/administration/running.xml +++ /dev/null @@ -1,21 +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-running"> - <title>Administration</title> - <partintro xml:id="ch-running-intro"> - <para> - This chapter describes various aspects of managing a running NixOS system, - such as how to use the <command>systemd</command> service manager. - </para> - </partintro> - <xi:include href="../from_md/administration/service-mgmt.chapter.xml" /> - <xi:include href="../from_md/administration/rebooting.chapter.xml" /> - <xi:include href="../from_md/administration/user-sessions.chapter.xml" /> - <xi:include href="../from_md/administration/control-groups.chapter.xml" /> - <xi:include href="../from_md/administration/logging.chapter.xml" /> - <xi:include href="../from_md/administration/cleaning-store.chapter.xml" /> - <xi:include href="../from_md/administration/containers.chapter.xml" /> - <xi:include href="../from_md/administration/troubleshooting.chapter.xml" /> -</part> diff --git a/nixos/doc/manual/administration/troubleshooting.chapter.md b/nixos/doc/manual/administration/troubleshooting.chapter.md index 548456eaf6d67..1253607f8efc2 100644 --- a/nixos/doc/manual/administration/troubleshooting.chapter.md +++ b/nixos/doc/manual/administration/troubleshooting.chapter.md @@ -3,10 +3,10 @@ This chapter describes solutions to common problems you might encounter when you manage your NixOS system. -```{=docbook} -<xi:include href="boot-problems.section.xml" /> -<xi:include href="maintenance-mode.section.xml" /> -<xi:include href="rollback.section.xml" /> -<xi:include href="store-corruption.section.xml" /> -<xi:include href="network-problems.section.xml" /> +```{=include=} sections +boot-problems.section.md +maintenance-mode.section.md +rollback.section.md +store-corruption.section.md +network-problems.section.md ``` |