1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<title>docbook2X: FAQ</title>
<link rel="stylesheet" href="docbook2X.css" type="text/css" />
<link rev="made" href="mailto:stevecheng@users.sourceforge.net" />
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1" />
<meta name="description" content=
"Answers and tips for common problems" />
<link rel="start" href="docbook2X.html" title=
"docbook2X: Documentation Table of Contents" />
<link rel="up" href="docbook2X.html" title=
"docbook2X: Documentation Table of Contents" />
<link rel="prev" href="utf8trans.html" title=
"docbook2X: utf8trans" />
<link rel="next" href="performance.html" title=
"docbook2X: Performance analysis" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">FAQ</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href=
"utf8trans.html"><< Previous</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href=
"performance.html">Next >></a></td>
</tr>
</table>
<hr /></div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="faq" name="faq"></a>FAQ</h2>
</div>
</div>
</div>
<a id="id2539312" class="indexterm" name="id2539312"></a><a id=
"id2539319" class="indexterm" name="id2539319"></a><a id=
"id2539325" class="indexterm" name="id2539325"></a><a id=
"id2539332" class="indexterm" name="id2539332"></a>
<div class="qandaset">
<dl>
<dt>Q: <a href="faq.html#id2539951">I have a SGML DocBook document.
How do I use docbook2X?</a></dt>
<dt>Q: <a href="faq.html#id2539993">docbook2X bombs with this
document!</a></dt>
<dt>Q: <a href="faq.html#id2540024">Must I use refentry to write my
man pages?</a></dt>
<dt>Q: <a href="faq.html#id2540103">Where have the SGML-based
docbook2X tools gone?</a></dt>
<dt>Q: <a href="faq.html#id2540121">I get some iconv error when
converting documents.</a></dt>
<dt>Q: <a href="faq.html#id2540201">Texinfo output looks
ugly.</a></dt>
<dt>Q: <a href="faq.html#id2540235">How do I use SAXON (or
Xalan-Java) with docbook2X?</a></dt>
<dt>Q: <a href="faq.html#id2540311">XML catalogs don’t work
with Xalan-Java. (Or: Stop connecting to the Internet when running
docbook2X!)</a></dt>
<dt>Q: <a href="faq.html#id2540350">I don’t like how
docbook2X renders this markup.</a></dt>
<dt>Q: <a href="faq.html#id2540402">Does docbook2X support other
XML document types or output formats?</a></dt>
</dl>
<table border="0" summary="Q and A Set">
<col align="left" width="1%" />
<tbody>
<tr class="question">
<td align="left" valign="top"><a id="id2539951" name=
"id2539951"></a><a id="id2539953" name=
"id2539953"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>I have a SGML DocBook document. How do I use docbook2X?</p>
<a id="id2539960" class="indexterm" name="id2539960"></a></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>Use the <code class="option">--sgml</code> option to
<span><strong class="command">db2x_xsltproc</strong></span>.</p>
<p>(Formerly, we described a quite intricate hack here to convert
to SGML to XML while preserving the ISO entities. That hack is
actually what <code class="option">--sgml</code> does.)</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2539993" name=
"id2539993"></a><a id="id2539995" name=
"id2539995"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>docbook2X bombs with this document!</p>
</td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>It is probably a bug in docbook2X. (Assuming that the input
document is valid DocBook in the first place.) Please file a bug
report. In it, please include the document which causes docbook2X
to fail, or a pointer to it, or a test case that reproduces the
problem.</p>
<p>I don’t want to hear about bugs in obsolete tools (i.e.
tools that are not in the current release of docbook2X.) I’m
sorry, but maintaining all that is a lot of work that I don’t
have time for.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540024" name=
"id2540024"></a><a id="id2540027" name=
"id2540027"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>Must I use <code class="sgmltag-element">refentry</code> to
write my man pages?</p>
<a id="id2540039" class="indexterm" name="id2540039"></a></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>Under the default settings of docbook2X: yes, you have to. The
contents of the source document that lie outside of <code class=
"sgmltag-element">refentry</code> elements are probably written in
a book/article style that is usually not suited for the reference
style of man pages.</p>
<p>Nevertheless, sometimes you might want to include inside your
man page, (small) snippets or sections of content from other parts
of your book or article. You can achieve this by using a custom
XSLT stylesheet to include the content manually. The docbook2X
documentation demonstrates this technique: see the <span class=
"citerefentry"><span class=
"refentrytitle">docbook2man</span></span> and the <span class=
"citerefentry"><span class=
"refentrytitle">docbook2texi</span></span> man pages and the
stylesheet that produces them in <code class=
"filename">doc/ss-man.xsl</code>.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540103" name=
"id2540103"></a><a id="id2540105" name=
"id2540105"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>Where have the SGML-based docbook2X tools gone?</p>
</td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>They are in a separate package now, docbook2man-sgmlspl.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540121" name=
"id2540121"></a><a id="id2540123" name=
"id2540123"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>I get some <span><strong class="command">iconv</strong></span>
error when converting documents.</p>
<a id="id2540135" class="indexterm" name="id2540135"></a></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>It's because there is some Unicode character in your document
that docbook2X fails to convert to ASCII or a markup escape (in
roff or Texinfo). The error message is intentional because it
alerts you to a possible loss of information in your document,
although admittedly it could be less cryptic, but I unfortunately
can't control what <span><strong class=
"command">iconv</strong></span> says.</p>
<p>You can look at the partial man or Texinfo output — the
offending Unicode character should be near the point that the
output is interrupted. Since you probably wanted that Unicode
character to be there, the way you want to fix this error is to add
a translation for that Unicode character to the
<span><strong class="command">utf8trans</strong></span> character
map. Then use the <code class="option">--utf8trans-map</code>
option to the Perl docbook2X tools to use your custom character
map.</p>
<p>Alternatively, if you want to close your eyes to the utterly
broken Unicode handling in groff and Texinfo, just use the
<code class="option">--encoding=utf-8</code> option. Note that the
UTF-8 output is unlikely to display correctly everywhere.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540201" name=
"id2540201"></a><a id="id2540203" name=
"id2540203"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>Texinfo output looks ugly.</p>
</td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>You have to keep in mind that Info is extremely limited in its
formatting. Try setting the various parameters to the stylesheet
(see <code class="filename">xslt/texi/param.xsl</code>).</p>
<p>Also, if you look at native Info pages, you will see there is a
certain structure, that your DocBook document may not adhere to.
There is really no fix for this. It is possible, though, to give
rendering hints to the Texinfo stylesheet in your DocBook source,
like this this manual does. Unfortunately these are not yet
documented in a prominent place.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540235" name=
"id2540235"></a><a id="id2540237" name=
"id2540237"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>How do I use SAXON (or Xalan-Java) with docbook2X?</p>
<a id="id2540244" class="indexterm" name="id2540244"></a><a id=
"id2540250" class="indexterm" name="id2540250"></a></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>Bob Stayton’s <em class="citetitle">DocBook XSL: The
Complete Guide</em> has a nice <a href=
"http://www.sagehill.net/docbookxsl/InstallingAProcessor.html"
target="_top">section on setting up the XSLT processors</a>. It
talks about Norman Walsh’s DocBook XSL stylesheets, but for
docbook2X you only need to change the stylesheet argument (any file
with the extension <code class="filename">.xsl</code>).</p>
<p>If you use the Perl wrapper scripts provided with docbook2X, you
only need to “install” the XSLT processors (i.e. for
Java, copying the <code class="filename">*.jar</code> files to
<code class="filename">/usr/local/share/java</code>), and you
don’t need to do anything else.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540311" name=
"id2540311"></a><a id="id2540313" name=
"id2540313"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>XML catalogs don’t work with Xalan-Java. (Or: Stop
connecting to the Internet when running docbook2X!)</p>
<a id="id2540322" class="indexterm" name="id2540322"></a><a id=
"id2540329" class="indexterm" name="id2540329"></a></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>I have no idea why — XML catalogs with Xalan-Java
don’t work for me either, no matter how hard I try. Just go
use SAXON or libxslt instead (which do work for me at least).</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540350" name=
"id2540350"></a><a id="id2540352" name=
"id2540352"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>I don’t like how docbook2X renders this markup.</p>
<a id="id2540359" class="indexterm" name="id2540359"></a><a id=
"id2540366" class="indexterm" name="id2540366"></a></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>The XSLT stylesheets are customizable, so assuming you have
knowledge of XSLT, you should be able to change the rendering
easily. See <code class="filename">doc/ss-texinfo.xsl</code> of
docbook2X’s own documentation for a non-trivial example.</p>
<p>If your customizations can be generally useful, I would like to
hear about it.</p>
<p>If you don't want to muck with XSLT, you can still tell me what
sort of features you want. Maybe other users want them too.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top"><a id="id2540402" name=
"id2540402"></a><a id="id2540404" name=
"id2540404"></a><b>Q:</b></td>
<td align="left" valign="top">
<p>Does docbook2X support other XML document types or output
formats?</p>
<a id="id2540411" class="indexterm" name="id2540411"></a><a id=
"id2540418" class="indexterm" name="id2540418"></a><a id=
"id2540425" class="indexterm" name="id2540425"></a></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b>A:</b></td>
<td align="left" valign="top">
<p>No. But if you want to create code for a new XML document type
or output format, the existing infrastructure of docbook2X may be
able to help you.</p>
<p>For example, if you want to convert a document in the W3C spec
DTD to Texinfo, you can write a XSLT stylesheet that outputs a
document conformant to the Texi-XML, and run that through
<span><strong class="command">db2x_texixml</strong></span> to get
your Texinfo pages. Writing the said XSLT stylesheet should not be
any more difficult than if you were to write a stylesheet for HTML
output, in fact probably even easier.</p>
<p>An alternative approach is to convert the source document to
DocBook first, then apply docbook2X conversion afterwards. The
stylesheet reference documentation in docbook2X uses this
technique: the documentation embedded in the XSLT stylesheets is
first extracted into a DocBook document, then that is converted to
Texinfo. This approach obviously is not ideal if the source
document does not map well into DocBook, but it does allow you to
use the standard DocBook HTML and XSL-FO stylesheets to format the
source document with little effort.</p>
<p>If you want, on the other hand, to get troff output but using a
different macro set, you will have to rewrite both the stylesheets
and the post-processor (performing the function of
<span><strong class="command">db2x_manxml</strong></span> but with
a different macro set). In this case some of the code in
<span><strong class="command">db2x_manxml</strong></span> may be
reused, and you can certainly reuse <span><strong class=
"command">utf8trans</strong></span> and the provided roff character
maps.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href=
"utf8trans.html"><< Previous</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href=
"performance.html">Next >></a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top"><span><strong class=
"command">utf8trans</strong></span> </td>
<td width="20%" align="center"><a accesskey="h" href=
"docbook2X.html">Table of Contents</a></td>
<td width="40%" align="right" valign="top"> Performance
analysis</td>
</tr>
</table>
</div>
<p class="footer-homepage"><a href=
"http://docbook2x.sourceforge.net/" title=
"docbook2X: Home page">docbook2X home page</a></p>
</body>
</html>
|
