Mercurial > geeqie
diff doc/wiki2docbook/html2db/ar01s07.html @ 1773:2ae81598b254
scripts for converting wiki documentation to docbook
| author | nadvornik |
|---|---|
| date | Sun, 22 Nov 2009 09:12:22 +0000 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/wiki2docbook/html2db/ar01s07.html Sun Nov 22 09:12:22 2009 +0000 @@ -0,0 +1,73 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Specification</title><meta content="DocBook XSL Stylesheets V1.65.1" name="generator"><link rel="home" href="index.html" title="html2db.xsl"><link rel="up" href="index.html" title="html2db.xsl"><link rel="previous" href="ar01s06.html" title="Usage"><link rel="next" href="ar01s08.html" title="Customization"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Specification</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ar01s06.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ar01s08.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N100DB"></a>Specification</h2></div></div><div></div></div><p></p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N100DF"></a>XHTML Elements</h3></div></div><div></div></div><p><tt class="literal">code/i</tt> stands for "an <tt class="literal">i</tt> element +immediately within a <tt class="literal">code</tt> element". This notation is +from XPath.</p><p>XHTML elements must be in the XHTML Transitional namespace, +<tt class="literal">http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd</tt>.</p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>XHTML</th><th>Docbook</th><th>Notes</th></tr></thead><tbody><tr><td><tt class="literal">b</tt>, <tt class="literal">i</tt>, <tt class="literal">em</tt>, <tt class="literal">strong</tt></td><td><tt class="literal">emphasis</tt></td><td>The <tt class="literal">role</tt> attribute is the original tag name</td></tr><tr><td><tt class="literal">dfn</tt></td><td><tt class="literal">glossitem</tt>, and also <tt class="literal">primary</tt><tt class="literal">indexterm</tt></td><td class="auto-generated"> </td></tr><tr><td><tt class="literal">code/i</tt>, <tt class="literal">tt/i</tt>, <tt class="literal">pre/i</tt></td><td><tt class="literal">replaceable</tt></td><td>In practice, <tt class="literal">i</tt> within a monospace content is usually used to mean replaceable text. If you're using it for emphasis, use <tt class="literal">em</tt> instead.</td></tr><tr><td><tt class="literal">pre</tt>, <tt class="literal">body/code</tt></td><td><tt class="literal">programlisting</tt></td><td class="auto-generated"> </td></tr><tr><td><tt class="literal">img</tt></td><td><tt class="literal">inlinemediaobject/imageobject/imagedata</tt></td><td>In an inline context.</td></tr><tr><td><tt class="literal">img</tt></td><td><tt class="literal">[informal]figure/mediaobject/imageobject/imagedata</tt></td><td>If it has a <tt class="literal">title</tt> attribute or <tt class="literal">db:title</tt> it's wrapped in a <tt class="literal">figure</tt>. Otherwise it's wrapped in an <tt class="literal">informalfigure</tt>.</td></tr><tr><td><tt class="literal">table</tt></td><td><tt class="literal">[informal]table</tt></td><td>XHTML <tt class="literal">table</tt> becomes Docbook <tt class="literal">table</tt> if it has a <tt class="literal">summary</tt> attribute; <tt class="literal">informaltable</tt> otherwise.</td></tr><tr><td><tt class="literal">ul</tt></td><td><tt class="literal">itemizedlist</tt></td><td>But see the processing instruction <a href="ar01s08.html#simplelist">below</a>.</td></tr></tbody></table></div><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1017E"></a>Links</h3></div></div><div></div></div><div class="table"><a name="N10181"></a><p class="title"><b>Table 1. Link Translation</b></p><table summary="Link Translation" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>XHTML</th><th>Docbook</th><th>Notes</th></tr></thead><tbody><tr><td><tt class="literal"><a name="<i class="replaceable"><tt>name</tt></i>"></tt></td><td><tt class="literal"><anchor id="{$anchor-id-prefix}<i class="replaceable"><tt>name</tt></i>"></tt></td><td>An anchor within a <tt class="literal">h<i class="replaceable"><tt>n</tt></i></tt> element is attached to the enclosing <tt class="literal">section</tt> as an <tt class="literal">id</tt> attribute instead.</td></tr><tr><td><tt class="literal"><a href="#<i class="replaceable"><tt>name</tt></i>"></tt></td><td><tt class="literal"><link linkend="{$anchor-id-prefix}<i class="replaceable"><tt>name</tt></i>"></tt></td><td class="auto-generated"> </td></tr><tr><td><tt class="literal"><a href="<i class="replaceable"><tt>url</tt></i>"></tt></td><td><tt class="literal"><ulink url="<i class="replaceable"><tt>name</tt></i>"></tt></td><td class="auto-generated"> </td></tr><tr><td><tt class="literal"><a name="mailto:<i class="replaceable"><tt>address</tt></i>"></tt></td><td><tt class="literal"><email><i class="replaceable"><tt>address</tt></i></email></tt></td><td class="auto-generated"> </td></tr></tbody></table></div><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tables"></a>Tables</h3></div></div><div></div></div><p>XHTML <tt class="literal">table</tt> support is minimal. <tt class="literal">html2db.xsl</tt> changes the +element names and counts the columns (this is necessary to get table +footnotes to span all the columns), but it does not attempt to deal +with tables in their full generality.</p><p>An XHTML <tt class="literal">table</tt> with a <tt class="literal">summary</tt> attribute +generates a <tt class="literal">table</tt>, whose <tt class="literal">title</tt> is the value +of that summary. An XHTML <tt class="literal">table</tt> without a +<tt class="literal">summary</tt> generates an <tt class="literal">informaltable</tt>.</p><p>Any <tt class="literal">tr</tt>s that contain <tt class="literal">th</tt>s are pulled to +the top of the table, and placed inside a <tt class="literal">thead</tt>. Other +<tt class="literal">tr</tt>s are placed inside a <tt class="literal">tbody</tt>. This matches +the commanon XHTML <tt class="literal">table</tt> pattern, where the first row is +a header row.</p><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="implicit-blocks"></a>Implicit Blocks</h3></div></div><div></div></div><p>XHTML allows <tt class="literal">li</tt>, <tt class="literal">dd</tt>, and <tt class="literal">td</tt> +elements to contain either inline text (for instance, +<tt class="literal"><li>a list item</li></tt>) or block structure +(<tt class="literal"><li><p>a block</p></li></tt>). The +corresponding Docbook elements require block structure, such as +<tt class="literal">para</tt>.</p><p><tt class="literal">html2db.xsl</tt> provides limited support for wrapping naked text in +these positions in <tt class="literal">para</tt> elements. If a list item or +table cell item directly contains text, all text up to the position of +the first element (or all text, if there is no element) is wrapped in +<tt class="literal">para</tt>. This handles the simple case of an item that +directly contains text, and also the case of an item that contains +text followed by blocks such as paragraphs.</p><p>Note that this algorithm is easily confused. It doesn't +distinguish between block and inline XHTML elements, so it will only +wrap the first word in <tt class="literal"><li>some <b>bold</b> +text</li></tt>, leading to badly formatted output. Twhe +workaround is to wrap troublesome content in explicit +<tt class="literal"><p></tt> tags.</p><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="docbook-elements"></a>Docbook Elements</h3></div></div><div></div></div><p>Elements from the Docbook namespace are passed through as is. +There are two ways to include a Docbook element in your XHTML +source:</p><div class="variablelist"><dl><dt><span class="term">Global prefix</span></dt><dd><p>A <a name="N10241" class="indexterm"></a><i class="glossterm">fake Docbook namespace</i><sup>[<a href="#ftn.N10247" name="N10247">2</a>]</sup> + +declaration may be added to the document root element. Anywhere in +the document, the prefix from this namespace declaration may be used +to include a Docbook element. This is useful if a document contains +many Docbook elements, such as <tt class="literal">footnote</tt> or +<tt class="literal">glossterm</tt>, interspersed with XHTML. (In this case it may +be more convenient to allow these elements in the XHMTL namespace and +add a customization layer that translates them to docbook elements, +however. See <a href="ar01s08.html" title="Customization">Customization</a>.)</p><div class="informalexample"><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting"> +<html xmlns="http://www.w3.org/1999/xhtml" + xmlns:db="urn:docbook"> + ... + <p>Some text<db:footnote>and a footnote</db:footnote>.</p> +</pre></td></tr></table></div></dd><dt><span class="term">Local namespace</span></dt><dd><p>A Docbook element may be introduced along with a prefix-less +namespace declaration. This is useful for embedding a Docbook +document fragment (a hierarchy of elements that all use Docbook tags) +within of a XHTML document.</p><div class="informalexample"><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting"> + ... + <articleinfo xmlns="urn:docbook"> + <author> + <firstname>...</firstname> + ... +</pre></td></tr></table></div></dd></dl></div><p>The source to <a href="index.src.html" target="_top">this document</a> +illustrates both of these techniques.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Both these techniques will cause your document to be +invalid as XHTML. In order to validate an XHTML document that +contains Docbook elements, you will need to create a custom schema. +Technically, you then ought to place your document in a different +namespace, but this will cause <tt class="literal">html2db.xsl</tt> not to recognize it!</p></div><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10275"></a>Output Processing Instructions</h3></div></div><div></div></div><p><tt class="literal">html2db.xsl</tt> adds a few of processing instructions to the output file. +The Docbook XSL stylesheets ignore these, but if you write a +customization layer for Docbook XSL, you can use the information in +these processing instructions to customize the HTML output. This can +be used, for example, to set the <tt class="literal">a</tt> <tt class="literal">onclick</tt> +and <tt class="literal">target</tt> attributes in the HTML files that Docbook XSL +creates to the same values they had in the input document.</p><div class="variablelist"><dl><dt><span class="term"><tt class="literal"><?html2db attribute="<i class="replaceable"><tt>name</tt></i>" value="<i class="replaceable"><tt>value</tt></i>"?></tt></span></dt><dd><p>Placed inside a link element to capture the value of the <tt class="literal">a</tt> <tt class="literal">target</tt> and <tt class="literal">onclick</tt> attributes. <i class="replaceable"><tt>name</tt></i> is the name of the attribute (<tt class="literal">target</tt> or <tt class="literal">onclick</tt>), and <i class="replaceable"><tt>value</tt></i> is its value, with <tt class="literal">"</tt> and <tt class="literal">\</tt> replaced by <tt class="literal">\"</tt> and <tt class="literal">\\</tt>, respectively.</p></dd><dt><span class="term"><tt class="literal"><?html2db element="br"?></tt></span></dt><dd><p>Represents the location of an XHTML <tt class="literal">br</tt> element in the +source document.</p></dd></dl></div><p>You can also include <tt class="literal"><?db2html?></tt> processing +instructions in the HTML source document, and they will be copied +through to the Docbook output file unchanged (as will all other +processing instructions).</p><p></p></div><div class="footnotes"><br><hr align="left" width="100"><div class="footnote"><p><sup>[<a href="#N10247" name="ftn.N10247">2</a>] </sup>The fake +Docbook namespace is <tt class="literal">urn:docbook</tt>. Docbook doesn't really +have a namespace, and if it did, it wouldn't be this one. See <a href="ar01s10.html#docbook-namespace" title="The Docbook Namespace">Docbook namespace</a> for a discussion of +this issue.</p></div></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ar01s06.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ar01s08.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Usage </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Customization</td></tr></table></div></body></html> \ No newline at end of file