diff options
Diffstat (limited to 'doc/build-aux/pandoc-filters')
6 files changed, 164 insertions, 0 deletions
diff --git a/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua b/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua new file mode 100644 index 00000000000..281e85af271 --- /dev/null +++ b/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua @@ -0,0 +1,23 @@ +--[[ +Converts Code AST nodes produced by pandoc’s DocBook reader +from citerefentry elements into AST for corresponding role +for reStructuredText. + +We use subset of MyST syntax (CommonMark with features from rST) +so let’s use the rST AST for rST features. + +Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage +]] + +function Code(elem) + elem.classes = elem.classes:map(function (x) + if x == 'citerefentry' then + elem.attributes['role'] = 'manpage' + return 'interpreted-text' + else + return x + end + end) + + return elem +end diff --git a/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua b/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua new file mode 100644 index 00000000000..fa97729a28b --- /dev/null +++ b/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua @@ -0,0 +1,34 @@ +--[[ +Converts Link AST nodes with empty label to DocBook xref elements. + +This is a temporary script to be able use cross-references conveniently +using syntax taken from MyST, while we still use docbook-xsl +for generating the documentation. + +Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing +]] + +local function starts_with(start, str) + return str:sub(1, #start) == start +end + +local function escape_xml_arg(arg) + amps = arg:gsub('&', '&') + amps_quotes = amps:gsub('"', '"') + amps_quotes_lt = amps_quotes:gsub('<', '<') + + return amps_quotes_lt +end + +function Link(elem) + has_no_content = #elem.content == 0 + targets_anchor = starts_with('#', elem.target) + has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0 + + if has_no_content and targets_anchor and has_no_attributes then + -- xref expects idref without the pound-sign + target_without_hash = elem.target:sub(2, #elem.target) + + return pandoc.RawInline('docbook', '<xref linkend="' .. escape_xml_arg(target_without_hash) .. '" />') + end +end diff --git a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua new file mode 100644 index 00000000000..92dc6895750 --- /dev/null +++ b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua @@ -0,0 +1,36 @@ +--[[ +Converts AST for reStructuredText roles into corresponding +DocBook elements. + +Currently, only a subset of roles is supported. + +Reference: + List of roles: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html + manpage: + https://tdg.docbook.org/tdg/5.1/citerefentry.html + file: + https://tdg.docbook.org/tdg/5.1/filename.html +]] + +function Code(elem) + if elem.classes:includes('interpreted-text') then + local tag = nil + local content = elem.text + if elem.attributes['role'] == 'manpage' then + tag = 'citerefentry' + local title, volnum = content:match('^(.+)%((%w+)%)$') + if title == nil then + -- No volnum in parentheses. + title = content + end + content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '') + elseif elem.attributes['role'] == 'file' then + tag = 'filename' + end + + if tag ~= nil then + return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>') + end + 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 new file mode 100644 index 00000000000..e437ac73a1c --- /dev/null +++ b/doc/build-aux/pandoc-filters/link-unix-man-references.lua @@ -0,0 +1,17 @@ +--[[ +Turns a manpage reference into a link, when a mapping is defined below. +]] + +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/build-aux/pandoc-filters/myst-reader/roles.lua b/doc/build-aux/pandoc-filters/myst-reader/roles.lua new file mode 100644 index 00000000000..c33a688eeba --- /dev/null +++ b/doc/build-aux/pandoc-filters/myst-reader/roles.lua @@ -0,0 +1,29 @@ +--[[ +Replaces Str AST nodes containing {role}, followed by a Code node +by a Code node with attrs that would be produced by rST reader +from the role syntax. + +This is to emulate MyST syntax in Pandoc. +(MyST is a CommonMark flavour with rST features mixed in.) + +Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point +]] + +function Inlines(inlines) + for i = #inlines-1,1,-1 do + local first = inlines[i] + local second = inlines[i+1] + local correct_tags = first.tag == 'Str' and second.tag == 'Code' + if correct_tags then + -- docutils supports alphanumeric strings separated by [-._:] + -- We are slightly more liberal for simplicity. + local role = first.text:match('^{([-._+:%w]+)}$') + if role ~= nil then + inlines:remove(i) + second.attributes['role'] = role + second.classes:insert('interpreted-text') + end + end + end + return inlines +end diff --git a/doc/build-aux/pandoc-filters/myst-writer/roles.lua b/doc/build-aux/pandoc-filters/myst-writer/roles.lua new file mode 100644 index 00000000000..0136bc55065 --- /dev/null +++ b/doc/build-aux/pandoc-filters/myst-writer/roles.lua @@ -0,0 +1,25 @@ +--[[ +Replaces Code nodes with attrs that would be produced by rST reader +from the role syntax by a Str AST node containing {role}, followed by a Code node. + +This is to emulate MyST syntax in Pandoc. +(MyST is a CommonMark flavour with rST features mixed in.) + +Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point +]] + +function Code(elem) + local role = elem.attributes['role'] + + if elem.classes:includes('interpreted-text') and role ~= nil then + elem.classes = elem.classes:filter(function (c) + return c ~= 'interpreted-text' + end) + elem.attributes['role'] = nil + + return { + pandoc.Str('{' .. role .. '}'), + elem, + } + end +end |