From f397309f4e6c7a219a7703b629f6a4e8d4e7a58b Mon Sep 17 00:00:00 2001 From: pennae Date: Fri, 23 Jun 2023 00:26:52 +0200 Subject: [PATCH] doc: remove remnants of docbook times all xml-related tooling can go away. shell.nix is no longer useful since the makefile is gone and the build runs entirely via a derivation, and gitignore is thus also no longer that useful. it may filter out some swap files, but its main reason to exist (keeping generated files out of a concurrent build of the derivation) has gone away. --- doc/.gitignore | 11 --- .../citerefentry-to-rst-role.lua | 23 ------ .../docbook-writer/labelless-link-is-xref.lua | 34 --------- .../docbook-writer/rst-roles.lua | 44 ------------ .../pandoc-filters/link-manpages.nix | 28 -------- .../pandoc-filters/myst-reader/roles.lua | 36 ---------- .../pandoc-filters/myst-writer/roles.lua | 25 ------- doc/default.nix | 2 +- doc/doc-support/default.nix | 27 ------- doc/doc-support/parameters.xml | 19 ----- doc/doc-support/xmlformat.conf | 72 ------------------- doc/shell.nix | 3 - 12 files changed, 1 insertion(+), 323 deletions(-) delete mode 100644 doc/.gitignore delete mode 100644 doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua delete mode 100644 doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua delete mode 100644 doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua delete mode 100644 doc/build-aux/pandoc-filters/link-manpages.nix delete mode 100644 doc/build-aux/pandoc-filters/myst-reader/roles.lua delete mode 100644 doc/build-aux/pandoc-filters/myst-writer/roles.lua delete mode 100644 doc/doc-support/parameters.xml delete mode 100644 doc/doc-support/xmlformat.conf delete mode 100644 doc/shell.nix diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index b08285995f66..000000000000 --- a/doc/.gitignore +++ /dev/null @@ -1,11 +0,0 @@ -*.chapter.xml -*.section.xml -.version -functions/library/generated -functions/library/locations.xml -highlightjs -manual-full.xml -out -result -result-* -media 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 deleted file mode 100644 index 281e85af2717..000000000000 --- a/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua +++ /dev/null @@ -1,23 +0,0 @@ ---[[ -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 deleted file mode 100644 index fa97729a28bc..000000000000 --- a/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua +++ /dev/null @@ -1,34 +0,0 @@ ---[[ -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', '') - 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 deleted file mode 100644 index 5c1b034d0792..000000000000 --- a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua +++ /dev/null @@ -1,44 +0,0 @@ ---[[ -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 = '' .. title .. '' .. (volnum ~= nil and ('' .. volnum .. '') or '') - elseif elem.attributes['role'] == 'file' then - tag = 'filename' - elseif elem.attributes['role'] == 'command' then - tag = 'command' - elseif elem.attributes['role'] == 'option' then - tag = 'option' - elseif elem.attributes['role'] == 'var' then - tag = 'varname' - elseif elem.attributes['role'] == 'env' then - tag = 'envar' - end - - if tag ~= nil then - return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '') - end - end -end diff --git a/doc/build-aux/pandoc-filters/link-manpages.nix b/doc/build-aux/pandoc-filters/link-manpages.nix deleted file mode 100644 index 2589a7c34251..000000000000 --- a/doc/build-aux/pandoc-filters/link-manpages.nix +++ /dev/null @@ -1,28 +0,0 @@ -{ pkgs ? import ../../.. {} }: -let - inherit (pkgs) lib; - manpageURLs = lib.importJSON (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/myst-reader/roles.lua b/doc/build-aux/pandoc-filters/myst-reader/roles.lua deleted file mode 100644 index f4ef6d390b40..000000000000 --- a/doc/build-aux/pandoc-filters/myst-reader/roles.lua +++ /dev/null @@ -1,36 +0,0 @@ ---[[ -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. - -- Allow preceding punctuation (eg '('), otherwise '({file}`...`)' - -- does not match. Also allow anything followed by a non-breaking space - -- since pandoc emits those after certain abbreviations (e.g. e.g.). - local prefix, role = first.text:match('^(.*){([-._+:%w]+)}$') - if role ~= nil and (prefix == '' or prefix:match("^.*[%p ]$") ~= nil) then - if prefix == '' then - inlines:remove(i) - else - first.text = prefix - end - 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 deleted file mode 100644 index 0136bc550652..000000000000 --- a/doc/build-aux/pandoc-filters/myst-writer/roles.lua +++ /dev/null @@ -1,25 +0,0 @@ ---[[ -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 diff --git a/doc/default.nix b/doc/default.nix index 57066aabdaa9..b8b25c3b4e07 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -50,7 +50,7 @@ in pkgs.stdenv.mkDerivation { nixos-render-docs ]; - src = pkgs.nix-gitignore.gitignoreSource [] ./.; + src = ./.; postPatch = '' ln -s ${doc-support} ./doc-support/result diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix index 34f1982f5c96..4f013c8edf9d 100644 --- a/doc/doc-support/default.nix +++ b/doc/doc-support/default.nix @@ -21,26 +21,6 @@ let functionDocs = import ./lib-function-docs.nix { inherit pkgs nixpkgs libsets; }; version = pkgs.lib.version; - epub-xsl = pkgs.writeText "epub.xsl" '' - - - - - - ''; - - xhtml-xsl = pkgs.writeText "xhtml.xsl" '' - - - - - - ''; - # NB: This file describes the Nixpkgs manual, which happens to use module # docs infra originally developed for NixOS. optionsDoc = pkgs.nixosOptionsDoc { @@ -70,13 +50,6 @@ in pkgs.runCommand "doc-support" {} cd result ln -s ${functionDocs} ./function-docs ln -s ${optionsDoc.optionsJSON} ./config-options.json - - ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng - ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl - ln -s ${epub-xsl} ./epub.xsl - ln -s ${xhtml-xsl} ./xhtml.xsl - - ln -s ${./xmlformat.conf} ./xmlformat.conf ) mv result $out '' diff --git a/doc/doc-support/parameters.xml b/doc/doc-support/parameters.xml deleted file mode 100644 index 5b39d2f7f1a5..000000000000 --- a/doc/doc-support/parameters.xml +++ /dev/null @@ -1,19 +0,0 @@ - - - - - - - - - - - - - - - - - diff --git a/doc/doc-support/xmlformat.conf b/doc/doc-support/xmlformat.conf deleted file mode 100644 index c3f39c7fd81b..000000000000 --- a/doc/doc-support/xmlformat.conf +++ /dev/null @@ -1,72 +0,0 @@ -# -# DocBook Configuration file for "xmlformat" -# see http://www.kitebird.com/software/xmlformat/ -# 10 Sept. 2004 -# - -# Only block elements -ackno address appendix article biblioentry bibliography bibliomixed \ -biblioset blockquote book bridgehead callout calloutlist caption caution \ -chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \ -constructorsynopsis dedication destructorsynopsis entry epigraph equation example \ -figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \ -glosssee glossseealso graphic graphicco highlights imageobjectco important \ -index indexdiv indexentry indexinfo info informalequation informalexample \ -informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \ -mediaobjectco msgmain msgset note orderedlist para part preface primaryie \ -procedure qandadiv qandaentry qandaset refentry refentrytitle reference \ -refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \ -sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \ -simplesect step substeps synopfragment synopsis table term title \ -toc variablelist varlistentry warning itemizedlist listitem \ -footnote colspec partintro row simplelist subtitle tbody tgroup thead tip - format block - normalize no - - -#appendix bibliography chapter glossary preface reference -# element-break 3 - -sect1 section - element-break 2 - - -# -para abstract - format block - entry-break 1 - exit-break 1 - normalize yes - -title - format block - normalize = yes - entry-break = 0 - exit-break = 0 - -# Inline elements -abbrev accel acronym action application citation citebiblioid citerefentry citetitle \ -classname co code command computeroutput constant country database date email emphasis \ -envar errorcode errorname errortext errortype exceptionname fax filename \ -firstname firstterm footnoteref foreignphrase funcdef funcparams function \ -glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \ -hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \ -interface interfacename \ -keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \ -menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \ -oointerface option optional otheraddr othername package paramdef parameter personname \ -phrase pob postcode productname prompt property quote refpurpose replaceable \ -returnvalue revnumber sgmltag state street structfield structname subscript \ -superscript surname symbol systemitem token trademark type ulink userinput \ -uri varargs varname void wordasword xref year mathphrase member tag - format inline - -programlisting screen - format verbatim - entry-break = 0 - exit-break = 0 - -# This is needed so that the spacing inside those tags is kept. -term cmdsynopsis arg - normalize yes - format block diff --git a/doc/shell.nix b/doc/shell.nix deleted file mode 100644 index 5fa2b4424899..000000000000 --- a/doc/shell.nix +++ /dev/null @@ -1,3 +0,0 @@ -{ pkgs ? import ../. { } }: -(import ./default.nix { }).overrideAttrs -(x: { buildInputs = (x.buildInputs or [ ]) ++ [ pkgs.xmloscopy pkgs.ruby ]; })