diff options
| author | Evan Martin <martine@danga.com> | 2015-11-17 14:04:50 -0800 |
|---|---|---|
| committer | Evan Martin <martine@danga.com> | 2015-11-17 14:05:53 -0800 |
| commit | a6859ac8af7377b1a1e136a6b296f8e8ca950507 (patch) | |
| tree | c80140188229269ead4b6f033ad6a42090a00c57 | |
| parent | 274db07276106944f63a3387bc3826e2211da154 (diff) | |
| download | ninja-a6859ac8af7377b1a1e136a6b296f8e8ca950507.tar.gz | |
improve docs generation, including PDF output
- Fix the manual build rules (missing the .xsl as an input).
- Add a README describing how the docs build works.
- Add rules that generate PDF, just 'cause we can.
| -rwxr-xr-x | configure.py | 12 | ||||
| -rw-r--r-- | doc/README.md | 11 | ||||
| -rw-r--r-- | doc/dblatex.xsl | 7 | ||||
| -rw-r--r-- | doc/docbook.xsl | 22 |
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" |