Mercurial > geeqie

<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>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<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 "&lt;/br&gt;".
</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">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</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>&nbsp;</td><td align="center" width="20%"><a accesskey="u" href="index.html">Up</a></td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ar01s10.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Customization&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Implementation Notes</td></tr></table></div></body></html>
author	mow
date	Mon, 10 May 2010 11:33:13 +0000
parents	2ae81598b254
children