diff options
author | Naïm Favier <n@monade.li> | 2023-01-09 11:57:01 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-01-09 11:57:01 +0100 |
commit | bff4bb554028cbf083bc0d1e0a6a251653e5056d (patch) | |
tree | e0fc4768d98a58e68076bf11e578ec3f0b53e843 /doc | |
parent | 8cd3fc50f9f13a1dc93f237c97789fac3675d524 (diff) | |
parent | 4fb500d62937dcce11c84e7c36fcc0d5db354d5c (diff) |
Merge pull request #208762 from ncfavier/link-manpages-options-doc
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile | 2 | ||||
-rw-r--r-- | doc/build-aux/pandoc-filters/link-manpages.nix | 28 | ||||
-rw-r--r-- | doc/build-aux/pandoc-filters/link-unix-man-references.lua | 38 | ||||
-rw-r--r-- | doc/contributing/contributing-to-documentation.chapter.md | 2 | ||||
-rw-r--r-- | doc/default.nix | 1 | ||||
-rw-r--r-- | doc/manpage-urls.json | 29 |
6 files changed, 60 insertions, 40 deletions
diff --git a/doc/Makefile b/doc/Makefile index f8d2d7248fabc..1e54aef9bd122 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,7 +11,7 @@ pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracket pandoc_flags = --extract-media=$(pandoc_media_dir) \ --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/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/labelless-link-is-xref.lua \ -f commonmark$(pandoc_commonmark_enabled_extensions)+smart diff --git a/doc/build-aux/pandoc-filters/link-manpages.nix b/doc/build-aux/pandoc-filters/link-manpages.nix new file mode 100644 index 0000000000000..ee27c5d608125 --- /dev/null +++ b/doc/build-aux/pandoc-filters/link-manpages.nix @@ -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 +'' diff --git a/doc/build-aux/pandoc-filters/link-unix-man-references.lua b/doc/build-aux/pandoc-filters/link-unix-man-references.lua deleted file mode 100644 index b81d4a0979e72..0000000000000 --- a/doc/build-aux/pandoc-filters/link-unix-man-references.lua +++ /dev/null @@ -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 diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 81482523cd0ec..889b4114accaf 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -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). - []{#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: diff --git a/doc/default.nix b/doc/default.nix index ac382ec8519c5..1d5fa4811a369 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -36,4 +36,5 @@ in pkgs.stdenv.mkDerivation { # Environment variables 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; }; } diff --git a/doc/manpage-urls.json b/doc/manpage-urls.json new file mode 100644 index 0000000000000..0ff4b762bec7e --- /dev/null +++ b/doc/manpage-urls.json @@ -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" +} |