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
parent
be4d19ff1a
commit
f397309f4e
11
doc/.gitignore
vendored
11
doc/.gitignore
vendored
@ -1,11 +0,0 @@
|
||||
*.chapter.xml
|
||||
*.section.xml
|
||||
.version
|
||||
functions/library/generated
|
||||
functions/library/locations.xml
|
||||
highlightjs
|
||||
manual-full.xml
|
||||
out
|
||||
result
|
||||
result-*
|
||||
media
|
||||
@ -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
|
||||
@ -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', '<xref linkend="' .. escape_xml_arg(target_without_hash) .. '" />')
|
||||
end
|
||||
end
|
||||
@ -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
|
||||
@ -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
|
||||
''
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
''
|
||||
|
||||
@ -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>
|
||||
@ -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
|
||||
@ -1,3 +0,0 @@
|
||||
{ pkgs ? import ../. { } }:
|
||||
(import ./default.nix { }).overrideAttrs
|
||||
(x: { buildInputs = (x.buildInputs or [ ]) ++ [ pkgs.xmloscopy pkgs.ruby ]; })
|
||||
Loading…
Reference in New Issue
Block a user