Bug 456170

Summary: publican won't render valid DocBook XML document
Product: [Community] Publican Reporter: Paul W. Frields <stickster>
Component: publicanAssignee: Jeff Fearn <jfearn>
Status: CLOSED CURRENTRELEASE QA Contact: Fedora Extras Quality Assurance <extras-qa>
Severity: medium Docs Contact:
Priority: medium    
Version: 1.6CC: mmcallis, publican-list
Target Milestone: ---   
Target Release: ---   
Hardware: All   
OS: Linux   
Fixed In Version: 0.37 Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2008-09-09 00:29:13 EDT Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Description Paul W. Frields 2008-07-21 17:22:23 EDT
Version:  publican-0.33-1.fc9

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
Modification of non-creatable array value attempted, subscript -1 at
/usr/lib/perl5/vendor_perl/5.10.0/XML/TreeBuilder.pm line 39.
Comment 1 Jeff Fearn 2008-07-21 20:05:48 EDT
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
walk b81cdad6c28218aae614ad7684687cc53dfa60e4
...snip lots of walking...
walk fe3d25dbf8a1619662e5a4a0bbb68ad3a8f9f6bd
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 :)

Comment 2 Paul W. Frields 2008-07-21 20:23:33 EDT
You got the wrong URL -- you want this one:

git clone git://fedorapeople.org/home/fedora/pfrields/public_git/release-notes.git
Comment 3 Jeff Fearn 2008-07-21 21:24:36 EDT
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.

Comment 4 Paul W. Frields 2008-07-21 22:28:37 EDT
This is excellent information, and the document's building now.  This advice
probably belongs in the publican documentation -- want a separate bug for that?
Comment 5 Jeff Fearn 2008-07-21 22:33:03 EDT
(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.
Comment 6 Jeff Fearn 2008-08-06 02:12:27 EDT
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 :)

Comment 7 Jeff Fearn 2008-09-09 00:29:13 EDT
I opened a new bug for the perl-XML-TreeBuilder issue. The publican specific issues have been fixed.