commit a8d4cf149cda4f82145291cc9a6819a9baa3951e · pyrox.dev/nixpkgs

+1 -1

doc/Makefile

···

       11
       11
        
       pandoc_flags = --extract-media=$(pandoc_media_dir) \

     

       12
       12
        
       	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \

     

       13
       13
        
       	--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \

     

       14
       14
       -
       	--lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \

     

       14
       14
       +
       	--lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \

     

       15
       15
        
       	--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \

     

       16
       16
        
       	--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \

     

       17
       17
        
       	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart

+28

doc/build-aux/pandoc-filters/link-manpages.nix

···

       1
       1
       +
       { pkgs ? import ../../.. {} }:

     

       2
       2
       +
       let

     

       3
       3
       +
         inherit (pkgs) lib;

     

       4
       4
       +
         manpageURLs = builtins.fromJSON (builtins.readFile (pkgs.path + "/doc/manpage-urls.json"));

     

       5
       5
       +
       in pkgs.writeText "link-manpages.lua" ''

     

       6
       6
       +
         --[[

     

       7
       7
       +
         Adds links to known man pages that aren't already in a link.

     

       8
       8
       +
         ]]

     

       9
       9
       +
       

     

       10
       10
       +
         local manpage_urls = {

     

       11
       11
       +
         ${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url:

     

       12
       12
       +
           "  [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)}

     

       13
       13
       +
         }

     

       14
       14
       +
       

     

       15
       15
       +
         traverse = 'topdown'

     

       16
       16
       +
       

     

       17
       17
       +
         -- Returning false as the second value aborts processing of child elements.

     

       18
       18
       +
         function Link(elem)

     

       19
       19
       +
           return elem, false

     

       20
       20
       +
         end

     

       21
       21
       +
       

     

       22
       22
       +
         function Code(elem)

     

       23
       23
       +
           local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'

     

       24
       24
       +
           if is_man_role and manpage_urls[elem.text] ~= nil then

     

       25
       25
       +
             return pandoc.Link(elem, manpage_urls[elem.text]), false

     

       26
       26
       +
           end

     

       27
       27
       +
         end

     

       28
       28
       +
       ''

-38

doc/build-aux/pandoc-filters/link-unix-man-references.lua

···

       1
       1
       -
       --[[

     

       2
       2
       -
       Turns a manpage reference into a link, when a mapping is defined below.

     

       3
       3
       -
       ]]

     

       4
       4
       -
       

     

       5
       5
       -
       local man_urls = {

     

       6
       6
       -
         ["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",

     

       7
       7
       -
       

     

       8
       8
       -
         ["journald.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/journald.conf.html",

     

       9
       9
       -
         ["logind.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/logind.conf.html",

     

       10
       10
       -
         ["networkd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",

     

       11
       11
       -
         ["systemd.automount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",

     

       12
       12
       -
         ["systemd.exec(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",

     

       13
       13
       -
         ["systemd.link(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.link.html",

     

       14
       14
       -
         ["systemd.mount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",

     

       15
       15
       -
         ["systemd.netdev(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",

     

       16
       16
       -
         ["systemd.network(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.network.html",

     

       17
       17
       -
         ["systemd.nspawn(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",

     

       18
       18
       -
         ["systemd.path(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.path.html",

     

       19
       19
       -
         ["systemd.resource-control(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",

     

       20
       20
       -
         ["systemd.scope(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",

     

       21
       21
       -
         ["systemd.service(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.service.html",

     

       22
       22
       -
         ["systemd.slice(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",

     

       23
       23
       -
         ["systemd.socket(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",

     

       24
       24
       -
         ["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",

     

       25
       25
       -
         ["systemd.unit(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",

     

       26
       26
       -
         ["timesyncd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",

     

       27
       27
       -
         ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",

     

       28
       28
       -
         ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",

     

       29
       29
       -
         ["systemd-fstab-generator(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",

     

       30
       30
       -
         ["systemd-networkd-wait-online.service(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html",

     

       31
       31
       -
       }

     

       32
       32
       -
       

     

       33
       33
       -
       function Code(elem)

     

       34
       34
       -
         local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'

     

       35
       35
       -
         if is_man_role and man_urls[elem.text] ~= nil then

     

       36
       36
       -
           return pandoc.Link(elem, man_urls[elem.text])

     

       37
       37
       -
         end

     

       38
       38
       -
       end

+1 -1

doc/contributing/contributing-to-documentation.chapter.md

···

       53
       53
        
         This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).

     

       54
       54
        
       

     

       55
       55
        
       - []{#ssec-contributing-markup-inline-roles}

     

       56
       56
       -
         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`.

     

       56
       56
       +
         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`.

     

       57
       57
        
       

     

       58
       58
        
         A few markups for other kinds of literals are also available:

     

       59
       59

+1

doc/default.nix

···

       36
       36
        
       

     

       37
       37
        
         # Environment variables

     

       38
       38
        
         PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";

     

       39
       39
       +
         PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; };

     

       39
       40
        
       }

+29

doc/manpage-urls.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "nix.conf(5)": "https://nixos.org/manual/nix/stable/#sec-conf-file",

     

       3
       3
       +
       

     

       4
       4
       +
         "journald.conf(5)": "https://www.freedesktop.org/software/systemd/man/journald.conf.html",

     

       5
       5
       +
         "logind.conf(5)": "https://www.freedesktop.org/software/systemd/man/logind.conf.html",

     

       6
       6
       +
         "networkd.conf(5)": "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",

     

       7
       7
       +
         "systemd.automount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",

     

       8
       8
       +
         "systemd.exec(5)": "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",

     

       9
       9
       +
         "systemd.link(5)": "https://www.freedesktop.org/software/systemd/man/systemd.link.html",

     

       10
       10
       +
         "systemd.mount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",

     

       11
       11
       +
         "systemd.netdev(5)": "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",

     

       12
       12
       +
         "systemd.network(5)": "https://www.freedesktop.org/software/systemd/man/systemd.network.html",

     

       13
       13
       +
         "systemd.nspawn(5)": "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",

     

       14
       14
       +
         "systemd.path(5)": "https://www.freedesktop.org/software/systemd/man/systemd.path.html",

     

       15
       15
       +
         "systemd.resource-control(5)": "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",

     

       16
       16
       +
         "systemd.scope(5)": "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",

     

       17
       17
       +
         "systemd.service(5)": "https://www.freedesktop.org/software/systemd/man/systemd.service.html",

     

       18
       18
       +
         "systemd.slice(5)": "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",

     

       19
       19
       +
         "systemd.socket(5)": "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",

     

       20
       20
       +
         "systemd.timer(5)": "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",

     

       21
       21
       +
         "systemd.unit(5)": "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",

     

       22
       22
       +
         "systemd-system.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html",

     

       23
       23
       +
         "systemd-user.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-user.conf.html",

     

       24
       24
       +
         "timesyncd.conf(5)": "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",

     

       25
       25
       +
         "tmpfiles.d(5)": "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",

     

       26
       26
       +
         "systemd.time(7)": "https://www.freedesktop.org/software/systemd/man/systemd.time.html",

     

       27
       27
       +
         "systemd-fstab-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",

     

       28
       28
       +
         "systemd-networkd-wait-online.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html"

     

       29
       29
       +
       }

+1 -1

maintainers/scripts/db-to-md.sh

···

       41
       41
        
           # - diagram-generator.lua (we do not support that in NixOS manual to limit dependencies)

     

       42
       42
        
           # - media extraction (was only required for diagram generator)

     

       43
       43
        
           # - myst-reader/roles.lua (only relevant for MyST → DocBook)

     

       44
       44
       -
           # - link-unix-man-references.lua (links should only be added to display output)

     

       44
       44
       +
           # - link-manpages.lua (links should only be added to display output)

     

       45
       45
        
           # - docbook-writer/rst-roles.lua (only relevant for → DocBook)

     

       46
       46
        
           # - docbook-writer/labelless-link-is-xref.lua (only relevant for → DocBook)

     

       47
       47
        
           "--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua"

+3 -1

nixos/doc/manual/md-to-db.sh

···

       8
       8
        
       DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"

     

       9
       9
        
       pushd "$DIR"

     

       10
       10
        
       

     

       11
       11
       +
       link_manpages_filter=$(nix-build --no-out-link "$DIR/../../../doc/build-aux/pandoc-filters/link-manpages.nix")

     

       12
       12
       +
       

     

       11
       13
        
       # NOTE: Keep in sync with Nixpkgs manual (/doc/Makefile).

     

       12
       14
        
       # TODO: Remove raw-attribute when we can get rid of DocBook altogether.

     

       13
       15
        
       pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute

     
···

       17
       19
        
         # - media extraction (was only required for diagram generator)

     

       18
       20
        
         # - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)

     

       19
       21
        
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua"

     

       20
       20
       -
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/link-unix-man-references.lua"

     

       22
       22
       +
         "--lua-filter=$link_manpages_filter"

     

       21
       23
        
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua"

     

       22
       24
        
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua"

     

       23
       25
        
         "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua"