[geeqie.git] / doc / wiki2docbook / html2db / index.xml

<?xml version="1.0" encoding="UTF-8"?>\r
<article>\r
\r
<title>html2db.xsl</title>\r
\r
\r
<articleinfo>\r
  <author>\r
    <firstname>Oliver</firstname>\r
    <surname>Steele</surname>\r
  </author>\r
  <revhistory>\r
    <revision>\r
      <revnumber>1</revnumber>\r
      <date>2004-07-30</date>\r
    </revision>\r
    <revision>\r
      <revnumber>1.0.1</revnumber>\r
      <date>2004-08-01</date>\r
      <revdescription><para>Editorial changes to the\r
      readme.</para></revdescription>\r
    </revision>\r
  </revhistory>\r
  <date>2004-07-30</date>\r
</articleinfo>\r
\r
<para/><section><title>Overview</title>\r
\r
<para><literal>html2db.xsl</literal> converts an XHTML source document into a Docbook output\r
document.  It provides features for customizing the generation of the\r
output, so that the output can be tuned by annotating\r
the source, rather than hand-editing the output.  This makes it useful\r
in a processing pipeline where the source documents are maintained in\r
HTML, although it can be used as a one-time conversion tool\r
too.</para>\r
\r
<para>This document is an example of <literal>html2db.xsl</literal> used in conjunction with\r
the Docbook XSL stylesheets.  The <ulink url="index.src.html">source\r
file</ulink> is an XHTML file with some embedded Docbook elements and\r
processing instructions.  <literal>html2db.xsl</literal> compiles it into a <ulink url="index.xml">Docbook document</ulink>, which can be used to generate\r
this output file (which includes a Table of Contents), a <ulink url="docs/index.html">chunked HTML file</ulink>, a <ulink url="html2db.pdf">PDF</ulink>, or other formats.</para>\r
\r
<para/></section><section><title>Features</title>\r
<variablelist><varlistentry><term>XSLT implementation</term><listitem><para>This tool is designed to be embedded within an XSLT processing\r
pipeline.  <literal>html2html.xslt</literal> can be used in a custom\r
stylesheet or integrated into a larger system.  See <link linkend="embedding">Overriding</link>.</para></listitem></varlistentry><varlistentry><term>Customizable</term><listitem><para>The output can be customized by the means of additonal markup in\r
the XHMTL source.  See the section on <link linkend="customization">customization</link>.</para></listitem></varlistentry><varlistentry><term>Creates outline structure</term><listitem><para><literal>h1</literal>, <literal>h2</literal>, etc. are turned into nested\r
<literal>section</literal> and <literal>title</literal> elements (as opposed to\r
bridge heads).</para></listitem></varlistentry><varlistentry><term>Accepts a wide variety of XHTML</term><listitem><para>In particular, <literal>html2db.xsl</literal> automatically wraps <indexterm significance="preferred"><primary>naked item\r
text</primary></indexterm><glossterm>naked item\r
text</glossterm> (text that is not enclosed in a <literal>&lt;p&gt;</literal>)\r
inside a table cell or list item.  Naked text is a common property of\r
XHTML documents, but needs to be clothed to create valid\r
Docbook.<footnote><para>This feature is limited.  See <link linkend="implicit-blocks">Implicit Blocks</link>.)</para></footnote></para></listitem></varlistentry></variablelist>\r
\r
<para/></section><section><title>Requirements</title>\r
<itemizedlist spacing="compact"><listitem><para>Java: JRE or JDK 1.3 or greater.</para></listitem><listitem><para>Xalan 2.5.0.</para></listitem><listitem><para>Familiarity with installing and running JAR files.</para></listitem></itemizedlist>\r
\r
<para><literal>html2db.xsl</literal> might work with earlier versions of Java and Xalan, and\r
it might work with other XSLT processors such as Saxon and\r
xsltproc.</para>\r
\r
<para/></section><section><title>License</title>\r
<para>This software is released under the Open Source <ulink url="http://www.opensource.org/licenses/artistic-license.php">Artistic License</ulink>.</para>\r
\r
<para/></section><section><title>Installation</title>\r
<itemizedlist spacing="compact"><listitem><para>Install JRE 1.3 or higher.</para></listitem><listitem><para>Install Xalan, if necessary.</para></listitem><listitem><para>Download <literal>html2db-1.zip</literal> from <ulink url="http://osteele.com/sources/html2db.zip">http://osteele.com/sources/html2db-1.zip</ulink>.</para></listitem><listitem><para>Unzip <literal>html2db-1.zip</literal>.</para></listitem></itemizedlist>\r
\r
<para/></section><section><title>Usage</title>\r
<para>Use Xalan to process an XHTML source file into a Docbook file:</para>\r
\r
<informalexample><programlisting>\r
java org.apache.xalan.xslt.Process -XSL html2dbk.xsl -IN doc.html &gt; doc.xml\r
</programlisting></informalexample>\r
\r
<para>See <ulink url="index.src.html"><literal>index.src.html</literal></ulink> for an\r
example of an input file.</para>\r
\r
<para>If your source files are in HTML, not XHTML, you may find the <ulink url="http://tidy.sourceforge.net/">Tidy</ulink> tool useful.  This is a\r
tool that converts from HTML to XHTML, and can be added to the front\r
of your processing pipeline.</para>\r
\r
<para>(If you need to process HTML and you don't know or can't figure out\r
from context what a processing pipeline is, <literal>html2db.xsl</literal> is probably not\r
the right tool for you, and you should look for a local XML or Java\r
guru or for a commercially supported product.)</para>\r
\r
<para/></section><section><title>Specification</title>\r
\r
<para/><section><title>XHTML Elements</title>\r
<para><literal>code/i</literal> stands for "an <literal>i</literal> element\r
immediately within a <literal>code</literal> element".  This notation is\r
from XPath.</para>\r
\r
<para>XHTML elements must be in the XHTML Transitional namespace,\r
<literal>http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd</literal>.</para>\r
\r
<informaltable><tgroup cols="3"><thead><row><entry>XHTML</entry><entry>Docbook</entry><entry>Notes</entry></row>\r
</thead><tbody><row><entry><literal>b</literal>, <literal>i</literal>, <literal>em</literal>, <literal>strong</literal></entry><entry><literal>emphasis</literal></entry><entry>The <literal>role</literal> attribute is the original tag name</entry></row>\r
<row><entry><literal>dfn</literal></entry><entry><literal>glossitem</literal>, and also <literal>primary</literal> <literal>indexterm</literal></entry></row>\r
<row><entry><literal>code/i</literal>, <literal>tt/i</literal>, <literal>pre/i</literal></entry><entry><literal>replaceable</literal></entry><entry>In practice, <literal>i</literal> within a monospace content is usually used to mean replaceable text.  If you're using it for emphasis, use <literal>em</literal> instead.</entry></row>\r
<row><entry><literal>pre</literal>, <literal>body/code</literal></entry><entry><literal>programlisting</literal></entry></row>\r
<row><entry><literal>img</literal></entry><entry><literal>inlinemediaobject/imageobject/imagedata</literal></entry><entry>In an inline context.</entry></row>\r
<row><entry><literal>img</literal></entry><entry><literal>[informal]figure/mediaobject/imageobject/imagedata</literal></entry><entry>If it has a <literal>title</literal> attribute or <literal>db:title</literal> it's wrapped in a <literal>figure</literal>.  Otherwise it's wrapped in an <literal>informalfigure</literal>.</entry></row>\r
<row><entry><literal>table</literal></entry><entry><literal>[informal]table</literal></entry><entry>XHTML <literal>table</literal> becomes Docbook <literal>table</literal> if it has a <literal>summary</literal> attribute; <literal>informaltable</literal> otherwise.</entry></row>\r
<row><entry><literal>ul</literal></entry><entry><literal>itemizedlist</literal></entry><entry>But see the processing instruction <link linkend="simplelist">below</link>.</entry></row>\r
</tbody></tgroup></informaltable>\r
\r
\r
\r
<para/></section><section><title>Links</title>\r
<table><title>Link Translation</title><tgroup cols="3"><thead><row><entry>XHTML</entry><entry>Docbook</entry><entry>Notes</entry></row>\r
</thead><tbody><row><entry><literal>&lt;a name="<replaceable>name</replaceable>"&gt;</literal></entry><entry><literal>&lt;anchor id="{$anchor-id-prefix}<replaceable>name</replaceable>"&gt;</literal></entry><entry>An anchor within a <literal>h<replaceable>n</replaceable></literal> element is attached to the enclosing <literal>section</literal> as an <literal>id</literal> attribute instead.</entry></row>\r
<row><entry><literal>&lt;a href="#<replaceable>name</replaceable>"&gt;</literal></entry><entry><literal>&lt;link linkend="{$anchor-id-prefix}<replaceable>name</replaceable>"&gt;</literal></entry></row>\r
<row><entry><literal>&lt;a href="<replaceable>url</replaceable>"&gt;</literal></entry><entry><literal>&lt;ulink url="<replaceable>name</replaceable>"&gt;</literal></entry></row>\r
<row><entry><literal>&lt;a name="mailto:<replaceable>address</replaceable>"&gt;</literal></entry><entry><literal>&lt;email&gt;<replaceable>address</replaceable>&lt;/email&gt;</literal></entry></row>\r
</tbody></tgroup></table>\r
\r
<para/></section><section id="tables"><title>Tables</title>\r
\r
<para>XHTML <literal>table</literal> support is minimal.  <literal>html2db.xsl</literal> changes the\r
element names and counts the columns (this is necessary to get table\r
footnotes to span all the columns), but it does not attempt to deal\r
with tables in their full generality.</para>\r
\r
<para>An XHTML <literal>table</literal> with a <literal>summary</literal> attribute\r
generates a <literal>table</literal>, whose <literal>title</literal> is the value\r
of that summary.  An XHTML <literal>table</literal> without a\r
<literal>summary</literal> generates an <literal>informaltable</literal>.</para>\r
\r
<para>Any <literal>tr</literal>s that contain <literal>th</literal>s are pulled to\r
the top of the table, and placed inside a <literal>thead</literal>.  Other\r
<literal>tr</literal>s are placed inside a <literal>tbody</literal>.  This matches\r
the commanon XHTML <literal>table</literal> pattern, where the first row is\r
a header row.</para>\r
\r
<para/></section><section id="implicit-blocks"><title>Implicit Blocks</title>\r
<para>XHTML allows <literal>li</literal>, <literal>dd</literal>, and <literal>td</literal>\r
elements to contain either inline text (for instance,\r
<literal>&lt;li&gt;a list item&lt;/li&gt;</literal>) or block structure\r
(<literal>&lt;li&gt;&lt;p&gt;a block&lt;/p&gt;&lt;/li&gt;</literal>).  The\r
corresponding Docbook elements require block structure, such as\r
<literal>para</literal>.</para>\r
\r
<para><literal>html2db.xsl</literal> provides limited support for wrapping naked text in\r
these positions in <literal>para</literal> elements.  If a list item or\r
table cell item directly contains text, all text up to the position of\r
the first element (or all text, if there is no element) is wrapped in\r
<literal>para</literal>.  This handles the simple case of an item that\r
directly contains text, and also the case of an item that contains\r
text followed by blocks such as paragraphs.</para>\r
\r
<para>Note that this algorithm is easily confused.  It doesn't\r
distinguish between block and inline XHTML elements, so it will only\r
wrap the first word in <literal>&lt;li&gt;some &lt;b&gt;bold&lt;/b&gt;\r
text&lt;/li&gt;</literal>, leading to badly formatted output.  Twhe\r
workaround is to wrap troublesome content in explicit\r
<literal>&lt;p&gt;</literal> tags.</para>\r
\r
<para/></section><section id="docbook-elements"><title>Docbook Elements</title>\r
\r
<para>Elements from the Docbook namespace are passed through as is.\r
There are two ways to include a Docbook element in your XHTML\r
source:</para>\r
\r
<variablelist><varlistentry><term>Global prefix</term><listitem><para>A <indexterm significance="preferred"><primary>fake Docbook namespace</primary></indexterm><glossterm>fake Docbook namespace</glossterm><footnote><para>The fake\r
Docbook namespace is <literal>urn:docbook</literal>.  Docbook doesn't really\r
have a namespace, and if it did, it wouldn't be this one.  See <link linkend="docbook-namespace">Docbook namespace</link> for a discussion of\r
this issue.</para></footnote>\r
\r
declaration may be added to the document root element.  Anywhere in\r
the document, the prefix from this namespace declaration may be used\r
to include a Docbook element.  This is useful if a document contains\r
many Docbook elements, such as <literal>footnote</literal> or\r
<literal>glossterm</literal>, interspersed with XHTML.  (In this case it may\r
be more convenient to allow these elements in the XHMTL namespace and\r
add a customization layer that translates them to docbook elements,\r
however.  See <link linkend="customization">Customization</link>.)</para>\r
\r
<informalexample><programlisting>\r
&lt;html xmlns="http://www.w3.org/1999/xhtml"\r
      xmlns:db="urn:docbook"&gt;\r
  ...\r
  &lt;p&gt;Some text&lt;db:footnote&gt;and a footnote&lt;/db:footnote&gt;.&lt;/p&gt;\r
