Red Hat Bugzilla – Bug 824597
CSP prevents inclusion of topics directly within a part
Last modified: 2013-06-06 21:29:50 EDT
Description of problem:
When including a topic directly within a 'part', the CSP reports:
ERROR: Line 65: Invalid Topic! A topic must be inside of a Chapter or Section.
-> Installing Virtualization Hosts 
Is this intentional? DocBook XML does not prevent a part including content directly (un-nested), usually introductory or overview content.
The relevant extract from my content specification:
Part: Installing Virtualization Hosts
#Installing Virtualization Hosts 
Yeah it was intention just because I couldn't find any examples of it in documentation. But looking at your example I can see why it'd be useful to have, so I'll fix it up tonight.
Yeah, the text probably doesn't do it justice (and shouldn't have had the comment # I put in afterwards) but the use case is we have an infographic (wrapped in the topic) at the start of the part showing where the user is at in the installation process. After that we launch into the expected chapters.
Had an actual look at this one finally and it's actually not valid docbook to have a section (ie a topic) in a part. See: http://www.docbook.org/tdg/en/html/part.html
The element that would normally be used from what I can see is partintro. However it does have slightly different valid content, so I can't just dump the normal topic into the partintro as it may break the docbook XML. It actually brings up the same problem as Bug #799924. Either way I'll bring this up with Matt at our meeting on Tuesday.
Yeah looking at the source of the original book before we broke it into topics it looks like this:
<part label="III" id="part_III">
<title>Installing Virtualization Hosts</title>
<imagedata fileref="images/RHEV30_Install_Flow_4.png" />
<xi:include href="Hosts.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<xi:include href="Install_RHEVH.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<xi:include href="Install_RHEL.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
The partintro element does support section as a child and I have confirmed that publican builds the above snippet when the <mediaobject> is wrapped in a section.
Thanks for the info, though I had avoided that because then it throws the title below the part title which looks a little weird. Though we could do that for an interim solution.
(In reply to comment #6)
> Thanks for the info, though I had avoided that because then it throws the
> title below the part title which looks a little weird. Though we could do
> that for an interim solution.
That's a side-effect of using sections as topic containers that we (or in this case *I*) probably just have to deal with I think.
Lee, was there any progress on this? I've come back to try and insert these workflow overview topics but it looks like it is still blocked.
Added interim solution in 0.27.0.
As we mentioned before, parts can't have sections and a section doesn't directly map to whats valid for a partintro. So the topics are still wrapped in a section and added to partintro, this has the side effect of having the topic title added below the part heading.
I've also set it up so that you can have multiple topics under a part, just so long as they are before any other levels (chapters, sections, etc). Note: This may change when/if we move the topic into the partintro directly.
Closing and setting as current release as no QA was performed by the original reporter. If there is still an issue with this bug still than please re-open it.