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.
nixos-render-docs supports inline anchors, but not ids for blocks. it
seems wise to reserve blocks for special cases that don't have other
syntax already, like admonitions.
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.
the examples for mkPackageOption weren't terminated, leading to pretty
odd nesting of docbook (and thus html) elements. close them properly.
also turn the (likewise unclosed) fenced div containing just an anchor
id and a class that will be silently dropped to an inline anchor while
we're here. we'd have to convert it anyway later.
markdown-it parses deflists slitghtly differently than pandoc does. in
these two cases pandoc would find a deflist item while markdown-it would
not, instead it'd find a lone colon and the rest of the text.
this converts meta.doc into an md pointer, not an xml pointer. since we
no longer need xml for manual chapters we can also remove support for
manual chapters from md-to-db.sh
since pandoc converts smart quotes to docbook quote elements and our
nixos-render-docs does not we lose this distinction in the rendered
output. that's probably not that bad, our stylesheet didn't make use of
this anyway (and pre-23.05 versions of the chapters didn't use quote
elements either).
also updates the nixpkgs manual to clarify that option docs support all
extensions (although it doesn't support headings at all, so heading
anchors don't work by extension).
`shell_interact()` is currently not nice to use. If you try to cancel
the socat process, it will also break the nixos test. Furthermore
ptpython creates it's own terminal that subprocesses are running in,
which breaks some of the terminal features of socat.
Hence this commit extends `shell_interact` to allow also to connect to
arbitrary servers i.e. tcp servers started by socat.
Add a section on ordering option definitions.
Also mention `mkDefault` in the section on `mkOverride`.
Clarify the code a bit by renaming `defaultPriority` to
`defaultOverridePriority` and introducing `defaultOrderPriority`.
deprecate literalDocBook by adding a warning (that will not fire yet) to
its uses and other docbook literal strings by adding optional warning
message to mergeJSON.