</programlisting></informalexample></listitem></varlistentry><varlistentry><term>Local namespace</term><listitem><para>A Docbook element may be introduced along with a prefix-less\r
namespace declaration.  This is useful for embedding a Docbook\r
document fragment (a hierarchy of elements that all use Docbook tags)\r
within of a XHTML document.</para>\r
\r
<informalexample><programlisting>\r
  ...\r
  &lt;articleinfo xmlns="urn:docbook"&gt;\r
    &lt;author&gt;\r
      &lt;firstname&gt;...&lt;/firstname&gt;\r
  ...\r
</programlisting></informalexample></listitem></varlistentry></variablelist>\r
\r
<para>The source to <ulink url="index.src.html">this document</ulink>\r
illustrates both of these techniques.</para>\r
\r
<note><para>Both these techniques will cause your document to be\r
invalid as XHTML.  In order to validate an XHTML document that\r
contains Docbook elements, you will need to create a custom schema.\r
Technically, you then ought to place your document in a different\r
namespace, but this will cause <literal>html2db.xsl</literal> not to recognize it!</para></note>\r
\r
\r
<para/></section><section><title>Output Processing Instructions</title>\r
\r
<para><literal>html2db.xsl</literal> adds a few of processing instructions to the output file.\r
The Docbook XSL stylesheets ignore these, but if you write a\r
customization layer for Docbook XSL, you can use the information in\r
these processing instructions to customize the HTML output.  This can\r
be used, for example, to set the <literal>a</literal> <literal>onclick</literal>\r
and <literal>target</literal> attributes in the HTML files that Docbook XSL\r
creates to the same values they had in the input document.</para>\r
\r
<variablelist><varlistentry><term><literal>&lt;?html2db attribute="<replaceable>name</replaceable>" value="<replaceable>value</replaceable>"?&gt;</literal></term><listitem><para>Placed inside a link element to capture the value of the <literal>a</literal> <literal>target</literal> and <literal>onclick</literal> attributes.  <replaceable>name</replaceable> is the name of the attribute (<literal>target</literal> or <literal>onclick</literal>), and <replaceable>value</replaceable> is its value, with <literal>"</literal> and <literal>\</literal> replaced by <literal>\"</literal> and <literal>\\</literal>, respectively.</para></listitem></varlistentry><varlistentry><term><literal>&lt;?html2db element="br"?&gt;</literal></term><listitem><para>Represents the location of an XHTML <literal>br</literal> element in the\r
source document.</para></listitem></varlistentry></variablelist>\r
\r
<para>You can also include <literal>&lt;?db2html?&gt;</literal> processing\r
instructions in the HTML source document, and they will be copied\r
through to the Docbook output file unchanged (as will all other\r
processing instructions).</para>\r
\r
\r
<para/></section></section><section id="customization"><title>Customization</title>\r
<para/><section><title>XSLT Parameters</title>\r
<variablelist><varlistentry><term><literal>&lt;xsl:param name="anchor-id-prefix" select="''/&gt;</literal></term><listitem><para>Prefixed to every id generated from <literal>&lt;a name=&gt;</literal>\r
  and <literal>&lt;a href="#"&gt;</literal>.  This is useful to avoid\r
  collisions between multiple documents that are compiled into the\r
  same book.  For instance, if a number of XHTML sources are assembled\r
  into chapters of a book, you style each source file with a prefix of\r
  <literal><replaceable>docid</replaceable>.</literal> where <replaceable>docid</replaceable> is a unique id\r
  for each source file.</para></listitem></varlistentry><varlistentry><term><literal>&lt;xsl:param name="document-root" select="'article'"/&gt;</literal></term><listitem><para>The default document root.  This can be overridden by\r
  <literal>&lt;?html2db class="<replaceable>name</replaceable>"&gt;</literal> within the\r
  document itself, and defaults to <literal>article</literal>.</para></listitem></varlistentry></variablelist>\r
