mirror of
https://github.com/SebastianWendel/nixpkgs.git
synced 2024-09-20 04:19:00 +02:00
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:
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
|
nixos-render-docs
|
||||||
];
|
];
|
||||||
|
|
||||||
src = pkgs.nix-gitignore.gitignoreSource [] ./.;
|
src = ./.;
|
||||||
|
|
||||||
postPatch = ''
|
postPatch = ''
|
||||||
ln -s ${doc-support} ./doc-support/result
|
ln -s ${doc-support} ./doc-support/result
|
||||||
|
|
|
@ -21,26 +21,6 @@ let
|
||||||
functionDocs = import ./lib-function-docs.nix { inherit pkgs nixpkgs libsets; };
|
functionDocs = import ./lib-function-docs.nix { inherit pkgs nixpkgs libsets; };
|
||||||
version = pkgs.lib.version;
|
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
|
# NB: This file describes the Nixpkgs manual, which happens to use module
|
||||||
# docs infra originally developed for NixOS.
|
# docs infra originally developed for NixOS.
|
||||||
optionsDoc = pkgs.nixosOptionsDoc {
|
optionsDoc = pkgs.nixosOptionsDoc {
|
||||||
|
@ -70,13 +50,6 @@ in pkgs.runCommand "doc-support" {}
|
||||||
cd result
|
cd result
|
||||||
ln -s ${functionDocs} ./function-docs
|
ln -s ${functionDocs} ./function-docs
|
||||||
ln -s ${optionsDoc.optionsJSON} ./config-options.json
|
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
|
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 a new issue