Commit Graph

13 Commits

Author SHA1 Message Date
Naïm Favier
a8d4cf149c
doc: separate manpage URLs from the Pandoc filter
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.
2023-01-02 14:11:22 +01:00
Naïm Favier
07cb3bf3cc
nixos/doc: bump Pandoc
Update the pinned channel in `md-to-db`, which bumps the Pandoc version,
which fixes https://github.com/NixOS/nixpkgs/issues/125511 maybe.
2022-12-27 17:23:25 +01:00
Jan Tojnar
fa285355ee nixos/doc/manual/md-to-db.sh: Add support for <kbd> element 2022-10-26 01:46:44 +02:00
Alyssa Ross
b825f6db56 nixos/doc/md-to-db.sh: consistent pandoc version
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
2022-04-14 12:57:51 +00:00
Luflosi
7938ea67a7
nixos/doc/md-to-db.sh: handle path to nixpkgs with spaces
Without this change, the script will fail if the path to nixpkgs contains a space.
2021-10-10 11:57:51 +02:00
Jan Tojnar
1e75936926
Merge pull request #130047 from NixOS/doc-manpage-role
doc: Add support for manpage references
2021-09-07 21:29:26 +02:00
Ryan Mulligan
c863de29a7 nixos/doc/md-to-db.sh: handle Docbook inclues in CommonMark
You can do includes like this:

```{=docbook}
<xi:include href="rl-2111.section.xml" />
```
2021-09-07 06:29:21 -07:00
Jan Tojnar
04b59b0328 doc: Linkify man page references 2021-07-13 02:21:22 +02:00
Jan Tojnar
c9139dfa1a doc: Add support for MyST roles
Officially, only the manpage role is supported at the moment.

Unlike in rST, the syntax uses braces instead of colons:

    {manpage}`nix.conf(5)`
2021-07-13 02:10:57 +02:00
Jan Tojnar
a49d36b979 doc: Move lua filters to subdirectory 2021-07-12 22:57:28 +02:00
Jan Tojnar
f07dcbef64
nixos/doc: Synchronize the Markdown generator with Nixpkgs
Switch to CommonMark with our extensions.
2021-06-18 00:07:00 +02:00
Ryan Mulligan
7501467903 nixos/doc: convert "Contributing to this manual" to CommonMark
Also updates it to mention running md-to-db.sh.
2021-05-22 18:14:49 -07:00
Ryan Mulligan
6c14851943 nixos/doc: add md-to-db.sh, convert "Building Your Own NixOS CD" to CommonMark 2021-05-22 18:14:49 -07:00