\r
<para/></section><section id="processing-instructions"><title>Processing instructions</title>\r
<para>Use the <literal>&lt;?html2db?&gt;</literal> processing instruction to\r
customize the transformation of the XHTML source to Docbook:</para>\r
\r
<informaltable><tgroup cols="3"><thead><row><entry>Processing instruction</entry><entry>Content</entry><entry>Effect</entry></row>\r
</thead><tbody><row><entry><literal>&lt;?html2db class="<replaceable>xxx</replaceable>"?&gt;</literal></entry><entry><literal>body</literal></entry><entry>Sets the output document root to <replaceable>xxx</replaceable>.  Useful for\r
translating to <literal>prefix</literal>, <literal>appendix</literal>, or <literal>chapter</literal>; the default is\r
<replaceable>$document-root</replaceable>.</entry></row>\r
<row id="simplelist"><entry><literal>&lt;?html2db class="simplelist"?&gt;</literal></entry><entry><literal>ul</literal></entry><entry>Creates a vertical <literal>simplelist</literal>.<footnote><para>Note that the\r
current implementation simply checks for the presence of <emphasis role="em">any</emphasis>\r
<literal>html2db</literal> processing instruction.</para></footnote></entry></row>\r
<row><entry><literal>&lt;?html2db rowsep="1"?&gt;</literal></entry><entry><literal>[informal]table</literal></entry><entry>Sets the <literal>rowsep</literal> attribute on the generated <literal>table</literal>.<footnote><para>Note that the current implementation simply checks for the presence of <emphasis role="em">any</emphasis> <literal>html2db</literal> processing instruction that begins with <literal>rowsep</literal>, and assumes the vlaue is <literal>1</literal>.</para></footnote></entry></row>\r
</tbody></tgroup></informaltable>\r
\r
<para/></section><section id="embedding"><title>Overriding the built-in templates</title>\r
<para>For cases where the previous techniques don't allow for enough\r
customization, you can override the builtin templates.  You will need\r
to know XSLT in order to do this, and you will need to write a new\r
stylesheet that uses the <literal>xsl:import</literal> element to import\r
<literal>html2db.xsl</literal>.</para>\r
\r
<para>The <ulink url="examples.xsl"><literal>example.xsl</literal></ulink> stylesheet\r
is an example customization layer.  It recognizes the <literal>&lt;div\r
class="abstract"&gt;</literal> and <literal>&lt;p class="note"&gt;</literal>\r
classes in the <ulink url="index.src.html">source</ulink> for this document,\r
and generates the corresponding Docbook elements.</para>\r
\r
\r
<para/></section></section><section><title>FAQ</title>\r
<para/><section><title>Why generate Docbook?</title>\r
<para>The primary reason to use Docbook as an <emphasis role="em">output</emphasis> format is\r
to take advantage of the Docbook XSL stylesheets.  These are a\r
well-designed, well-documented set of XSL stylesheets that provide a\r
variety of publishing features that would be difficult to recreate\r
from scratch for HTML:</para>\r
\r
<itemizedlist spacing="compact"><listitem><para>Automatic Table-of-Contents generation</para></listitem><listitem><para>Automatic part, chapter, and section numbering.</para></listitem><listitem><para>Creation of single-page, multi-page, PDF, and WinHelp files from the same source document.</para></listitem><listitem><para>Navigation headers, footers, and metadata for multi-page HTML\r
documents.</para></listitem><listitem><para>Link resolution and link target text insertion across multiple pages and numbered targets.</para></listitem><listitem><para>Figure, example, and table numbering, and tables of these.</para></listitem><listitem><para>Index and glossary tools.</para></listitem></itemizedlist>\r
\r
<para/></section><section><title>Why write in XHTML?</title>\r
\r
<para>Given that Docbook is so great, why not write in it?</para>\r
\r
<para>Where there are not legacy concerns, Docbook is probably a better\r
choice for structured or technical documentation.</para>\r
\r
<para>Where the only legacy concern is the documents themselves, and not\r
the tools and skill sets of documentation contributors, you should\r
consider using an (X)HMTL convertor to perform a one-time conversion\r
of your documentation source into Docbook, and then switching\r
development to the result files.  You can use this stylesheet to\r
perform this conversion, or evaluate other tools, many of which are\r
probably appropriate for this purpose.</para>\r
\r
<para>Often there are other legacy concerns: the availability of cheap\r
(including free) and usable HTML editors and editing modes; and the\r
fact that it's easier to teach people XHTML than Docbook.  If either\r
of this is an issue in your organization, you may want to maintain\r
documentation sources in XHTML instead of Docbook</para>\r
\r
<para>For example, at <ulink url="http://www.laszlosystems.com/">Laszlo</ulink>,\r
most developers contribute directly to the documentation.  Requiring\r
that developers learn Docbook, or that they wait on the doc team to\r
get content into the docs, would discourage this.</para>\r
\r
<para/></section><section><title>Why not use an existing convertor?</title>\r
\r
<para>This isn't the first (X)HTML to Docbook convertor.  Why not use one\r
of the exisitng ones?</para>\r
\r
<para>Each HTML to Docbook convertors that I could find had at least some\r
of the following limitations, some of which stemmed from their\r
intended use as one-time-only convertors for legacy documents:</para>\r
\r
<itemizedlist spacing="compact"><listitem><para>Many only operated on a subset of HTML, and relied upon hand\r
editing of the output to clean up mistakes.  This made them impossible\r
to use as part of a processing pipeline, where the source is\r
<emphasis role="em">maintained</emphasis> in XHTML.</para></listitem><listitem><para>There was no way to customize the output, except by (1) hand\r
editing, or (2) writing a post-processing stylesheet, which didn't\r
have access to the information in the XHTML source document.</para></listitem><listitem><para>Many of them were difficult or impossible to customize and\r
extend. They were closed-source, or written in Java or Perl (which I\r
find to be a difficult languages to use for customizing this kind of\r
thing) and embedded in a larger system.</para></listitem><listitem><para>They didn't take full advantage of the Docbook tag set and content\r
model to represent document structure.  For instance, they didn't\r
generate nested <literal>section</literal> elements to represent\r
<literal>h1</literal> <literal>h2</literal> sequences, or <literal>table</literal> to\r
represent tables with <literal>summary</literal> attributes.</para></listitem></itemizedlist>\r
\r
<para/></section><section><title>I got this error.  What does it mean?</title>\r
<variablelist><varlistentry><term>Q. <literal>Fatal Error! The element type "br" must be terminated by the matching end-tag "&lt;/br&gt;".\r
</literal></term><listitem><para>A. Your document is HTML, not <emphasis role="em">X</emphasis>HTML.  You need to fix it, or run it through Tidy first.</para></listitem></varlistentry><varlistentry><term>Q. My output document is empty except for the <literal>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</literal> line.</term><listitem><para>A. The document is missing a namespace declaration.  See the <ulink url="index.src.html">example</ulink> for an example.</para></listitem></varlistentry><varlistentry><term>Q. Some of the headers and document sections are repeated multiple times.</term><listitem><para>A. The document has out-of-sequence headers, such as <literal>h1</literal> followed by <literal>h3</literal> (instead of <literal>h2</literal>).  This won't work.</para></listitem></varlistentry><varlistentry><term>Q. <literal>Fatal Error! The prefix "db" for element "db:footnote" is not bound.</literal></term><listitem><para>A. You haven't declared the <literal>db</literal> namespace prefix.  See the <ulink url="index.src.html">example</ulink> for an example.</para></listitem></varlistentry></variablelist>\r
\r
\r
<para/></section></section><section><title>Implementation Notes</title>\r
\r
<para/><section><title>Bugs</title>\r
<itemizedlist spacing="compact"><listitem><para>Improperly sequenced <literal>h<replaceable>n</replaceable></literal> (for example\r
<literal>h1</literal> followed by <literal>h3</literal>, instead of\r
<literal>h2</literal>) will result in duplicate text.</para></listitem></itemizedlist>\r
\r
\r
<para/></section><section><title>Limitations</title>\r
<itemizedlist spacing="compact"><listitem><para>The <literal>id</literal> attribute is only preserved for certain\r
elements (at least <literal>h<replaceable>n</replaceable></literal>, images, paragraphs, and\r
tables).  It ought to be preserved for all of them.</para></listitem><listitem><para>Only the <link linkend="tables">very simplest</link> table format is\r
implemented.</para></listitem><listitem><para>Always uses compact lists.</para></listitem><listitem><para>The string matching for <literal>&lt;?html2b\r
class="<replaceable>classname</replaceable>"?&gt;</literal> requires an exact match\r
(spaces and all).</para></listitem><listitem><para>The <link linkend="implicit-blocks">implicit blocks</link> code is easily\r
confused, as documented in that section.  This is\r
easy to fix now that I understand the difference between block and\r
inline elements (I didn't when I was implementing this), but I\r
probably won't do so until I run into the problem again.</para></listitem></itemizedlist>\r
\r
\r
\r
\r
<para/></section><section><title>Wishlist</title>\r
<itemizedlist spacing="compact"><listitem><para>Allow <literal>&lt;html2db attribute-name="<replaceable>name</replaceable>"\r
value="<replaceable>value</replaceable>"?&gt;</literal> at any position, to set arbitrary\r
Docbook attributes on the generated element.</para></listitem><listitem><para>Use different technique from the <link linkend="docbook-elements">fake\r
namespace prefix</link> to name Docbook elements in the source, that\r
preserves the XHTML validity of the source file. For example, an\r
option transform <literal>&lt;div class="db:footnote"&gt;</literal> into\r
<literal>&lt;footnote&gt;</literal>, or to use a processing attribute\r
(<literal>&lt;div&gt;&lt;?html2db classname="footnote"?&gt;</literal>).</para></listitem><listitem><para>Parse DC metadata from XHTML <literal>html/head/meta</literal>.</para></listitem><listitem><para>Add an option to use <literal>html/head/title</literal> instead of\r
<literal>html/body/h1[1]</literal> for top title.</para></listitem><listitem><para>Allow an <literal>id</literal> on every element.</para></listitem><listitem><para>Add an option to translate the XHTML <literal>class</literal> into a\r
Docbook <literal>role</literal>.</para></listitem><listitem><para>Preserve more of the whitespace from the source document  especially within lists and tables  in order to make it easier to debug the output document.</para></listitem></itemizedlist>\r
\r
\r
<para/></section><section><title>Design Notes</title>\r
<para/><section id="docbook-namespace"><title>The Docbook Namespace</title>\r
<para><literal>html2db.xsl</literal> accepts elements in the "Docbook namespace" in XHTML\r
source.  This namespace is <literal>urn:docbook</literal>.</para>\r
\r
<para>This isn't technically correct.  Docbook doesn't really have a\r
namespace, and if it did, it wouldn't be this one.  <ulink url="http://www.faqs.org/rfcs/rfc3151.html">RFC 3151</ulink> suggests\r
<literal>urn:publicid:-:OASIS:DTD+DocBook+XML+V4.1.2:EN</literal> as the\r
Docbook namespace.</para>\r
\r
<para>There two problems with the RFC 3151 namespace.  First, it's long\r
and hard to remember.  Second, it's limited to Docbook v4.1.2 \r
but <literal>html2db.xsl</literal> works with other versions of Docbook too, which would\r
presumably have other namespaces.  I think it's more useful to\r
<emphasis role="em">under</emphasis>specify the Docbook version in the spec for this tool.\r
Docbook itself underspecifies the version completely, by avoiding a\r
namespace at all, but when mixing Docbook and XHTML elements I find it\r
useful to be <emphasis role="em">more</emphasis> specific than that.</para>\r
\r
<para/></section></section><section><title>History</title>\r
<para>The original version of <literal>html2db.xsl</literal> was written by <ulink url="http://osteele.com">Oliver Steele</ulink>, as part of the <ulink url="http://laszlosystems.com">Laszlo Systems, Inc.</ulink> documentation\r
effort.  We had a set of custom stylesheets that formatted and added\r
linking information to programming-language elements such as\r
<literal>classname</literal> and <literal>tagname</literal>, and added\r
Table-of-Contents to chapter documentation and numbers examples.</para>\r
\r
<para>As the documentation set grew, the doc team (John Sundman)\r
requested features such as inter-chapter navigation, callouts, and\r
index and glossary elements.  I was able to beat all of these back\r
except for navigation, which seemed critical.  After a few days trying\r
to implement this, I decided it would be simpler to convert the subset\r
of XHTML that we used into a subset of Docbook, and use the latter to\r
add navigation.  (Once this was done, the other features came for\r
free.)</para>\r
\r
<para>During my August 2004 "sabbatical", I factored the general html2db\r
code out from the Laszlo-specific code, refactored and otherwise\r
cleaned it up, and wrote this documentation.</para>\r
\r
<para/></section><section><title>Credits</title>\r
<para><literal>html2db.xsl</literal> was written by <ulink url="http://osteele.com">Oliver Steele</ulink>, as part of the <ulink url="http://laszlosystems.com">Laszlo Systems, Inc.</ulink> documentation effort.</para>\r
\r
<para/></section></section></article>