most of the lists in option docs are actually compact, but docbook to
manpage processing always rendered them as non-compact. compactifying
these lists improves readability somewhat since most lists and their
contents are pretty short.
mdoc is just too slow to render on groff, and semantic markup doesn't
help us any for generated pages.
this produces a lot of changes to configuration.nix.5, but only few
rendering changes. most of those seem to be place losing a space where
docbook emitted roff code that did not faithfully represent the input
text, though a few places also gained space where docbook dropped them.
notably we also don't need the compatibility code docbook-xsl emitted
because that problem was fixed over a decade ago.
this will handle block quotes, which the docbook stylesheets turned into
a mess of roff requests that ended up showing up in the output instead
of being processed.
Token.attr is a dict[str, str | int | float], meta has no restriction on
the value type. attrs is ostensibly meant for html attributes, meta for
any information whatsoever.
these work together with render and renderInline to produce an output
from either of the two. rendering manpages will need both: to join
blocks with newlines, and to run some postprocessing and the rendered inlines.
pulling mypy into the build closure is unfortunately not reasonable, the
closure for mypy is rather large and takes a long time to build. if we
have the type checks hooked into CI we'll get most of the benefit though.
this is not yet able to produce manual-combined.xml, but the intention
is to add that support before too long. for now we'll concentrate on
getting the basics working: concatenating a list of chapters into a
manual-combined fragment, which will be rendered via docbook.
previously we did not detect whether lists were supposed to be compact
or not. this will make a difference for manual chapters, so let's stop
not doing that.
headings are not supported in options docs (since it's unclear what that
would be in the final manual, and the docbook stylesheets already have
trouble rendering all docbook constructs correctly). ordered lists
should be supported, but obviously nothing uses them yet.
options do not use comments, but a number of manual chapters do. since
we don't want to enable html just so we can then inspect the html and
figure out whether it's a comment we'll instead add a plugin that
detects comments natively.
we will soon add plugins to this tool to support nixos markdown features
that aren't readily supported with markdown-it plugins. since we will
have to test these plugin we'll need access to the parser, and since
we'll also want to add functions that require postprocessing of a parsed
token stream we also add the necessary hooks now.
with some fiddling and custom validation logic we can avoid needing
multiple instances of this plugin. originally this wasn't done because
it does need a type stack to emit correct docbook, but since we can
easily do that now we may as well.
using environment variables isn't great once multiple input or output
formats get involved (which will happen soon). now is a good time to set
a pattern for future converters.
while we won't have other converters (with other output formats) for a
while yet it still seems like a good idea to generalize *now* so we have
a pattern to follow.
these modules will be extended with more functionality. md will
ultimately contain MD-related code such as parsers and converter base
classes. docbook will contain renderers.
this new package shall eventually contain the rendering code necessary
to produce the entirety of the nixos (not nixpkgs) manual, in all of its
various output formats.
checkInputs used to be added to nativeBuildInputs. Now we have
nativeCheckInputs to do that instead. Doing this treewide change allows
to keep hashes identical to before the introduction of
nativeCheckInputs.
Fixes `error: unable to execute '/nix/store/arrb5j23znf00p1i0kvd9bmb7ddamlxx-nix-output-monitor-2.0.0.2/bin/nix-output-monitor': No such file or directory` with nix run
