Bug 799924 - RFE: Chapter / section front matter injection
RFE: Chapter / section front matter injection
Status: CLOSED CURRENTRELEASE
Product: PressGang CCMS
Classification: Community
Component: CSProcessor (Show other bugs)
1.x
Unspecified Unspecified
low Severity low
: ---
: ---
Assigned To: Lee Newson
: Reopened
: 805380 (view as bug list)
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-03-05 07:39 EST by Lee Newson
Modified: 2013-06-06 21:30 EDT (History)
2 users (show)

See Also:
Fixed In Version: 0.32.0
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-06-06 21:30:54 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Lee Newson 2012-03-05 07:39:00 EST
There needs to be a way to inject content into the section/chapter part of the xml files rather then wrapping all topics in sections.
Comment 1 Lee Newson 2012-03-05 07:41:07 EST
Need to find a way to inject the report a bug links as it seems that you can't have a chapter in the form of (para para simplesect section section section).
Comment 2 Joshua Wulf 2012-03-05 19:18:39 EST
Lee, do you have example use cases for this?

"inject content into the section/chapter part of the xml files rather then wrapping all topics in sections"
Comment 3 Lee Newson 2012-03-05 19:34:23 EST
This primarily comes from talking to misty about this last week(?). An example is that not everything is desired to be wrapped with a title. i.e: http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html/Administration_And_Configuration_Guide/What_this_Book_Covers.html

As such there needs to be some way to add this for a content spec.
Comment 4 Joshua Wulf 2012-03-21 00:52:11 EDT
maybe the Section: and Chapter: keywords could take an argument, like this:

Chapter: Some Chapter Name [Description= Some Topic [6137]]

Then the textual content of Topic 6137 would be inserted inline in under the Chapter / Section heading as the intro material for that Chapter / Section...
Comment 5 Lee Newson 2012-03-21 00:57:41 EDT

*** This bug has been marked as a duplicate of bug 805380 ***
Comment 6 Joshua Wulf 2012-03-21 03:09:21 EDT
This bug actually differs from bug 805380 in a subtle but significant way.

The functionality described in this bug would allow you to do this:

Section: Messaging [Description = Messaging Chapter Intro [6137]]
  Messaging Components [543]

Which would result in:

<section>
  <title>Messaging</title>
  <para>The content of Topic 6137 goes here, with no title element from Topic 6137, and no enclosing section tag - the content is within the Section container generated by the Section keyword.</para>
  <section>
    <title>Messaging Components</title>
    <para>This is topic 543</para>
  </section>
</section>


The functionality in 805380 would allow you to do this, which is different:

Section: Messaging Components [543]

Which would result in:

<section>
  <title>Messaging Components</title>
  <para>The content of topic 543 goes here, and the title above is from topic 543, and the enclosing section tag is also from the topic. In fact, the whole section is topic 543. The Section keyword in this case does not generate the Docbook section. We rely on the fact that a topic is already implemented as a Docbook section.</para>
</section>
Comment 7 Lee Newson 2012-03-21 03:24:11 EDT
That is not what this bug was originally about. The original concept was the same as bug 805380.

*** This bug has been marked as a duplicate of bug 805380 ***
Comment 8 Joshua Wulf 2012-03-21 03:33:42 EDT
OK, so that's an argument in favor of actually describing the feature in the bug :-)

I think the ability to do:

Chapter: Messaging [Description = Messaging Chapter Intro [6137]]
  Section: Messaging API [Description = Messaging API Section Intro [6138]]

is useful.

At the moment you have to use a pattern like this:

Chapter: Messaging
  Introducing Messaging [6137]
  Section: Messaging API
    Introducing Messaging API [6138]

Which makes sense when topic 6137 actually introduces Messaging. However, if topic 6137 actually talks about the Messaging Chapter in this particular book, its real title should be something like: "This Chapter", which looks funny in a book output, and is meaningless in Skynet.

What we're looking at is a meta-structural topic. It's a topic that talks about a particular output structure. It could have content in it like "This chapter introduces the following things..." or similar.

One alternative would be to be title the topic "Chapter Summary" or similar. There are ways to work around it, but they all result in stilted output.
Comment 9 Lee Newson 2012-03-21 18:35:54 EDT
After evaluating this and the other bug properly you are correct, this does differ slightly. However the syntax should be the same as bug 805380.

