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.
This commit is contained in:
pennae 2023-06-23 00:26:52 +02:00
parent be4d19ff1a
commit f397309f4e
12 changed files with 1 additions and 323 deletions

11
doc/.gitignore vendored
View file

@ -1,11 +0,0 @@
*.chapter.xml
*.section.xml
.version
functions/library/generated
functions/library/locations.xml
highlightjs
manual-full.xml
out
result
result-*
media

View file

@ -1,23 +0,0 @@
--[[
Converts Code AST nodes produced by pandocs DocBook reader
from citerefentry elements into AST for corresponding role
for reStructuredText.
We use subset of MyST syntax (CommonMark with features from rST)
so lets 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

View file

@ -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('<', '&lt;')
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

View file

@ -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 = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') 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 .. '</' .. tag .. '>')
end
end
end

View file

@ -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
''

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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" ''
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl" />
<xsl:import href="${./parameters.xml}"/>
</xsl:stylesheet>
'';
xhtml-xsl = pkgs.writeText "xhtml.xsl" ''
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/xhtml/docbook.xsl" />
<xsl:import href="${./parameters.xml}"/>
</xsl:stylesheet>
'';
# 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
''

View file

@ -1,19 +0,0 @@
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:param name="chapter.autolabel" select="0" />
<xsl:param name="part.autolabel" select="0" />
<xsl:param name="preface.autolabel" select="0" />
<xsl:param name="reference.autolabel" select="0" />
<xsl:param name="section.autolabel" select="0" />
<xsl:param name="html.stylesheet" select="'style.css overrides.css highlightjs/mono-blue.css'" />
<xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" />
<xsl:param name="xref.with.number.and.title" select="0" />
<xsl:param name="use.id.as.filename" select="1" />
<xsl:param name="generate.section.toc.level" select="1" />
<xsl:param name="toc.section.depth" select="0" />
<xsl:param name="admon.style" select="''" />
<xsl:param name="callout.graphics.extension" select="'.svg'" />
<xsl:param name="generate.consistent.ids" select="1" />
</xsl:stylesheet>

View file

@ -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

View file

@ -1,3 +0,0 @@
{ pkgs ? import ../. { } }:
(import ./default.nix { }).overrideAttrs
(x: { buildInputs = (x.buildInputs or [ ]) ++ [ pkgs.xmloscopy pkgs.ruby ]; })