Bug 1013444 - Chapters or sections that contain <refentry>s do not work in Docbuilder
Chapters or sections that contain <refentry>s do not work in Docbuilder
Product: PressGang CCMS
Classification: Community
Component: CSProcessor (Show other bugs)
Unspecified Unspecified
high Severity high
: ---
: 1.4
Assigned To: Lee Newson
Depends On:
  Show dependency treegraph
Reported: 2013-09-30 02:01 EDT by Ruediger Landmann
Modified: 2014-02-23 18:43 EST (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2014-02-23 18:43:49 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description Ruediger Landmann 2013-09-30 02:01:05 EDT
Description of problem:
DocBuilder inserts: 

<para role="RoleCreateBugPara">
		<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):
Build 201309081012

How reproducible:

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

Actual results:
Sections or chapters do not build, docbuilder cites validation errors

Expected results:
Sections or chapters build correctly
Comment 1 Lee Newson 2013-09-30 02:08:04 EDT
Additional Information:

BZ#799924 is the reason as to why this functionality has been disabled.
Comment 2 Ruediger Landmann 2013-09-30 02:49:33 EDT
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
        Building Author_Group.xml
        Building Revision_History.xml
Content Specification successfully built with 9 Errors and 0 Warnings
Output saved to: /home/rlandmann/SystemTap_Tapset_Reference.zip
Comment 3 Ruediger Landmann 2013-09-30 18:19:17 EDT
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.
Comment 4 Lee Newson 2013-10-16 19:25:39 EDT
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.
Comment 5 Lee Newson 2013-10-16 19:46:58 EDT
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.
Comment 6 Lee Newson 2014-02-12 17:51:49 EST
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.
Comment 7 Lee Newson 2014-02-12 19:01:17 EST
Correction sorry that build number was for something else. This was fixed in 1.4-SNAPSHOT build 201402121631.
Comment 9 Matthew Casperson 2014-02-13 15:35:21 EST
Confirmed that a book with <refentry>s will build with bug links enabled and disabled.

Note You need to log in before you can comment on or make changes to this bug.