|
1773
|
1 <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
|
|
|
2 to take advantage of the Docbook XSL stylesheets. These are a
|
|
|
3 well-designed, well-documented set of XSL stylesheets that provide a
|
|
|
4 variety of publishing features that would be difficult to recreate
|
|
|
5 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
|
|
|
6 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
|
|
|
7 choice for structured or technical documentation.</p><p>Where the only legacy concern is the documents themselves, and not
|
|
|
8 the tools and skill sets of documentation contributors, you should
|
|
|
9 consider using an (X)HMTL convertor to perform a one-time conversion
|
|
|
10 of your documentation source into Docbook, and then switching
|
|
|
11 development to the result files. You can use this stylesheet to
|
|
|
12 perform this conversion, or evaluate other tools, many of which are
|
|
|
13 probably appropriate for this purpose.</p><p>Often there are other legacy concerns: the availability of cheap
|
|
|
14 (including free) and usable HTML editors and editing modes; and the
|
|
|
15 fact that it's easier to teach people XHTML than Docbook. If either
|
|
|
16 of this is an issue in your organization, you may want to maintain
|
|
|
17 documentation sources in XHTML instead of Docbook</p><p>For example, at <a href="http://www.laszlosystems.com/" target="_top">Laszlo</a>,
|
|
|
18 most developers contribute directly to the documentation. Requiring
|
|
|
19 that developers learn Docbook, or that they wait on the doc team to
|
|
|
20 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
|
|
|
21 of the exisitng ones?</p><p>Each HTML to Docbook convertors that I could find had at least some
|
|
|
22 of the following limitations, some of which stemmed from their
|
|
|
23 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
|
|
|
24 editing of the output to clean up mistakes. This made them impossible
|
|
|
25 to use as part of a processing pipeline, where the source is
|
|
|
26 <span class="em">maintained</span> in XHTML.</p></li><li><p>There was no way to customize the output, except by (1) hand
|
|
|
27 editing, or (2) writing a post-processing stylesheet, which didn't
|
|
|
28 have access to the information in the XHTML source document.</p></li><li><p>Many of them were difficult or impossible to customize and
|
|
|
29 extend. They were closed-source, or written in Java or Perl (which I
|
|
|
30 find to be a difficult languages to use for customizing this kind of
|
|
|
31 thing) and embedded in a larger system.</p></li><li><p>They didn't take full advantage of the Docbook tag set and content
|
|
|
32 model to represent document structure. For instance, they didn't
|
|
|
33 generate nested <tt class="literal">section</tt> elements to represent
|
|
|
34 <tt class="literal">h1</tt> <tt class="literal">h2</tt> sequences, or <tt class="literal">table</tt> to
|
|
|
35 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>".
|
|
|
36 </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> |
