Red Hat Bugzilla – Bug 1013444
Chapters or sections that contain <refentry>s do not work in Docbuilder
Last modified: 2014-02-23 18:43:49 EST
Description of problem:
<ulink url="http://redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=23174">Edit this topic</ulink>
at the end of a <chapter> or <section>. If the root node of the topic contains <refentry>s, this extra para creates a validation error
Version-Release number of selected component (if applicable):
Steps to Reproduce:
1. Create a section or chapter that contains <refentry>s as its children
2. Include this section or chapter in a book
3. Try to view the book in docbuilder
Sections or chapters do not build, docbuilder cites validation errors
Sections or chapters build correctly
BZ#799924 is the reason as to why this functionality has been disabled.
Confirm that this is broken not just in docbuilder but also when you check out the book to build locally with "csprocessor build" (see output below)
Existing platform books use this structure; and <refentry> is also the structure that Publican uses for man pages, so any reuse of man page material will need this functionality.
FWIW, this book has the "Report a bug" functionality turned off, so it's not necessary to inject those paras at all.
$ csprocessor build 22468
CSProcessor client version: 1.0.3
Loading configuration from /home/rlandmann/.config/csprocessor.ini
Connecting to PressGang server: http://skynet.usersys.redhat.com:8080/TopicIndex/
WARN: The Content Specification has validation errors, so using the latest valid version.
Attempting to download all the latest topics...
Starting first validation pass...
Starting second validation pass...
INFO: The Content Specification is valid.
Starting to build...
Doing en-US Populate Database Pass
Doing Fixed URL Pass
Doing Revisions Fixed URL Pass
Doing en-US First topic pass
Processing 17 Topics
First topic Pass 6% Done
First topic Pass 12% Done
First topic Pass 18% Done
First topic Pass 24% Done
First topic Pass 29% Done
First topic Pass 35% Done
First topic Pass 41% Done
First topic Pass 47% Done
First topic Pass 53% Done
First topic Pass 59% Done
First topic Pass 65% Done
First topic Pass 71% Done
First topic Pass 76% Done
First topic Pass 82% Done
First topic Pass 88% Done
First topic Pass 94% Done
First topic Pass 100% Done
Doing en-US Topic Link Pass
Doing en-US Spec Topic Pass
Processing 17 Spec Topics
Processing Pass 6% Done
Processing Pass 12% Done
Processing Pass 18% Done
Processing Pass 24% Done
Processing Pass 29% Done
Processing Pass 35% Done
Processing Pass 41% Done
Processing Pass 47% Done
Processing Pass 53% Done
Processing Pass 59% Done
Processing Pass 65% Done
Processing Pass 71% Done
Processing Pass 76% Done
Processing Pass 82% Done
Processing Pass 88% Done
Processing Pass 94% Done
Processing Pass 100% Done
Building the ZIP file
Building Level and Topic XML Files
Building Error Chapter
Adding standard files to Publican ZIP file
Content Specification successfully built with 9 Errors and 0 Warnings
Output saved to: /home/rlandmann/SystemTap_Tapset_Reference.zip
Actually, no; the "csprocessor build" error is unrelated (subject for another bug). This is purely a docbuilder problem; removing Platform R&D blocker status and downgrading urgency and sev accordingly.
I've done a small patch to this for 1.2. Now <refentry>'s will render correctly provided that they are not used as a front matter topic. This works by going back to the old mechanism of wrapping the para in a <simplesect>.
I'm going to leave this bug open though, so that we can work out a proper way to deal with this. I suspect what should happen is that the content spec validator should be updated to check that a front matter topic doesn't have nested sections or refentry's.
Ignore that first part of that last comment sorry, I wrote it up while waiting for a build and upon seeing the result it isn't fixed.
The problem is the DTD only allows all refentries or all simplesects after the regular content, so it's possible there may be no way to add bug links or editor links for topics that contain refentrys.
Fixed in 1.4-SNAPSHOT build 201402121649
Topics with <refentry> will now get the very last <refentry> element and add either a <refsection> or <refsect1> (depending on what the last element in the <refentry> is). Inside that <refsection>/<refsect1> a blank title will be added and then any bug/editor links.
This means that there will be a slightly larger gap than normal between the end of the text and the links but it is fairly minimal and this really is the only way to add bug/editor links.
Correction sorry that build number was for something else. This was fixed in 1.4-SNAPSHOT build 201402121631.
Confirmed that a book with <refentry>s will build with bug links enabled and disabled.