Mercurial > geeqie
diff doc/wiki2docbook/html2db/ar01s09.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/ar01s09.html Sun Nov 22 09:12:22 2009 +0000 @@ -0,0 +1,36 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>FAQ</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="ar01s08.html" title="Customization"><link rel="next" href="ar01s10.html" title="Implementation Notes"></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">FAQ</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ar01s08.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ar01s10.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="N10378"></a>FAQ</h2></div></div><div></div></div><p></p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1037C"></a>Why generate Docbook?</h3></div></div><div></div></div><p>The primary reason to use Docbook as an <span class="em">output</span> format is +to take advantage of the Docbook XSL stylesheets. These are a +well-designed, well-documented set of XSL stylesheets that provide a +variety of publishing features that would be difficult to recreate +from scratch for HTML:</p><div class="itemizedlist"><ul type="disc" compact="compact"><li><p>Automatic Table-of-Contents generation</p></li><li><p>Automatic part, chapter, and section numbering.</p></li><li><p>Creation of single-page, multi-page, PDF, and WinHelp files from the same source document.</p></li><li><p>Navigation headers, footers, and metadata for multi-page HTML +documents.</p></li><li><p>Link resolution and link target text insertion across multiple pages and numbered targets.</p></li><li><p>Figure, example, and table numbering, and tables of these.</p></li><li><p>Index and glossary tools.</p></li></ul></div><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1039D"></a>Why write in XHTML?</h3></div></div><div></div></div><p>Given that Docbook is so great, why not write in it?</p><p>Where there are not legacy concerns, Docbook is probably a better +choice for structured or technical documentation.</p><p>Where the only legacy concern is the documents themselves, and not +the tools and skill sets of documentation contributors, you should +consider using an (X)HMTL convertor to perform a one-time conversion +of your documentation source into Docbook, and then switching +development to the result files. You can use this stylesheet to +perform this conversion, or evaluate other tools, many of which are +probably appropriate for this purpose.</p><p>Often there are other legacy concerns: the availability of cheap +(including free) and usable HTML editors and editing modes; and the +fact that it's easier to teach people XHTML than Docbook. If either +of this is an issue in your organization, you may want to maintain +documentation sources in XHTML instead of Docbook</p><p>For example, at <a href="http://www.laszlosystems.com/" target="_top">Laszlo</a>, +most developers contribute directly to the documentation. Requiring +that developers learn Docbook, or that they wait on the doc team to +get content into the docs, would discourage this.</p><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103AF"></a>Why not use an existing convertor?</h3></div></div><div></div></div><p>This isn't the first (X)HTML to Docbook convertor. Why not use one +of the exisitng ones?</p><p>Each HTML to Docbook convertors that I could find had at least some +of the following limitations, some of which stemmed from their +intended use as one-time-only convertors for legacy documents:</p><div class="itemizedlist"><ul type="disc" compact="compact"><li><p>Many only operated on a subset of HTML, and relied upon hand +editing of the output to clean up mistakes. This made them impossible +to use as part of a processing pipeline, where the source is +<span class="em">maintained</span> in XHTML.</p></li><li><p>There was no way to customize the output, except by (1) hand +editing, or (2) writing a post-processing stylesheet, which didn't +have access to the information in the XHTML source document.</p></li><li><p>Many of them were difficult or impossible to customize and +extend. They were closed-source, or written in Java or Perl (which I +find to be a difficult languages to use for customizing this kind of +thing) and embedded in a larger system.</p></li><li><p>They didn't take full advantage of the Docbook tag set and content +model to represent document structure. For instance, they didn't +generate nested <tt class="literal">section</tt> elements to represent +<tt class="literal">h1</tt> <tt class="literal">h2</tt> sequences, or <tt class="literal">table</tt> to +represent tables with <tt class="literal">summary</tt> attributes.</p></li></ul></div><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103D8"></a>I got this error. What does it mean?</h3></div></div><div></div></div><div class="variablelist"><dl><dt><span class="term">Q. <tt class="literal">Fatal Error! The element type "br" must be terminated by the matching end-tag "</br>". +</tt></span></dt><dd><p>A. Your document is HTML, not <span class="em">X</span>HTML. You need to fix it, or run it through Tidy first.</p></dd><dt><span class="term">Q. My output document is empty except for the <tt class="literal"><?xml version="1.0" encoding="UTF-8"?></tt> line.</span></dt><dd><p>A. The document is missing a namespace declaration. See the <a href="index.src.html" target="_top">example</a> for an example.</p></dd><dt><span class="term">Q. Some of the headers and document sections are repeated multiple times.</span></dt><dd><p>A. The document has out-of-sequence headers, such as <tt class="literal">h1</tt> followed by <tt class="literal">h3</tt> (instead of <tt class="literal">h2</tt>). This won't work.</p></dd><dt><span class="term">Q. <tt class="literal">Fatal Error! The prefix "db" for element "db:footnote" is not bound.</tt></span></dt><dd><p>A. You haven't declared the <tt class="literal">db</tt> namespace prefix. See the <a href="index.src.html" target="_top">example</a> for an example.</p></dd></dl></div><p></p></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ar01s08.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="ar01s10.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Customization </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Implementation Notes</td></tr></table></div></body></html> \ No newline at end of file