Issue: after installing, running `yubikey-agent -setup` produces the
following error:
```
nixOS: Failed to connect to the YubiKey: connecting to pscs: the Smart
card resource manager is not running
```
More on this issue: https://github.com/FiloSottile/yubikey-agent/issues/137
render all manual chapters to docbook from scratch every time the manual
is built. nixos-render-docs is quick enough at this to not worry about
the cost (needing only about a second), and it means we can remove
md-to-db.sh in the next commit.
no changes to the rendered html manual except for replacements and smartquotes.
we'll soon add another docbook converter that does not emit a section as
a collection of chapters, but sections or chapters on their own. this
should clarify naming a bit before there can be any confusion.
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.
this is a lot easier than adding footnote support for just the one
instance. if a use case for footnotes appears in the future (e.g. if we
wanted to render the nixpkgs manual with nixos-render-docs as well) this
decision should be reevaluated.
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.
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.
this should be placed before the appendices, not between them. might
even have a good place in the development part, but that's a decision
for another day.
