diff options
author | Jan Tojnar <jtojnar@gmail.com> | 2021-07-12 18:40:33 +0200 |
---|---|---|
committer | Jan Tojnar <jtojnar@gmail.com> | 2021-07-13 02:21:22 +0200 |
commit | 04b59b0328daaa2e11f5e387ad3ec475cf2d2028 (patch) | |
tree | c93741cf282e772100da2d366a23cfd099a04da5 /doc | |
parent | c9139dfa1a001e32baa6fea9c9373d80c83e39e9 (diff) | |
download | nixpkgs-04b59b0328daaa2e11f5e387ad3ec475cf2d2028.tar nixpkgs-04b59b0328daaa2e11f5e387ad3ec475cf2d2028.tar.gz nixpkgs-04b59b0328daaa2e11f5e387ad3ec475cf2d2028.tar.bz2 nixpkgs-04b59b0328daaa2e11f5e387ad3ec475cf2d2028.tar.lz nixpkgs-04b59b0328daaa2e11f5e387ad3ec475cf2d2028.tar.xz nixpkgs-04b59b0328daaa2e11f5e387ad3ec475cf2d2028.tar.zst nixpkgs-04b59b0328daaa2e11f5e387ad3ec475cf2d2028.zip |
doc: Linkify man page references
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile | 1 | ||||
-rw-r--r-- | doc/build-aux/pandoc-filters/link-unix-man-references.lua | 18 | ||||
-rw-r--r-- | doc/contributing/contributing-to-documentation.chapter.md | 4 |
3 files changed, 22 insertions, 1 deletions
diff --git a/doc/Makefile b/doc/Makefile index 9bcd30c150a..027a8b9e7bb 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,6 +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=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-unix-man-references.lua b/doc/build-aux/pandoc-filters/link-unix-man-references.lua new file mode 100644 index 00000000000..12431f140fe --- /dev/null +++ b/doc/build-aux/pandoc-filters/link-unix-man-references.lua @@ -0,0 +1,18 @@ +--[[ +Turns a manpage reference into a link, when a mapping is defined +in the unix-man-urls.lua file. +]] + +local man_urls = { + ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html", + ["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file", + ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html", + ["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.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 bf73a340bce..178fdb36262 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -53,7 +53,9 @@ Additionally, the following syntax extensions are currently used: 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)`. + 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/unix-man-urls.lua`. This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax. |