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).
Move the manpage-to-URL mapping to `doc/manpage-urls.json` so that we can
reuse that file elsewhere, and generate the `link-manpages.lua` filter from
that file.
Also modify the Pandoc filter so that it doesn't wrap manpages that are
already inside a link.
Keeping a Lua filter is essential for speed: a Python filter would
increase the runtime `md-to-db.sh` from ~20s to ~30s (but Python is not
to blame; marshalling Pandoc types to and from JSON is a costly operation).
Parsing in Lua seems tedious, so I went with the Nix way.
Until now, this script has used the version of pandoc from unstable.
This means that running the script on the same version of Nixpkgs
could produce different results, and meant that when Pandoc's output
was changed, random PRs were changing the whole manual when they ran
the script to regenerate docs[1][2].
Here I've changed the manual to use a consistent version of pandoc —
the one from the latest release tag, which will avoid this problem in
future. This will avoid this problem in future. The only time we'll
need to worry about pandoc output changes is when we bump the version
used in this script.
I also considered using the version from the current Nixpkgs branch,
but decided against it as it's unlikely that e.g. the person bumping
Pandoc will remember to regenerate the manual.
[1]: https://github.com/NixOS/nixpkgs/pull/162550
[2]: https://github.com/NixOS/nixpkgs/pull/168535
