&myentity; entity replacement via <entites> configuration fails

[GoogleCodeExporter]

What steps will reproduce the problem?
1. Run mvn compile on the attached entity-test.xml

What is the expected output? What do you see instead?

According to the description at
http://docbkx-tools.sourceforge.net/docbkx-samples/manual.html, "Example 6.
Entity substitution", the entity &version; should be replaced. Instead,
generation fails with

[INFO] Processing entity-test.xml
Error on line 5 column 40 of
file:///C:/Users/aphillips/Workspaces/Xebia/deployit/core/documentation/src/docb
kx/entity-t
est.xml:
  Error reported by XML parser: The entity "version" was referenced, but
not declared.
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Failed to transform entity-test.xml.

Embedded error: org.xml.sax.SAXParseException: The entity "version" was
referenced, but not declared.

What version of the product are you using? On what operating system?

Plugin version: 2.0.9
Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)
Java version: 1.6.0_17
Java home: C:\Program Files\Java\jdk1.6.0_17\jre
Default locale: en_GB, platform encoding: Cp1252
OS name: "windows vista" version: "6.0" arch: "amd64" Family: "windows"

Original issue reported on code.google.com by sharedo...@gmail.com on 25 Feb 2010 at 7:28

Attachments:

• entity-test.xml
• pom.xml

[GoogleCodeExporter]

A workaround that seems to do the trick is to use the <preProcess> option in
combination with Ant's replace 
(http://ant.apache.org/manual/CoreTasks/replace.html)
task:

<preProcess>
  <echo>Replacing '&myentity;' with '${someProperty}' in source files...</echo>
  <replace dir="src/docbkx" token="&myentity;" value="${someProperty}">
    <include name="**/*.xml"/>
  </replace>
</preProcess>

Original comment by sharedo...@gmail.com on 26 Feb 2010 at 8:38

[GoogleCodeExporter]

Er...I just realized that the preProcess command actually modifies the *source*
files, so to keep the placeholders you'll have to "undo" the preProcess using
something like

<postProcess>
  <echo>Undoing replacement of '&myentity;' in source files...</echo>
  <replace dir="src/docbkx" token="${someProperty}" value="&myentity;">
    <include name="**/*.xml"/>
  </replace>
</postProcess>

Original comment by sharedo...@gmail.com on 8 Mar 2010 at 1:14

[GoogleCodeExporter]

Hi,

As far as I know XML Processing Instructions (XML PI are using <? ?>) cannot be
located in attributes.
So I guess we cannot fix anything here, you will have to find another way to 
replace
text.

Regards,
Cedric,

Original comment by MimilO...@gmail.com on 16 May 2010 at 9:36

• Changed state: Invalid

[GoogleCodeExporter]

> So I guess we cannot fix anything here, you will have to find another way to 
replace
> text.

Fair enough. See http://code.google.com/p/docbkx-tools/issues/detail?id=49, 
although
it may be the case that <?eval...?> is syntactically invalid there, too. 

In that case, though, I think there is a good case to be made that a new way of
replacing placeholders in attributes needs to be provided. Certainly, it seems 
like
an obvious use case that should be supported.

Original comment by sharedo...@gmail.com on 16 May 2010 at 10:36

[GoogleCodeExporter]

I've notices this too, but I have the following work around:
1. I use the preProcess configuration tag to copy all docbook files and related
images, CSS, etc to a staging directory, so MimilOwns's concern about modifying
sources is a moot point - perhaps the docbook tool should always copy to a 
staging
folder?
2. in the preProcess configuration tag, I have the following snippet:
<echo>Generating project properties as XML entites.</echo>
<echo file="${dir.docbook.staging}/META-INF/project.ent"><![CDATA[
<!-- Information about the doc itself -->
<!ENTITY project.groupId "${project.groupId}" >
<!ENTITY project.artifactId "${project.artifactId}" >
<!ENTITY project.name "${project.name}" >
<!ENTITY project.description "${project.description}" >
<!ENTITY doc-version "${project.version}" >

<!-- These are defined in the doc-pom to indicate what version of the framework 
the
doc is about -->
<!ENTITY ref.groupId "${ref.groupId}" >
<!ENTITY ref.artifactId "${ref.artifactId}" >
<!ENTITY ref.version "${ref.version}" >

<!-- These are for the most part autogenerated from the entities defined above 
-->
<!-- maven site base HREF of the referenced project -->
<!ENTITY href.site.base "${href.site.base}" >
<!-- maven site for the referenced project -->
<!ENTITY href.site "${href.site}" >
<!-- maven generated JavaDoc API for the referenced project -->
<!ENTITY href.api "${href.api}" >
<!-- maven generated JavaDoc Test API for the referenced project -->
<!ENTITY href.test-api "${href.test-api}" >

<!-- Makes standard HTML entities available -->
<!ENTITY % xhtml.latin-1 PUBLIC "-//W3C//ENTITIES Latin 1 for XHTML//EN"
"www.w3.org/xhtml-lat1.ent" >
<!ENTITY % xhtml.symbols PUBLIC "-//W3C//ENTITIES Symbols for XHTML//EN"
"www.w3.org/xhtml-symbol.ent" >
<!ENTITY % xhtml.special PUBLIC "-//W3C//ENTITIES Special for XHTML//EN"
"www.w3.org/xhtml-special.ent" >
%xhtml.latin-1;
%xhtml.symbols;
%xhtml.special;
                                        ]]></echo>
( note that the HTML entities reference saved files in my project folder 
because W3C
has started throttling multiple requests for these standard documents )
3. At the top of every  docbook document I have
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
    <!ENTITY % project.properties SYSTEM "../META-INF/project.ent" >
    %project.properties;
]>
<chapter xml:id="oraclexe"
    xmlns="http://docbook.org/ns/docbook"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xml="http://www.w3.org/XML/1998/namespace"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
            http://docbook.org/ns/docbook 
            http://docbook.org/xml/5.0/xsd/docbook.xsd 
    ">

This allows me to use HTML entities and custom ones defined by select project
properties. Unfortunately this approach has several drawbacks:
1. Only properties I have prepared for are created as entites - this definition 
is in
a parent project. I have plans on using ANT's xml/xslt capabilities for 
transforming
the entire POM's properties, when I get around to it.
2. Whenever the structure of my document folders change, I have to remember to 
update
the relative path to "../../META-INF/project.ent".
3. Because the META-INF folder is not copied to the source tree, Eclipse is not 
able
to completely validate the docbook XML file; although I don't see this as too 
much of
a problem since a fair number of my documents don't stick strictly with the 
schema
requirements (list items look horrible when spaced out with paragraphs :-/ ).

I would definitely like to see a standard means of turning project properties 
into
entities; I'll still have to figure out how to incorporate reference properties 
and
the HTML "imports" though.

Thanks for all the great work on this plugin, I've really enjoyed using it to 
create
my user guides :)

Original comment by jackd...@gmail.com on 1 Jun 2010 at 9:23