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

16 years ago · 412b4636c8
10 changed files with 421 additions and 1 deletions
--- a/2
+++ b/2
@ -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
--- a/doc/docbook-xsl/asciidoc-docbook-xsl.txt
+++ b/doc/docbook-xsl/asciidoc-docbook-xsl.txt
@ -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
 /////////////////////////////////////////////////////////////////////
--- a/doc/docbook-xsl/chunked.xsl
+++ b/doc/docbook-xsl/chunked.xsl
@ -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>
--- a/doc/docbook-xsl/common.xsl
+++ b/doc/docbook-xsl/common.xsl
@ -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>
--- a/doc/docbook-xsl/fo.xsl
+++ b/doc/docbook-xsl/fo.xsl
@ -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>
--- a/doc/docbook-xsl/htmlhelp.xsl
+++ b/doc/docbook-xsl/htmlhelp.xsl
@ -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>
--- a/doc/docbook-xsl/manpage-sp.patch
+++ b/doc/docbook-xsl/manpage-sp.patch
@ -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 -->
--- a/doc/docbook-xsl/manpage.xsl
+++ b/doc/docbook-xsl/manpage.xsl
@ -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>
--- a/doc/docbook-xsl/shaded-literallayout.patch
+++ b/doc/docbook-xsl/shaded-literallayout.patch
@ -0,0 +1,32 @@
 diff -u fo.ORIG/param.xsl fo/param.xsl
 --- fo.ORIG/param.xsl	2005-11-30 19:22:15.992409173 +1300
 +++ fo/param.xsl	2005-11-30 11:25:40.000000000 +1300
@@ -669,6 +669,7 @@
 </xsl:attribute-set>
 <xsl:param name="segmentedlist.as.table" select="0"/>
 <xsl:param name="shade.verbatim" select="0"/>
 +<xsl:param name="shade.literallayout" select="0"/>
 <xsl:attribute-set name="shade.verbatim.style">
   <xsl:attribute name="background-color">#E0E0E0</xsl:attribute>
 diff -u fo.ORIG/verbatim.xsl fo/verbatim.xsl
 --- fo.ORIG/verbatim.xsl	2005-11-30 19:22:15.944415115 +1300
 +++ fo/verbatim.xsl	2005-11-30 11:26:12.000000000 +1300
@@ -105,7 +105,7 @@
   <xsl:choose>
     <xsl:when test="@class='monospaced'">
       <xsl:choose>
 -        <xsl:when test="$shade.verbatim != 0">
 +        <xsl:when test="$shade.literallayout != 0">
           <fo:block id="{$id}"
                     white-space-collapse='false'
                     white-space-treatment='preserve'
@@ -128,7 +128,7 @@
     </xsl:when>
     <xsl:otherwise>
       <xsl:choose>
 -        <xsl:when test="$shade.verbatim != 0">
 +        <xsl:when test="$shade.literallayout != 0">
           <fo:block id="{$id}"
                     wrap-option='no-wrap'
                     white-space-collapse='false'
--- a/doc/docbook-xsl/xhtml.xsl
+++ b/doc/docbook-xsl/xhtml.xsl
@ -0,0 +1,14 @@
 <!--
  Generates single XHTML 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/xhtml/docbook.xsl"/>
 <xsl:import href="common.xsl"/>
 </xsl:stylesheet>