nixos/make-options-doc: link manpages #208762
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
ncfavier
requested review from
a team,
jtojnar,
fricklerhandwerk and
ryantm
as code owners
github-actions
bot
added
6.topic: nixos
ofborg
bot
added
10.rebuild-darwin: 0
|
Cool stuff! |
ncfavier
commented
Jan 2, 2023
Add links to manpages without a link using the mapping defined in `doc/manpage-urls.json`, as is already done for the nixpkgs and NixOS manuals.
ncfavier
force-pushed
the
link-manpages-options-doc
branch
from
b4226d2 to
4fb500d
Compare
7 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
See discussion in #207268 (comment), see commits.
In the future we could consider generating the mapping dynamically as a
.nixfile, e.g. extracting the full list of systemd manpages frompkgs.systemd.man.If this is merged, nixos-search will temporarily have double links in nixos options because it extracts them from
options.json(where the links have already been inserted) and re-applies the oldlink-unix-man-references.luafilter in the Docbook → HTML conversion. Most browsers should handle this fine.