summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rwxr-xr-xconfigure.py12
-rw-r--r--doc/README.md11
-rw-r--r--doc/dblatex.xsl7
-rw-r--r--doc/docbook.xsl22
4 files changed, 45 insertions, 7 deletions
diff --git a/configure.py b/configure.py
index 0710ea2..2104aff 100755
--- a/configure.py
+++ b/configure.py
@@ -592,13 +592,19 @@ n.rule('asciidoc',
n.rule('xsltproc',
command='xsltproc --nonet doc/docbook.xsl $in > $out',
description='XSLTPROC $out')
-xml = n.build(built('manual.xml'), 'asciidoc', doc('manual.asciidoc'))
-manual = n.build(doc('manual.html'), 'xsltproc', xml,
- implicit=doc('style.css'))
+docbookxml = n.build(built('manual.xml'), 'asciidoc', doc('manual.asciidoc'))
+manual = n.build(doc('manual.html'), 'xsltproc', docbookxml,
+ implicit=[doc('style.css'), doc('docbook.xsl')])
n.build('manual', 'phony',
order_only=manual)
n.newline()
+n.rule('dblatex',
+ command='dblatex -q -o $out -p doc/dblatex.xsl $in',
+ description='DBLATEX $out')
+n.build(doc('manual.pdf'), 'dblatex', docbookxml,
+ implicit=[doc('dblatex.xsl')])
+
n.comment('Generate Doxygen.')
n.rule('doxygen',
command='doxygen $in',
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..6afe5d4
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,11 @@
+This directory contains the Ninja manual and support files used in
+building it. Here's a brief overview of how it works.
+
+The source text, `manual.asciidoc`, is written in the AsciiDoc format.
+AsciiDoc can generate HTML but it doesn't look great; instead, we use
+AsciiDoc to generate the Docbook XML format and then provide our own
+Docbook XSL tweaks to produce HTML from that.
+
+In theory using AsciiDoc and DocBook allows us to produce nice PDF
+documentation etc. In reality it's not clear anyone wants that, but the
+build rules are in place to generate it if you install dblatex.
diff --git a/doc/dblatex.xsl b/doc/dblatex.xsl
new file mode 100644
index 0000000..c0da212
--- /dev/null
+++ b/doc/dblatex.xsl
@@ -0,0 +1,7 @@
+<!-- This custom XSL tweaks the dblatex XML settings. -->
+<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
+ <!-- These parameters disable the list of collaborators and revisions.
+ Together remove a useless page from the front matter. -->
+ <xsl:param name='doc.collab.show'>0</xsl:param>
+ <xsl:param name='latex.output.revhistory'>0</xsl:param>
+</xsl:stylesheet>
diff --git a/doc/docbook.xsl b/doc/docbook.xsl
index 8afdc8c..19cc126 100644
--- a/doc/docbook.xsl
+++ b/doc/docbook.xsl
@@ -1,15 +1,29 @@
-<!-- This soup of XML is the minimum customization necessary to make the
- autogenerated manual look ok. -->
+<!-- This custom XSL tweaks the DocBook XML -> HTML settings to produce
+ an OK-looking manual. -->
<!DOCTYPE xsl:stylesheet [
<!ENTITY css SYSTEM "style.css">
]>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
+
+ <!-- Embed our stylesheet as the user-provided <head> content. -->
<xsl:template name="user.head.content"><style>&css;</style></xsl:template>
+
+ <!-- Remove the body.attributes block, which specifies a bunch of
+ useless bgcolor etc. attrs on the <body> tag. -->
<xsl:template name="body.attributes"></xsl:template>
- <xsl:param name="generate.toc" select="'book toc'"/>
- <xsl:param name="chapter.autolabel" select="0" />
+
+ <!-- Specify that in "book" form (which we're using), we only want a
+ single table of contents at the beginning of the document. -->
+ <xsl:param name="generate.toc">book toc</xsl:param>
+
+ <!-- Don't put the "Chapter 1." prefix on the "chapters". -->
+ <xsl:param name="chapter.autolabel">0</xsl:param>
+
+ <!-- Use <ul> for the table of contents. By default DocBook uses a
+ <dl>, which makes no semantic sense. I imagine they just did
+ it because it looks nice? -->
<xsl:param name="toc.list.type">ul</xsl:param>
<xsl:output method="html" encoding="utf-8" indent="no"