PR: MPXDOC-17

Revert last commit as it was breaking lots of other stuff.
Implemented and documented workaround solution using <entity> tags.

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@399845 13f79535-47bb-0310-9956-ffa450edef68

xdoc/xdocs/reference/xdocs.xml

@@ -134,6 +134,37 @@
         </p>
       </subsection>
 
+      <subsection name="Custom entities">
+        <p>
+          Due to a bug in Jelly, it is not possible to use custom entities directly in xdoc documents.
+          A workaround has been implemented such that you need to embed your entities
+          in <code>&lt;entity&gt;</code> tags. First you should declare the resource file
+          for your entities:
+        </p>
+        <source><![CDATA[<?xml version="1.0"?>
+<!DOCTYPE document [
+  <!ENTITY % my-entities SYSTEM "entities.ent">
+  %my-entities;
+]>
+<document>
+...]]></source>
+        <p>
+          where the file <code>entities.ent</code> contains, eg:
+        </p>
+        <source><![CDATA[<!ENTITY version '1.3.2-SNAPSHOT'>]]></source>
+        <p>
+          which can then be used in your xdoc like:
+        </p>
+        <source><![CDATA[<p>
+  This information only applies to version <entity>&version;</entity>.
+</p>]]></source>
+        <p>
+          <strong>Note</strong> that xdoc files using entities in this way
+          cannot be validated with the <code>xdoc:validate</code> goal
+          (see below).
+        </p>
+      </subsection>
+
     </section>
 
     <section name="Validation">