reactos/ninja
1
0
Fork 0
mirror of https://github.com/reactos/ninja.git synced 2024-11-26 21:20:23 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

improve docs generation, including PDF output

Browse Source 
- 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.
This commit is contained in:
Evan Martin 2015-11-17 14:04:50 -08:00
parent 274db07276
commit a6859ac8af
4 changed files with 45 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
configure.py
View File

@ -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',

11
doc/README.md Normal file
View File

@ -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.

7
doc/dblatex.xsl Normal file
View File

@ -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>

22
doc/docbook.xsl
View File

@ -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"