xdoc with XML entities goes wierd

I'm having a problem using XML entities inside xdoc files.

I like to create XML entities for my XML documentation for common things like links to API docs, or to descriptions of my schemas.

So, I have a file, services.xml, which begins:

<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY % common-links SYSTEM "../common/links.xml">
%common-links;
]>

Inside common/links.xml I have stuff like:

<!ENTITY _module '<module>'>
<!ENTITY module '<a href="descriptor.html#module">&_module;</a>'>

And that works properly in my docs; <module> appears as a link when I use
&module; in the document.

However, if you do something simpler it fails:

<!ENTITY api.IFactory 'IFactory'>

Appears in the output as a blank space.

<!ENTITY api.IFactory '<IFactory>'>

Appears as: <IFactory>

<!ENTITY api.IFactory '[IFactory]'>

Appears as: ]

<!ENTITY api.IFactory '<a
href="apidocs/org/apache/commons/hivemind/IFactory.html">IFactory</a>'>

Appears as:
<a href="apidocs/org/apache/commons/hivemind/IFactory.html">
tory
</a>

Something appears screwed up in the xdoc processing pipeline. Does this all sound familiar?

Alternately, is there another way to accomplish my goals (using some kind of Velocity markup?)