Add the documentation.

3 files changed, 133 insertions, 0 deletions

diff --git a/doc/asciidoc/dblatex/asciidoc-dblatex.sty b/doc/asciidoc/dblatex/asciidoc-dblatex.sty
new file mode 100644
index 0000000..9d89839
--- /dev/null
+++ b/doc/asciidoc/dblatex/asciidoc-dblatex.sty
@@ -0,0 +1,20 @@
+%%
+%% This style is derived from the docbook one.
+%%
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{asciidoc}[2008/06/05 AsciiDoc DocBook Style]
+%% Just use the original package and pass the options.
+\RequirePackageWithOptions{docbook}
+
+% Sidebar is a boxed minipage that can contain verbatim.
+% Changed shadow box to double box.
+\renewenvironment{sidebar}[1][0.95\textwidth]{
+  \hspace{0mm}\newline%
+  \noindent\begin{Sbox}\begin{minipage}{#1}%
+  \setlength\parskip{\medskipamount}%
+}{
+  \end{minipage}\end{Sbox}\doublebox{\TheSbox}%
+}
+
+% For DocBook literallayout elements, see `./dblatex/dblatex-readme.txt`.
+\usepackage{alltt}
diff --git a/doc/asciidoc/dblatex/asciidoc-dblatex.xsl b/doc/asciidoc/dblatex/asciidoc-dblatex.xsl
new file mode 100644
index 0000000..3df2d2e
--- /dev/null
+++ b/doc/asciidoc/dblatex/asciidoc-dblatex.xsl
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!--
+dblatex(1) XSL user stylesheet for asciidoc(1).
+See dblatex(1) -p option.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+  <!-- TOC links in the titles, and in blue. -->
+  <xsl:param name="latex.hyperparam">colorlinks,linkcolor=blue,pdfstartview=FitH</xsl:param>
+  <xsl:param name="doc.publisher.show">1</xsl:param>
+  <xsl:param name="doc.lot.show"></xsl:param>
+  <xsl:param name="term.breakline">1</xsl:param>
+  <xsl:param name="doc.collab.show">0</xsl:param>
+  <xsl:param name="doc.section.depth">3</xsl:param>
+  <xsl:param name="table.in.float">0</xsl:param>
+  <xsl:param name="monoseq.hyphenation">0</xsl:param>
+  <xsl:param name="latex.output.revhistory">1</xsl:param>
+
+  <!-- This doesn't work, don't know why, see:
+  http://dblatex.sourceforge.net/html/manual/apas03.html
+  ./docbook-xsl/common.xsl
+  -->
+  <!--
+  <xsl:param name="doc.toc.show">
+    <xsl:choose>
+      <xsl:when test="/processing-instruction('asciidoc-toc')">
+1
+      </xsl:when>
+      <xsl:otherwise>
+0
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:param>
+  <xsl:param name="doc.lot.show">
+    <xsl:choose>
+      <xsl:when test="/book">
+figure,table,equation,example
+      </xsl:when>
+    </xsl:choose>
+  </xsl:param>
+  -->
+  <xsl:param name="doc.toc.show">1</xsl:param>
+
+  <!--
+    Override default literallayout template.
+    See `./dblatex/dblatex-readme.txt`.
+  -->
+  <xsl:template match="address|literallayout[@class!='monospaced']">
+    <xsl:text>\begin{alltt}</xsl:text>
+    <xsl:text>&#10;\normalfont{}&#10;</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;\end{alltt}</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="processing-instruction('asciidoc-pagebreak')">
+    <!-- force hard pagebreak, varies from 0(low) to 4(high) -->
+    <xsl:text>\pagebreak[4] </xsl:text>
+    <xsl:apply-templates />
+    <xsl:text>&#10;</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="processing-instruction('asciidoc-br')">
+    <xsl:text>\newline&#10;</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="processing-instruction('asciidoc-hr')">
+    <!-- draw a 444 pt line (centered) -->
+    <xsl:text>\begin{center}&#10; </xsl:text>
+    <xsl:text>\line(1,0){444}&#10; </xsl:text>
+    <xsl:text>\end{center}&#10; </xsl:text>
+  </xsl:template>
+
+</xsl:stylesheet>
+
diff --git a/doc/asciidoc/dblatex/dblatex-readme.txt b/doc/asciidoc/dblatex/dblatex-readme.txt
new file mode 100644
index 0000000..39bb437
--- /dev/null
+++ b/doc/asciidoc/dblatex/dblatex-readme.txt
@@ -0,0 +1,39 @@
+AsciiDoc dblatex README
+=======================
+
+Customization
+-------------
+The `./dblatex` directory contains:
+
+`./dblatex/asciidoc-dblatex.xsl`:: Optional dblatex XSL parameter
+customization.
+
+`./dblatex/asciidoc-dblatex.sty`:: Optional customized LaTeX styles.
+
+Use these files with dblatex(1) `-p` and `-s` options, for example:
+
+  dblatex -p ../dblatex/asciidoc-dblatex.xsl \
+          -s ../dblatex/asciidoc-dblatex.sty article.xml
+
+
+Limitations
+-----------
+Observed in dblatex 0.2.8.
+
+- dblatex doesn't seem to process the DocBook 'literallayout' element
+  correctly: it is rendered in a monospaced font and no inline
+  elements are processed. By default the normal font should be used
+  and almost all DocBook inline elements should be processed
+  (http://www.docbook.org/tdg/en/html/literallayout.html).  I almost
+  fixed this by overriding the default dblatex literallayout template
+  (in `./dblatex/asciidoc-dblatex.xsl`) and using the LaTeX 'alltt'
+  package, but there are remaining problems:
+
+  * Blank lines are replaced by a single space.
+  * The 'literallayout' element incorrectly wraps text when rendered
+    inside a table.
+
+- Callouts do not work inside DocBook 'literallayout' elements which
+  means callouts are not displayed inside AsciiDoc literal blocks.  A
+  workaround is to change the AsciiDoc literal block to a listing
+  block.