The idea of "[Description = Messaging API Section Intro [6138]]" is messy and confusing since we already have description and it does a completely different thing. As we discussed last week if it is going to be in the "Introduction" or "About" section of the section/chapter then it should be the same name as the chapter. Perhaps what we could have is something like this:

Chapter: Messaging [6850, Title=About Messaging]
  Section: Messaging API
    Some Random Topic [4201]
Comment 10 Joshua Wulf 2012-03-21 21:00:57 EDT
So like this?

1. 

Chapter: Messaging [6850, Title=About Messaging]
  Section: Messaging API
    Some Random Topic [4201]

Result: Topic 6850 evaluated to see if its title is "About Messaging". If validated, the content of Topic 6850 is injected as the child of the Docbook <chapter> element, effectively making it chapter introductory matter in the book.

2.

Chapter: Messaging 
  Section: Messaging API [235]
  Section: Some Other Section
    Some Random Topic [4201]

Result: Topic 235 "Messaging API" is inserted into the Docbook chapter with no wrapper section. 

3. 

Chapter: Messaging [6850, Title=About Messaging]
  Section: Messaging API [235]
  Section: Some Other Section [342, Title=Some Other Section Introduction]
    Some Random Topic [4201]

Result: 
Topic 6850 is used as introductory material for the chapter (content inserted as a child of the chapter element without the topic's own section elements); 

Topic 235 is a standalone section in the chapter (using the topic's own section element with no wrapper section element); 

Topic 342's topic content is used with no section wrapper as a child of the section wrapper element as introductory content.
Comment 11 Matthew Casperson 2012-05-01 02:03:52 EDT
Removing the section element wrapper places a huge burden on the tools to generate valid docbook for the boilerplate code in a wide range of situations, validate topics that are no longer valid without the section wrapper, and report and deal with these situations in an efficient way.

It is not worth the effort and confusion that this edge case generates, especially when this essentially comes down to not including a title for a topic instead of having a title of "Introduction" or "Overview" or "About X".

I am marking this as a low priority.
Comment 12 Joshua Wulf 2012-05-03 01:42:08 EDT
I'm not sure that this is accurately described as an "edge case", and I'm confident that the technical challenges can be more clearly articulated, and addressed. 

However, as you mention, a workaround exists ("Use an appropriately descriptive title, and accept that front matter has one") that doesn't significantly impact the comprehensibility of the text, there are a lot of requirements for the system, and this RFE has to be balanced with other requests and defects that don't have comparable workarounds.




I'll see if I can prototype this using xsl templating.

The xsl template approach would be like this:

If a section or chapter contains an immediate child with the same title, then delete the child's <section/> and <title/> tags.

So then an author can get untitled front matter in a chapter or section by using a front matter topic with the same title as the Section or Chapter in the Content Spec, then applying the xsl template to the publican book that the CSP produces.

The xsl could be incorporated into a publican brand, or applied manually or via a script (and possibly incorporated into the CSP).
Comment 13 Lee Newson 2012-05-03 01:57:52 EDT
The problem simply put Josh is this won't validate. 

<chapter id="Chapter-Configure_the_Content_Spec_Processor_Client">
	<title>Configure the Content Spec Processor Client</title>
	<para>Test Para</para>
	<simplesect>
		<title/>
		<para role="RoleCreateBugPara">
			<ulink url="https://bugzilla.redhat.com/enter_bug.cgi">Report a bug</ulink>
		</para>
	</simplesect>
	<xi:include href="topics/The_Client_Configuration_File_csprocessorini.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
	<xi:include href="topics/Generate_an_initial_csprocessorini.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
	<xi:include href="topics/Configure_apikey_details_in_csprocessorini.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
	<xi:include href="topics/Test_the_Content_Spec_Processor_Client.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>

If something as simple as that breaks the content then it is near impossible to prevent users from putting topics in with more complex content. While you can easily remove the Section and Title elements from the XML it has to stick to the Docbook schema, which is the issue here and why we've marked it as low priority.
Comment 14 Joshua Wulf 2012-05-03 03:04:11 EDT
Gotcha. So the xsl has to applied after the xi:includes have been processed.
Comment 15 Joshua Wulf 2012-05-03 03:15:36 EDT
Actually, it's the injected <simplesect> (the "Report a Bug Link") that is doing it.

Removing the <simplesect> validates the Docbook. So does changing it to a <formalpara>.

Is there a reason why <simplesect> is being used for the bug links, rather than <formalpara>?
Comment 16 Lee Newson 2012-05-03 03:16:23 EDT
No that won't work either. The format for docbook that we insert into is as follows:

Zero or more of the following elements:

calloutlist, glosslist, bibliolist, itemizedlist, orderedlist, segmentedlist, simplelist, variablelist, caution, important, note, tip, warning, literallayout, programlisting, programlistingco, screen, screenco, screenshot, synopsis, cmdsynopsis, funcsynopsis, classsynopsis, fieldsynopsis, constructorsynopsis, destructorsynopsis, methodsynopsis, formalpara, para, simpara, address, blockquote, graphic, graphicco, mediaobject, mediaobjectco, informalequation, informalexample, informalfigure, informaltable, equation, example, figure, table, msgset, procedure, sidebar, qandaset, task, productionset, constraintdef, anchor, bridgehead, remark, highlights, abstract, authorblurb, epigraph, indexterm, beginpage

Then zero or many of only one of these:
sect1, refentry, simplesect, section

or in regex:
sect1* |refentry* | simplesect* | section*

So the reason it fails in the example I gave is have the simplesect and sections from the xi:includes. So to be able to sucessfully do this with topics you'd have to enforce that no topic has simplesect's, refentry's, sect1's or section's. Plus possibly some other rules.
Comment 17 Lee Newson 2012-05-03 03:17:37 EDT
That was an example to show how easy it was to break it. I see no reason why the bug links couldn't be changed to a formal para, but that still doesn't resolve the issue.
Comment 18 Joshua Wulf 2012-05-03 09:42:14 EDT
Those tags *are* prohibited inside topics, which is why they use <formalpara>s for internal structure.
Comment 19 Matthew Casperson 2012-05-03 19:07:39 EDT
The only tag that is restricted in a topic is a section. No one (as far as I'm aware) has ever sat down and worked out a more comprehensive restriction of elements.
Comment 20 Joshua Wulf 2012-05-07 22:35:35 EDT
<sect1> has been banned in Publican for years now. That leaves only <simplesect>. 

I've documented that all three - section, sect1, and simplesect - cannot be used inside topics: https://engineering.redhat.com/docs/en-US/Engineering_Content_Services/1/html-single/Content_Spec_Processor_Guide/index.html#Topics_using_Docbook_XML

<section>, already banned inside topics, isn't actually a candidate to break this, only <simplesect> does, because it mixes section types.
Comment 21 Lee Newson 2012-05-07 22:41:39 EDT
As already mentioned there may be more elements then just sections. See: https://bugzilla.redhat.com/show_bug.cgi?id=799924#c16

So we first need to see if there is a set of docbook elements that exist for all requirements.
Comment 22 Joshua Wulf 2012-05-07 22:59:44 EDT
The complete set of elements that break this are:

<simplesect>
<sect1>-<sect6>
<refentry>
Comment 23 Lee Newson 2012-05-07 23:20:48 EDT
Just got around to comparing the two elements and I can confirm those values plus obviously the nested <section> which we already knew about.

Since <sect1>-<sect6> aren't available inside a section those don't need to be included. So really our only issue is <refentry> and <simplesect>.
Comment 24 Lee Newson 2013-05-05 20:00:27 EDT
*** Bug 805380 has been marked as a duplicate of this bug. ***
Comment 25 Lee Newson 2013-05-16 18:52:41 EDT
Added in csprocessor 0.32.0, syntax is as follows:

<LEVEL TYPE>: <TITLE> [<TOPIC DEFINTION>] <LEVEL DEFINTIONS>

eg

Section: About csprocessor [1]
  ...

or

Section: About csprocessor [1, condition=0.31.0] [condition=0.32.0] [T1]
  ...

We've also removed the ability to include <simplesect> or <refentry> in a <section>, so that all normal topics can be used as front matter or regular topics.
Comment 26 Lee Newson 2013-06-06 21:30:54 EDT
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.

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