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.
This commit is contained in:
parent
5a9a335334
commit
a8d4cf149c
|
@ -11,7 +11,7 @@ pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracket
|
||||||
pandoc_flags = --extract-media=$(pandoc_media_dir) \
|
pandoc_flags = --extract-media=$(pandoc_media_dir) \
|
||||||
--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
|
--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
|
||||||
--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
|
--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
|
||||||
--lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \
|
--lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \
|
||||||
--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
|
--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
|
||||||
--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
|
--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
|
||||||
-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
|
-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
|
||||||
|
|
28
doc/build-aux/pandoc-filters/link-manpages.nix
Normal file
28
doc/build-aux/pandoc-filters/link-manpages.nix
Normal file
|
@ -0,0 +1,28 @@
|
||||||
|
{ pkgs ? import ../../.. {} }:
|
||||||
|
let
|
||||||
|
inherit (pkgs) lib;
|
||||||
|
manpageURLs = builtins.fromJSON (builtins.readFile (pkgs.path + "/doc/manpage-urls.json"));
|
||||||
|
in pkgs.writeText "link-manpages.lua" ''
|
||||||
|
--[[
|
||||||
|
Adds links to known man pages that aren't already in a link.
|
||||||
|
]]
|
||||||
|
|
||||||
|
local manpage_urls = {
|
||||||
|
${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url:
|
||||||
|
" [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)}
|
||||||
|
}
|
||||||
|
|
||||||
|
traverse = 'topdown'
|
||||||
|
|
||||||
|
-- Returning false as the second value aborts processing of child elements.
|
||||||
|
function Link(elem)
|
||||||
|
return elem, false
|
||||||
|
end
|
||||||
|
|
||||||
|
function Code(elem)
|
||||||
|
local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
|
||||||
|
if is_man_role and manpage_urls[elem.text] ~= nil then
|
||||||
|
return pandoc.Link(elem, manpage_urls[elem.text]), false
|
||||||
|
end
|
||||||
|
end
|
||||||
|
''
|
|
@ -1,38 +0,0 @@
|
||||||
--[[
|
|
||||||
Turns a manpage reference into a link, when a mapping is defined below.
|
|
||||||
]]
|
|
||||||
|
|
||||||
local man_urls = {
|
|
||||||
["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",
|
|
||||||
|
|
||||||
["journald.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/journald.conf.html",
|
|
||||||
["logind.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/logind.conf.html",
|
|
||||||
["networkd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",
|
|
||||||
["systemd.automount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",
|
|
||||||
["systemd.exec(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",
|
|
||||||
["systemd.link(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.link.html",
|
|
||||||
["systemd.mount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",
|
|
||||||
["systemd.netdev(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",
|
|
||||||
["systemd.network(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.network.html",
|
|
||||||
["systemd.nspawn(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",
|
|
||||||
["systemd.path(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.path.html",
|
|
||||||
["systemd.resource-control(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",
|
|
||||||
["systemd.scope(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",
|
|
||||||
["systemd.service(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.service.html",
|
|
||||||
["systemd.slice(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",
|
|
||||||
["systemd.socket(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",
|
|
||||||
["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
|
|
||||||
["systemd.unit(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",
|
|
||||||
["timesyncd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",
|
|
||||||
["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
|
|
||||||
["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
|
|
||||||
["systemd-fstab-generator(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",
|
|
||||||
["systemd-networkd-wait-online.service(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html",
|
|
||||||
}
|
|
||||||
|
|
||||||
function Code(elem)
|
|
||||||
local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
|
|
||||||
if is_man_role and man_urls[elem.text] ~= nil then
|
|
||||||
return pandoc.Link(elem, man_urls[elem.text])
|
|
||||||
end
|
|
||||||
end
|
|
|
@ -53,7 +53,7 @@ Additional syntax extensions are available, though not all extensions can be use
|
||||||
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
|
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-inline-roles}
|
- []{#ssec-contributing-markup-inline-roles}
|
||||||
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`.
|
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/manpage-urls.json`.
|
||||||
|
|
||||||
A few markups for other kinds of literals are also available:
|
A few markups for other kinds of literals are also available:
|
||||||
|
|
||||||
|
|
|
@ -36,4 +36,5 @@ in pkgs.stdenv.mkDerivation {
|
||||||
|
|
||||||
# Environment variables
|
# Environment variables
|
||||||
PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";
|
PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";
|
||||||
|
PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; };
|
||||||
}
|
}
|
||||||
|
|
29
doc/manpage-urls.json
Normal file
29
doc/manpage-urls.json
Normal file
|
@ -0,0 +1,29 @@
|
||||||
|
{
|
||||||
|
"nix.conf(5)": "https://nixos.org/manual/nix/stable/#sec-conf-file",
|
||||||
|
|
||||||
|
"journald.conf(5)": "https://www.freedesktop.org/software/systemd/man/journald.conf.html",
|
||||||
|
"logind.conf(5)": "https://www.freedesktop.org/software/systemd/man/logind.conf.html",
|
||||||
|
"networkd.conf(5)": "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",
|
||||||
|
"systemd.automount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",
|
||||||
|
"systemd.exec(5)": "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",
|
||||||
|
"systemd.link(5)": "https://www.freedesktop.org/software/systemd/man/systemd.link.html",
|
||||||
|
"systemd.mount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",
|
||||||
|
"systemd.netdev(5)": "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",
|
||||||
|
"systemd.network(5)": "https://www.freedesktop.org/software/systemd/man/systemd.network.html",
|
||||||
|
"systemd.nspawn(5)": "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",
|
||||||
|
"systemd.path(5)": "https://www.freedesktop.org/software/systemd/man/systemd.path.html",
|
||||||
|
"systemd.resource-control(5)": "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",
|
||||||
|
"systemd.scope(5)": "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",
|
||||||
|
"systemd.service(5)": "https://www.freedesktop.org/software/systemd/man/systemd.service.html",
|
||||||
|
"systemd.slice(5)": "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",
|
||||||
|
"systemd.socket(5)": "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",
|
||||||
|
"systemd.timer(5)": "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
|
||||||
|
"systemd.unit(5)": "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",
|
||||||
|
"systemd-system.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html",
|
||||||
|
"systemd-user.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-user.conf.html",
|
||||||
|
"timesyncd.conf(5)": "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",
|
||||||
|
"tmpfiles.d(5)": "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
|
||||||
|
"systemd.time(7)": "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
|
||||||
|
"systemd-fstab-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",
|
||||||
|
"systemd-networkd-wait-online.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html"
|
||||||
|
}
|
|
@ -41,7 +41,7 @@ pandoc_flags=(
|
||||||
# - diagram-generator.lua (we do not support that in NixOS manual to limit dependencies)
|
# - diagram-generator.lua (we do not support that in NixOS manual to limit dependencies)
|
||||||
# - media extraction (was only required for diagram generator)
|
# - media extraction (was only required for diagram generator)
|
||||||
# - myst-reader/roles.lua (only relevant for MyST → DocBook)
|
# - myst-reader/roles.lua (only relevant for MyST → DocBook)
|
||||||
# - link-unix-man-references.lua (links should only be added to display output)
|
# - link-manpages.lua (links should only be added to display output)
|
||||||
# - docbook-writer/rst-roles.lua (only relevant for → DocBook)
|
# - docbook-writer/rst-roles.lua (only relevant for → DocBook)
|
||||||
# - docbook-writer/labelless-link-is-xref.lua (only relevant for → DocBook)
|
# - docbook-writer/labelless-link-is-xref.lua (only relevant for → DocBook)
|
||||||
"--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua"
|
"--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua"
|
||||||
|
|
|
@ -8,6 +8,8 @@
|
||||||
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
||||||
pushd "$DIR"
|
pushd "$DIR"
|
||||||
|
|
||||||
|
link_manpages_filter=$(nix-build --no-out-link "$DIR/../../../doc/build-aux/pandoc-filters/link-manpages.nix")
|
||||||
|
|
||||||
# NOTE: Keep in sync with Nixpkgs manual (/doc/Makefile).
|
# NOTE: Keep in sync with Nixpkgs manual (/doc/Makefile).
|
||||||
# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
|
# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
|
||||||
pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
|
pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
|
||||||
|
@ -17,7 +19,7 @@ pandoc_flags=(
|
||||||
# - media extraction (was only required for diagram generator)
|
# - media extraction (was only required for diagram generator)
|
||||||
# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
|
# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
|
||||||
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua"
|
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua"
|
||||||
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/link-unix-man-references.lua"
|
"--lua-filter=$link_manpages_filter"
|
||||||
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua"
|
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua"
|
||||||
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua"
|
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua"
|
||||||
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua"
|
"--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua"
|
||||||
|
|
Loading…
Reference in a new issue