cafkafk/nixpkgs
cafkafk/nixpkgs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
nixpkgs/nixos/doc/manual/manual.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

57 lines
1.5 KiB
Markdown
Raw Permalink Normal View History

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.
2023-02-11 08:48:06 +01:00
# NixOS Manual {#book-nixos-manual}
## Version @NIXOS_VERSION@
<!--
this is the top-level structure file for the nixos manual.
the manual structure extends the nixpkgs commonmark further with include
blocks to allow better organization of input text. there are six types of
include blocks: preface, parts, chapters, sections, appendix, and options.
each type except `options`` corresponds to the docbook elements of (roughly)
the same name, and can itself can further include blocks to denote its
substructure.
non-`options`` include blocks are fenced code blocks that list a number of
files to include, in the form
```{=include=} <type>
<file-name-1>
<file-name-2>
<...>
```
`options` include blocks do not list file names but contain a list of key-value
pairs that describe the options to be included and how to convert them into
elements of the manual output type:
```{=include=} options
id-prefix: <options id prefix>
list-id: <variable list element id>
source: <path to options.json>
```
-->
```{=include=} preface
preface.md
```
```{=include=} parts
installation/installation.md
configuration/configuration.md
administration/running.md
development/development.md
```
```{=include=} chapters
contributing-to-this-manual.chapter.md
```
nixos/manual: render html with nixos-render-doc if !allowDocBook this reproduces the docbook-generated html manual exactly enough to appease the compare workflows while we still support both toolchains. it's also a lot faster than the docbook toolchain, rendering the entire html manual in about two seconds on this machine (while docbook needs about 20).
2023-02-20 18:55:15 +01:00
```{=include=} appendix html:into-file=//options.html
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.
2023-02-11 08:48:06 +01:00
nixos-options.md
nixos/manual: render html with nixos-render-doc if !allowDocBook this reproduces the docbook-generated html manual exactly enough to appease the compare workflows while we still support both toolchains. it's also a lot faster than the docbook toolchain, rendering the entire html manual in about two seconds on this machine (while docbook needs about 20).
2023-02-20 18:55:15 +01:00
```
```{=include=} appendix html:into-file=//release-notes.html
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.
2023-02-11 08:48:06 +01:00
release-notes/release-notes.md
```
Reference in a new issue Copy permalink