XML - DOCTYPE element - documentation suggestion

Hi all

I've been working with XML storage in Pg and was puzzled by the fact
that Pg appears to refuse to store a document with a DOCTYPE declaration
- it was interpreting it as a regular element and rejecting it.

This turns out to be because Pg parses XML as a fragment (ie option
CONTENT) when casting, and XML fragments cannot have a doctype.
Unfortunately the error is ... unhelpful ... and the documentation
neglects to mention this issue. Hence my post.

I didn't see anything about this in the FAQ or in the docs for the XML
datatype
(http://www.postgresql.org/docs/current/interactive/datatype-xml.html)
and was half-way through writing this post when I found a helpful
message on the list:

http://www.mail-archive.com/pgsql-general@postgresql.org/msg119713.html

that hinted the way. Even then it took me a while to figure out that you
can't specify DOCUMENT or CONTENT on the XML type its self, but must
specify it while parsing instead and use a CHECK constraint if you want
to require storage of whole documents in a field.

The xml datatype documentation should probably mention that whole
documents must be loaded with an XMLPARSE(DOCUMENT 'doc_text_here), they
cannot just be cast from text to xml as happens when you pass an xml
document as text to a parameter during an INSERT. This should probably
appear under "CREATING XML VALUES" in:

http://www.postgresql.org/docs/current/static/datatype-xml.html

... and probably deserves mention in a new "CAVEATS" or "NOTES" section
too, as it' *will* catch people out even if they R TFM.

I'd expect this to work:

CREATE TABLE test_xml ( doc xml );

INSERT INTO test_xml ( doc ) VALUES (
$$<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE test SYSTEM 'test.dtd'><test>dummy content</test>$$
);

... but it fails with:

ERROR: invalid XML content
LINE 2: $$<?xml version="1.0" encoding="utf-8"?>
^
DETAIL: Entity: line 2: parser error : StartTag: invalid element name
<!DOCTYPE test SYSTEM 'test.dtd'><test>dummy content</test>
^

though xmllint (from libxml) is quite happy with the document. This had
me quite confused for a while.

--
Craig Ringer