Red Hat Bugzilla – Bug 456170
publican won't render valid DocBook XML document
Last modified: 2010-11-23 23:16:22 EST
I've ported a copy of the release notes here for testing:
The document validates fine when I do a standard test with xmllint:
xmllint --postvalid --xinclude --noout en-US/RELEASE-NOTES.xml
But 'make test' fails with:
warning: failed to load external entity "tmp/en-US/xml/RELEASE-NOTES.xml"
If I do 'make SHELL="sh -x" test 2>log' and look at log, the following is revealed:
+ xmlClean -in RELEASE-NOTES.xml -out ../xml/RELEASE-NOTES.xml -book
RELEASE-NOTES -lang en-US
Modification of non-creatable array value attempted, subscript -1 at
/usr/lib/perl5/vendor_perl/5.10.0/XML/TreeBuilder.pm line 39.
This looks to be the result of an error from earlier in the build process,
please attach a tar-zip of the log file.
I tried to clone http://git.fedorahosted.org/git/release-notes.git which I
assume is the source git, so I could do a test build myself.
$ git clone http://git.fedorahosted.org/git/release-notes.git
Initialized empty Git repository in /home/jfearn/Fedora/release-notes/.git/
Getting alternates list for http://git.fedorahosted.org/git/release-notes.git
Getting pack list for http://git.fedorahosted.org/git/release-notes.git
Getting index for pack f71f83200163158323c4b2124711e2981ed44326
Getting pack f71f83200163158323c4b2124711e2981ed44326
which contains b81cdad6c28218aae614ad7684687cc53dfa60e4
...snip lots of walking...
cat: /home/jfearn/Fedora/release-notes/.git/refs/remotes/origin/master: No such
file or directory
fatal: : not a valid SHA1
fatal: Not a valid object name HEAD
I have no idea what any of that means :)
You got the wrong URL -- you want this one:
git clone git://fedorapeople.org/home/fedora/pfrields/public_git/release-notes.git
I moved all the entity defs in en-US/RELEASE-NOTES.xml to
en-US/RELEASE-NOTES.ent and this builds fine.
The problem causing the crash is that XML/TreeBuilder.pm does not have a
dedicated handler for Entity declarations and the generic Start handler can not
handle entity content.
Publican rewrites the DTD declaration before it builds the document, this causes
all entities declared in any xml file to be lost for the build. This is
deliberate behaviour to avoid the mess of duplicate local entity declarations.
Required publican updates:
1: XML/TreeBuilder.pm needs to be able to handle entity declarations.
2: Publican should emit an error if it finds entities declared in xml files and
advise the user to move the entity definitions in to the correct .ent file.
This is excellent information, and the document's building now. This advice
probably belongs in the publican documentation -- want a separate bug for that?
(In reply to comment #4)
> This is excellent information, and the document's building now. This advice
> probably belongs in the publican documentation -- want a separate bug for that?
oops! Not necessary
3: Update User Guide to let people know.
I have added a warning message:
*WARNING: Entities Declared in XML*
Entities declared in XML files are excluded from all output.
Entities should be declared in en-US/Publican.ent
Declaration in: en-US/Book_Info.xml
It will spit out one such warning for each xml file containing an entity declaration.
The documentation has been updated to reflect this design decision, feedback welcomed :)
I opened a new bug for the perl-XML-TreeBuilder issue. The publican specific issues have been fixed.