It is common for SGML instances to use only a public identifier in document type and parameter entity declarations:

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter><title>Chapter Title</title>
<para>
This <emphasis>paragraph</paragraph> is important.
</para>
</chapter>

XML requires a system identifier:

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter><title>Chapter Title</title>
<para>
This <emphasis>paragraph</paragraph> is important.
</para>
</chapter>

If you're used to using catalog files to resolve system identifiers, you may be dismayed to learn that system identifiers are required. Because most tools favor system identifiers over public identifiers, all of the portability that was gained by the use of catalog files seems to have been lost. In the long run, it'll be regained by the fact that XML system identifiers can be URNs, which will have a resolution scheme like catalogs, but what about the short run?

Luckily, there are a couple of options. First, you can tell your tools to use the public identifiers even though system identifiers are present. Simply add:

OVERRIDE YES

to your catalog files. Alternatively, you can remap system identifers with the SYSTEM catalog directive. If you are faced with documents that don't use public identifiers at all, this is probably your only option.

If you have used SGML minimization features in your instances:

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter id=chap1><title>Chapter Title</title>
<para>
This <emphasis>paragraph</> is important.
</para>
</chapter>

they will not be well-formed XML instances. In particular, XML

	Requires that all attribute values be quoted.
	Does not allow short tag minization.

The result will be something like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter id="chap1"><title>Chapter Title</title>
<para>
This <emphasis>paragraph</emphasis> is important.
</para>
</chapter>

Correct processing of this document may require access to the default attributes:

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter><title>Chapter Title</title>
<para>
Write to us at:
<address>
90 Sherman Street
Cambridge, MA 02140
</address>
</para>
</chapter>

Address expresses that its content is line-specific with an attribute.

Some XML processing environments are going to ignore the doctype declaration in your document, even if it's present. This is relevant when your instance uses elements that have attributes with default values. The default values are expressed in the DTD, but may not be expressed in your instance. In the case of DocBook, there are relatively few of these, and your stylesheet can probably be constructed to do the right thing in either case. (It essentially treats the attributes as if they had implied values.)

The result will be something like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter><title>Chapter Title</title>
<para>
Write to us at:
<address format="linespecific">
90 Sherman Street
Cambridge, MA 02140
</address>
</para>
</chapter>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter><title>Chapter Title</title>
<para>
This book was published by O'Reilly&trade;.
</para>
</chapter>

The DocBook DTD defines all of the standard ISO entities automatically, but the ISO definitions use SDATA, which is not allowed in XML. Eventually, ISO (or someone else) will release official ISO standard entity sets that make reference to the appropriate Unicode character for each entity. Until then, the XML version of DocBook is distributed with an unofficial set. If you use entities in your document, it may be wise to put declarations for them in the internal subset of each instance, because some XML browsers are going to parse the internal subset but not the external subset. If the entity declarations are in your DTD, and the browser does not parse the external subset, the browser won't know how to display the entities in your document.

The result will be something like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY trade "&#x2122;">
<chapter><title>Chapter Title</title>
<para>
This book was published by O'Reilly&trade;.
</para>
</chapter>

<!DocType Book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<book><title>Book Title</title>
<chapter><title>Chapter Title</Title>
<para>
Paragraph test.
</para>
<PARA>
A second paragraph.
</PARA>
</chapter>
</book>

With the standard DocBook SGML declaration, DocBook instances are not case-sensitive with respect to element and attribute names. XML is always case-sensitive. As long as you have used the same case consistently, your XML instances will be well-formed, but it may still be advantageous to do some case-folding because it will simplify the construction of stylesheets.

	Keywords in XML are case-sensitive, and must be in uppercase.
	The name declared in the document type declaration, like all other names, is case-sensitive.
	Start and end tags must use the same case.
	In XML, Para is not the same as PARA. Note that this is a validity error (against the XML version of DocBook), but it is not an XML well-formedness error. The use of para and PARA as distinct names is as legitimate as using foo and bar, as long as they are properly nested.

The result will be something like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book><title>Book Title</title>
<chapter><title>Chapter Title</title>
<para>
Paragraph test.
</para>
<para>
A second paragraph.
</para>
</chapter>
</book>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter><title>Chapter Title</title>
<indexterm id="idx-bor"><primary>Something</primary></indexterm>
<para>
Paragraph test.
</para>
<indexterm startref="idx-bor">
</chapter>

The StartRef attribute on indexterm and the OtherTerm attribute on GlossSee and GlossSeeAlso are #CONREF attributes.

In SGML terms, this means that when these attributes are used, the content of the tag is taken to be the same as the content of the tag pointed to by the attribute.

If you have used these attributes, your instance will contain both empty and non-empty versions of these tags.

Your best bet is to transform the #CONREF version into an empty tag and let your stylesheet deal with it appropriately.

The result will be something like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter><title>Chapter Title</title>
<indexterm id="idx-bor"><primary>Something</primary></indexterm>
<para>
Paragraph test.
</para>
<indexterm startref="idx-bor"/>
</chapter>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY % draft "IGNORE">
<!ENTITY % sourcecode "CDATA">
]>
<chapter><title>Chapter Title</title>
<![ %draft; [
<para>
Draft paragraph.
</para>
]]>
<para>
The following code is totally out of context:
<programlisting>
<![ %sourcecode; [
if (x < 3) {
  y = 3;
}
]]>
</programlisting>
</chapter>

	Parameter entities are not allowed in the body of XML documents (they are allowed in the internal subset).
	XML instances cannot contain IGNORE, INCLUDE, TEMP, or RCDATA marked sections.
	CDATA marked sections must use the “CDATA” keyword literally because parameter entities are not allowed.

The result will be something like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter><title>Chapter Title</title>
<para>
The following code is totally out of context:
<programlisting>
<![CDATA[
if (x < 3) {
  y = 3;
}
]]>
</programlisting>
</chapter>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY % sourcecode SYSTEM "program.c" CDATA>
]>
<chapter><title>Chapter Title</title>
<para>
The following code is totally out of context:
<programlisting>
&sourcecode;
</programlisting>
</chapter>

XML instances cannot use CDATA or SUBDOC external entities. One option for integrating external CDATA content into a document is to employ a pre-processing pass that inserts the content inline, wrapped in a CDATA marked section.

SUBDOC entities may be more problematic. If you do not require validation, it may be sufficient to simply put them inline. XML namespaces may offer another possible solution.

The result will be something like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter><title>Chapter Title</title>
<para>
The following code is totally out of context:
<programlisting>
<![CDATA[
int main () {
..
}
]]>
</programlisting>
</chapter>

They're not allowed in XML, so don't add any.

They're not allowed in XML, so don't add any.