Permalink
Browse files

Add xsl files to doc directory so people can build docs easily

  • Loading branch information...
1 parent 8c41adb commit 412b4636c8b7edfa05b7cb97691a1ddb656cea55 @ry ry committed Sep 11, 2009
View
@@ -120,7 +120,7 @@ doc/api.xml: doc/api.txt
doc/node.1: doc/api.xml
xsltproc --output doc/node.1 \\
- --nonet /etc/asciidoc/docbook-xsl/manpage.xsl \\
+ --nonet doc/docbook-xsl/manpage.xsl \\
doc/api.xml
website-upload: doc
@@ -0,0 +1,96 @@
+AsciiDoc DocBook XSL Stylesheets Notes
+======================================
+
+*********************************************************************
+All current AsciiDoc PDF and manpage documentation has been generated
+using *DocBook XSL Stylesheets version 1.72.0*, these notes and
+patches relate to this version. The version of FOP used is 0.20.5 (I
+did try FOP 0.93 under Ubuntu 6.10, but got a Java exception which I
+didn't pursue).
+
+*********************************************************************
+
+My tools of choice for converting AsciiDoc generated DocBook files to
+PDF and manpage files are xsltproc(1), FOP and DocBook XSL
+Stylesheets. Output file customisation is achieved by tweaking the
+DocBook XSL stylesheets. I've tried to keep customization to a minimum
+and confine it to the separate XSL driver files in the distribution
+`./docbook-xsl/` directory (see the User Guide for details).
+
+To polish some rough edges I've written some patches for the DocBook
+XSL stylesheets -- you don't need them but they're documented below
+and included in the distribution `./docbook-xsl/` directory.
+
+
+Manually upgrading Debian to the latest DocBook XSL stylesheets
+---------------------------------------------------------------
+The DocBook XSL Stylesheets distribution is just a directory full of
+text files and you can switch between releases by changing the
+directory name in the system XML catalog.
+
+To upgrade to the latest docbook-xsl stylesheets without having to
+wait for the Debian `docbook-xsl` package:
+
+- Download the latest docbook-xsl tarball from
+ http://sourceforge.net/projects/docbook/[].
+
+- Unzip the tarball to `/usr/share/xml/docbook/stylesheet/`:
+
+ $ cd /usr/share/xml/docbook/stylesheet
+ $ sudo tar -xzf /tmp/docbook-xsl-1.72.0.tar.gz
+
+- Edit `/etc/xml/docbook-xsl.xml` catalog and replace occurences of
+ the current stylesheets directory with the new one (in our example
+ it would be `/usr/share/xml/docbook/stylesheet/docbook-xsl-1.72.0`.
+
+ $ cd /etc/xml/
+ $ sudo cp -p docbook-xsl.xml docbook-xsl.xml.ORIG
+ $ sudo vi docbook-xsl.xml
+
+- Apply optional patches (see below).
+
+
+Patches to DocBook XSL Stylesheets
+----------------------------------
+NOTE: You'll find the patch files in the AsciiDoc distribution archive
+`./docbook-xsl/` directory.
+
+Shade Literal Block Patch
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The processing expectation for AsciiDoc LiteralBlocks and
+LiteralParagraphs is that they are not shaded. The
+`shaded-literallayout.patch` was devised to allow AciiDoc Listing
+blocks to be shaded while leaving Literal paragraphs and Literal
+blocks unshaded (the default DocBook XSL Stylesheets behavior is to
+shade all verbatim elements).
+
+The patch implements a `shade.literallayout` XSL parameter so that
+shading in literal elements could be disabled while other verbatim
+elements are left shaded (by setting the XSL `shade.verbatim`
+parameter).
+
+The relevant patch file is `shaded-literallayout.patch` and it can be
+applied from the DocBook XSL Stylesheets directory:
+
+ $ cd /usr/share/xml/docbook/stylesheet/docbook-xsl-1.72.0
+ $ sudo patch -p0 < /tmp/shaded-literallayout.patch
+
+/////////////////////////////////////////////////////////////////////
+Manpage spurious .sp patch
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+IMPORTANT: *Don't apply this patch*. It was designed for docbook-xsl
+1.69.1 (the previous version of docbook-xsl used with AsciiDoc) and
+does not work with 1.72.0. I don't think it's necessary with
+docbook-xsl 1.72.0.
+
+Standalone `simpara` and some nested `title` DocBook elements generate
+`.sp` groff markup without a preceding newline, the `manpage-sp.patch`
+fixes this as well as stripping out extra blank lines generated by
+some `.sp` markup elements.
+
+The patch can be applied from the DocBook XSL Stylesheets directory
+with the following command:
+
+ # patch -p0 < manpage-sp.patch
+
+/////////////////////////////////////////////////////////////////////
@@ -0,0 +1,19 @@
+<!--
+ Generates chunked XHTML documents from DocBook XML source using DocBook XSL
+ stylesheets.
+
+ NOTE: The URL reference to the current DocBook XSL stylesheets is
+ rewritten to point to the copy on the local disk drive by the XML catalog
+ rewrite directives so it doesn't need to go out to the Internet for the
+ stylesheets. This means you don't need to edit the <xsl:import> elements on
+ a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
+<xsl:import href="common.xsl"/>
+<xsl:param name="base.dir" select="'./chunked/'"/>
+<xsl:param name="html.stylesheet" select="'./docbook-xsl.css'"/>
+<xsl:param name="navig.graphics.path">../images/icons/</xsl:param>
+<xsl:param name="admon.graphics.path">../images/icons/</xsl:param>
+<xsl:param name="callout.graphics.path" select="'../images/icons/callouts/'"/>
+</xsl:stylesheet>
View
@@ -0,0 +1,61 @@
+<!--
+ Inlcuded in xhtml.xsl, xhtml.chunked.xsl, htmlhelp.xsl.
+ Contains common XSL stylesheets parameters.
+ Output documents styled by docbook.css.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:param name="html.stylesheet" select="'./docbook-xsl.css'"/>
+
+<xsl:param name="htmlhelp.chm" select="'htmlhelp.chm'"/>
+<xsl:param name="htmlhelp.hhc.section.depth" select="5"/>
+
+<xsl:param name="suppress.navigation" select="0"/>
+<xsl:param name="navig.graphics.extension" select="'.png'"/>
+<xsl:param name="navig.graphics" select="0"/>
+<xsl:param name="navig.graphics.path">./images/icons/</xsl:param>
+<xsl:param name="navig.showtitles">0</xsl:param>
+
+<xsl:param name="shade.verbatim" select="0"/>
+<xsl:attribute-set name="shade.verbatim.style">
+ <xsl:attribute name="border">0</xsl:attribute>
+ <xsl:attribute name="bgcolor">#E0E0E0</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:param name="admon.graphics" select="1"/>
+<xsl:param name="admon.graphics.path">./images/icons/</xsl:param>
+<xsl:param name="admon.graphics.extension" select="'.png'"/>
+<xsl:param name="admon.style">
+ <xsl:text>margin-left: 0; margin-right: 10%;</xsl:text>
+</xsl:param>
+<xsl:param name="admon.textlabel" select="1"/>
+
+<xsl:param name="callout.defaultcolumn" select="'60'"/>
+<xsl:param name="callout.graphics.extension" select="'.png'"/>
+<xsl:param name="callout.graphics" select="'1'"/>
+<xsl:param name="callout.graphics.number.limit" select="'10'"/>
+<xsl:param name="callout.graphics.path" select="'./images/icons/callouts/'"/>
+<xsl:param name="callout.list.table" select="'1'"/>
+
+<xsl:param name="base.dir" select="'./xhtml/'"/>
+<xsl:param name="chunk.first.sections" select="0"/>
+<xsl:param name="chunk.quietly" select="0"/>
+<xsl:param name="chunk.section.depth" select="1"/>
+<xsl:param name="chunk.toc" select="''"/>
+<xsl:param name="chunk.tocs.and.lots" select="0"/>
+
+<xsl:param name="html.cellpadding" select="'4px'"/>
+<xsl:param name="html.cellspacing" select="''"/>
+
+<xsl:param name="table.borders.with.css" select="1"/>
+<xsl:param name="table.cell.border.color" select="''"/>
+
+<xsl:param name="table.cell.border.style" select="'solid'"/>
+<xsl:param name="table.cell.border.thickness" select="'1px'"/>
+<xsl:param name="table.footnote.number.format" select="'a'"/>
+<xsl:param name="table.footnote.number.symbols" select="''"/>
+<xsl:param name="table.frame.border.color" select="'#527bbd'"/>
+<xsl:param name="table.frame.border.style" select="'solid'"/>
+<xsl:param name="table.frame.border.thickness" select="'2px'"/>
+<xsl:param name="tablecolumns.extension" select="'1'"/>
+
+</xsl:stylesheet>
View
@@ -0,0 +1,112 @@
+<!--
+ Generates single FO document from DocBook XML source using DocBook XSL
+ stylesheets.
+
+ See xsl-stylesheets/fo/param.xsl for all parameters.
+
+ NOTE: The URL reference to the current DocBook XSL stylesheets is
+ rewritten to point to the copy on the local disk drive by the XML catalog
+ rewrite directives so it doesn't need to go out to the Internet for the
+ stylesheets. This means you don't need to edit the <xsl:import> elements on
+ a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
+<xsl:import href="common.xsl"/>
+
+<xsl:param name="fop.extensions" select="1" />
+<xsl:param name="variablelist.as.blocks" select="1" />
+
+<xsl:param name="paper.type" select="'A4'"/>
+<!--
+<xsl:param name="paper.type" select="'USletter'"/>
+-->
+<xsl:param name="hyphenate">false</xsl:param>
+<!-- justify, left or right -->
+<xsl:param name="alignment">left</xsl:param>
+
+<xsl:param name="body.font.family" select="'serif'"/>
+<xsl:param name="body.font.master">12</xsl:param>
+<xsl:param name="body.font.size">
+ <xsl:value-of select="$body.font.master"/><xsl:text>pt</xsl:text>
+</xsl:param>
+
+<xsl:param name="body.margin.bottom" select="'0.5in'"/>
+<xsl:param name="body.margin.top" select="'0.5in'"/>
+<xsl:param name="bridgehead.in.toc" select="0"/>
+
+<!-- Default fetches image from Internet (long timeouts) -->
+<xsl:param name="draft.watermark.image" select="''"/>
+
+<!-- Sets title to body text indent -->
+<xsl:param name="title.margin.left">
+ <xsl:choose>
+ <xsl:when test="$passivetex.extensions != 0">0pt</xsl:when>
+ <xsl:otherwise>-12pt</xsl:otherwise>
+ </xsl:choose>
+</xsl:param>
+
+<xsl:param name="page.margin.bottom" select="'0.25in'"/>
+<xsl:param name="page.margin.inner">
+ <xsl:choose>
+ <xsl:when test="$double.sided != 0">0.75in</xsl:when>
+ <xsl:otherwise>0.5in</xsl:otherwise>
+ </xsl:choose>
+</xsl:param>
+<xsl:param name="page.margin.outer">
+ <xsl:choose>
+ <xsl:when test="$double.sided != 0">0.5in</xsl:when>
+ <xsl:otherwise>0.5in</xsl:otherwise>
+ </xsl:choose>
+</xsl:param>
+
+<xsl:param name="page.margin.top" select="'0.5in'"/>
+<xsl:param name="page.orientation" select="'portrait'"/>
+<xsl:param name="page.width">
+ <xsl:choose>
+ <xsl:when test="$page.orientation = 'portrait'">
+ <xsl:value-of select="$page.width.portrait"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$page.height.portrait"/>
+ </xsl:otherwise>
+ </xsl:choose>
+</xsl:param>
+
+<xsl:attribute-set name="monospace.properties">
+ <xsl:attribute name="font-size">10pt</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:param name="admon.graphics" select="1"/>
+<xsl:param name="admon.textlabel" select="1"/>
+<xsl:attribute-set name="admonition.title.properties">
+ <xsl:attribute name="font-size">14pt</xsl:attribute>
+ <xsl:attribute name="font-weight">bold</xsl:attribute>
+ <xsl:attribute name="hyphenate">false</xsl:attribute>
+ <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:attribute-set name="sidebar.properties" use-attribute-sets="formal.object.properties">
+ <xsl:attribute name="border-style">solid</xsl:attribute>
+ <xsl:attribute name="border-width">1pt</xsl:attribute>
+ <xsl:attribute name="border-color">silver</xsl:attribute>
+ <xsl:attribute name="background-color">#ffffee</xsl:attribute>
+ <xsl:attribute name="padding-left">12pt</xsl:attribute>
+ <xsl:attribute name="padding-right">12pt</xsl:attribute>
+ <xsl:attribute name="padding-top">6pt</xsl:attribute>
+ <xsl:attribute name="padding-bottom">6pt</xsl:attribute>
+ <xsl:attribute name="margin-left">0pt</xsl:attribute>
+ <xsl:attribute name="margin-right">12pt</xsl:attribute>
+ <xsl:attribute name="margin-top">6pt</xsl:attribute>
+ <xsl:attribute name="margin-bottom">6pt</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:param name="callout.graphics" select="'1'"/>
+
+<xsl:param name="shade.literallayout" select="0"/>
+<xsl:param name="shade.verbatim" select="1"/>
+<xsl:attribute-set name="shade.verbatim.style">
+ <xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
+</xsl:attribute-set>
+
+</xsl:stylesheet>
@@ -0,0 +1,17 @@
+<!--
+ Generates chunked HTML Help HTML documents from DocBook XML source using
+ DocBook XSL stylesheets.
+
+ NOTE: The URL reference to the current DocBook XSL stylesheets is
+ rewritten to point to the copy on the local disk drive by the XML catalog
+ rewrite directives so it doesn't need to go out to the Internet for the
+ stylesheets. This means you don't need to edit the <xsl:import> elements on
+ a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl"/>
+<xsl:import href="common.xsl"/>
+<xsl:param name="base.dir" select="'./htmlhelp/'"/>
+<xsl:param name="htmlhelp.hhp" select="'asciidoc.hhp'"/>
+<xsl:param name="suppress.navigation" select="1"/>
+</xsl:stylesheet>
@@ -0,0 +1,41 @@
+diff -u ./manpages.ORIG/block.xsl ./manpages/block.xsl
+--- ./manpages.ORIG/block.xsl 2005-11-30 17:31:23.135642494 +1300
++++ ./manpages/block.xsl 2005-11-30 17:35:59.368886010 +1300
+@@ -37,7 +37,7 @@
+ <xsl:apply-templates/>
+ </xsl:variable>
+ <xsl:value-of select="normalize-space($content)"/>
+- <xsl:text>.sp&#10;</xsl:text>
++ <xsl:text>&#10;.sp&#10;</xsl:text>
+ </xsl:template>
+
+ <xsl:template match="address|literallayout|programlisting|screen|synopsis">
+@@ -56,7 +56,7 @@
+ <xsl:when test="parent::caption|parent::entry|parent::para|
+ parent::td|parent::th" /> <!-- do nothing -->
+ <xsl:otherwise>
+- <xsl:text>.sp&#10;</xsl:text>
++ <xsl:text>&#10;.sp&#10;</xsl:text>
+ </xsl:otherwise>
+ </xsl:choose>
+ <xsl:text>.nf&#10;</xsl:text>
+diff -u ./manpages.ORIG/param.xsl ./manpages/param.xsl
+--- ./manpages.ORIG/param.xsl 2005-11-30 17:31:23.164638883 +1300
++++ ./manpages/param.xsl 2005-11-30 17:58:14.345174391 +1300
+@@ -47,6 +47,16 @@
+ <substitution oldstring="&#xA;&#xA;." newstring="&#xA;."/>
+ <!-- * remove any .sp occurences that directly follow a .PP -->
+ <substitution oldstring=".PP&#xA;.sp" newstring=".PP"/>
++
++ <!-- * remove any .sp occurences that directly preceed a .SH -->
++ <substitution oldstring=".sp&#xA;.SH" newstring=".SH"/>
++ <!-- * remove any .sp occurences that directly preceed a .TP -->
++ <substitution oldstring=".sp&#xA;.TP" newstring=".TP"/>
++ <!-- * remove any .sp occurences that directly preceed a .SS -->
++ <substitution oldstring=".sp&#xA;.SS" newstring=".SS"/>
++ <!-- * remove any .sp occurences that directly preceed a .sp -->
++ <substitution oldstring=".sp&#xA;.sp" newstring=".sp"/>
++
+ <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
+ <substitution oldstring=".nf&#xA;&#xA;" newstring=".nf&#xA;"/>
+ <!-- * an apostrophe at the beginning of a line gets interpreted as a -->
@@ -0,0 +1,28 @@
+<!--
+ Generates single roff manpage document from DocBook XML source using DocBook
+ XSL stylesheets.
+
+ NOTE: The URL reference to the current DocBook XSL stylesheets is
+ rewritten to point to the copy on the local disk drive by the XML catalog
+ rewrite directives so it doesn't need to go out to the Internet for the
+ stylesheets. This means you don't need to edit the <xsl:import> elements on
+ a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>
+<xsl:import href="common.xsl"/>
+
+<!-- Only render the link text -->
+<xsl:template match="ulink">
+ <xsl:variable name="content">
+ <xsl:apply-templates/>
+ </xsl:variable>
+ <xsl:value-of select="$content"/>
+</xsl:template>
+
+<!-- Don't automatically generate the REFERENCES section -->
+<xsl:template name="format.links.list">
+</xsl:template>
+
+</xsl:stylesheet>
+
Oops, something went wrong.

0 comments on commit 412b463

Please sign in to comment.