<?xml version="1.0" encoding="utf-8" ?>
<sect1 id="faq">
<sect1info>
<abstract role="texinfo-node">
  <para>Answers and tips for common problems</para>
</abstract>
</sect1info>
<title>FAQ</title>

<indexterm><primary>FAQ</primary></indexterm>
<indexterm><primary>tips</primary></indexterm>
<indexterm><primary>problems</primary></indexterm>
<indexterm><primary>bugs</primary></indexterm>

<qandaset defaultlabel="qanda">

<qandaentry>
<question>
<para>I have a SGML DocBook document.  How do I use docbook2X?</para>
<indexterm><primary>SGML</primary></indexterm>
</question>
<answer>
<para>
Use the <option>--sgml</option> option to &db2x_xsltproc;.
</para>

<para>
(Formerly, we described a quite intricate hack here to convert
to SGML to XML while preserving the ISO entities.  That hack
is actually what <option>--sgml</option> does.)
</para>
</answer>
</qandaentry>



<qandaentry>
<question>
<para>docbook2X bombs with this document!</para>
</question>

<answer>

<para>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.</para>

<para>
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.
</para>

</answer>
</qandaentry>

<qandaentry>
<question>
<para>
Must I use <sgmltag class="element">refentry</sgmltag>
to write my man pages?
</para>
<indexterm><primary><sgmltag class="element">refentry</sgmltag></primary></indexterm>
</question>

<answer>
<para>
Under the default settings of docbook2X: yes, you have to.
The contents of the source document
that lie outside of <sgmltag class="element">refentry</sgmltag>
elements are probably written in a book/article style
that is usually not suited for the reference style of man pages.
</para>

<para>
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 
  <citerefentry>
    <refentrytitle>docbook2man</refentrytitle>
    <manvolnum>1</manvolnum>
  </citerefentry>

and the
  <citerefentry>
    <refentrytitle>docbook2texi</refentrytitle>
    <manvolnum>1</manvolnum>
  </citerefentry>

man pages and the stylesheet that produces them
 in <filename>doc/ss-man.xsl</filename>.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
Where have the SGML-based docbook2X tools gone?
</para>
</question>

<answer>
<para>
They are in a separate package now, docbook2man-sgmlspl.
</para>
</answer>
</qandaentry>


<qandaentry>
<question>
<para>
I get some <command>iconv</command> error when converting documents.
</para>
<indexterm><primary><command>iconv</command></primary></indexterm>
</question>

<answer>
<para>
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
<command>iconv</command> says.
</para>

<para>
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 &utf8trans; character map.
Then use the <option>--utf8trans-map</option> option to the Perl
docbook2X tools to use your custom character map.
</para>

<para>
Alternatively, if you want to close your eyes to the utterly broken
Unicode handling in groff and Texinfo, just use the 
<option>--encoding=utf-8</option> option.
Note that the UTF-8 output is unlikely to display correctly everywhere.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
Texinfo output looks ugly.
</para>
</question>

<answer>
<para>
You have to keep in mind that Info is extremely limited in its
formatting.  Try setting the various parameters to the stylesheet
(see <filename>xslt/texi/param.xsl</filename>).
</para>

<para>
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.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
How do I use SAXON (or Xalan-Java) with docbook2X?
</para>
<indexterm><primary>SAXON</primary></indexterm>
<indexterm><primary>Xalan-Java</primary></indexterm>
</question>

<answer>
<para>
Bob Stayton’s <citetitle>DocBook XSL: The Complete Guide</citetitle>
has a nice 
<ulink
url="http://www.sagehill.net/docbookxsl/InstallingAProcessor.html">
section on setting up the XSLT processors</ulink>.
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 <filename>.xsl</filename>).
</para>

<para>
If you use the Perl wrapper scripts provided with docbook2X,
you only need to “install” the XSLT processors (i.e. for Java, copying 
the <filename>*.jar</filename> files to 
<filename>/usr/local/share/java</filename>), and you don’t
need to do anything else.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
XML catalogs don’t work with Xalan-Java.
(Or: Stop connecting to the Internet when running docbook2X!)
</para>
<indexterm><primary>Xalan-Java</primary></indexterm>
<indexterm><primary>catalog</primary></indexterm>
</question>

<answer>
<para>
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).
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>I don’t like how docbook2X renders this markup.</para>
<indexterm><primary>rendering</primary></indexterm>
<indexterm><primary>customizing</primary></indexterm>
</question>

<answer>

<para>The XSLT stylesheets are customizable, so assuming you have
knowledge of XSLT, you should be able to change the rendering easily.  
See <filename>doc/ss-texinfo.xsl</filename> of docbook2X’s own
documentation for a non-trivial example.
</para>

<para>
If your customizations can be generally useful, I would like to hear
about it.
</para>

<para>
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.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Does docbook2X support other XML document types
or output formats?</para>
<indexterm><primary>other output formats</primary></indexterm>
<indexterm><primary>other document types</primary></indexterm>
<indexterm><primary>non-DocBook document type</primary></indexterm>
</question>

<answer>

<para>
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.
</para>

<para>
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 &db2x_texixml;
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.
</para>

<para>
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.
</para>

<para>
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
&db2x_manxml; but with a different macro set).
In this case some of the code in &db2x_manxml; may be reused, and you 
can certainly reuse &utf8trans; and the provided roff character maps.
</para>
</answer>
</qandaentry>

</qandaset>

</sect1>