From a6859ac8af7377b1a1e136a6b296f8e8ca950507 Mon Sep 17 00:00:00 2001 From: Evan Martin Date: Tue, 17 Nov 2015 14:04:50 -0800 Subject: 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. --- configure.py | 12 +++++++++--- doc/README.md | 11 +++++++++++ doc/dblatex.xsl | 7 +++++++ doc/docbook.xsl | 22 ++++++++++++++++++---- 4 files changed, 45 insertions(+), 7 deletions(-) create mode 100644 doc/README.md create mode 100644 doc/dblatex.xsl 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 @@ + + + + 0 + 0 + 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 @@ - + ]> + + + + - - + + + book toc + + + 0 + + ul