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.
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).
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"
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.
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...
*** This bug has been marked as a duplicate of bug 805380 ***
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>
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 ***
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.
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]
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.
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.
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).
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.
Gotcha. So the xsl has to applied after the xi:includes have been processed.
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>?
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.
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.
Those tags *are* prohibited inside topics, which is why they use <formalpara>s for internal structure.
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.
<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.
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.
The complete set of elements that break this are: <simplesect> <sect1>-<sect6> <refentry>
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>.
*** Bug 805380 has been marked as a duplicate of this bug. ***
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.
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.