Bug 1119098 - [RFE] Allows nested sections in PressGang
Summary: [RFE] Allows nested sections in PressGang
Keywords:
Status: CLOSED WONTFIX
Alias: None
Product: PressGang CCMS
Classification: Community
Component: CCMS-Core
Version: 1.8
Hardware: Unspecified
OS: Unspecified
high
high
Target Milestone: ---
: ---
Assignee: pressgang-ccms-dev
QA Contact:
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2014-07-14 01:25 UTC by Don Domingo
Modified: 2014-11-27 00:33 UTC (History)
3 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2014-11-27 00:33:16 UTC


Attachments (Terms of Use)

Description Don Domingo 2014-07-14 01:25:02 UTC
As of the latest PressGang update, nested sections within the same topic are now illegal.

Since this was a feature that we used and depended upon previously, I consider this a regression.

We need the ability to nest sections inside topics because in many cases, a topic is only "superficially" split up into several sections. Case in point: topic 30776.

That particular topic deals with RHN/CDN channels. Every time those channels change (ie during each release), it's easier to maintain and edit them in just the one place rather than in six or so different topics. Also, if you'll notice, even in its current form it is still a reusable topic (we share it between 5 different books; we just manage it through conditions when need be).


Another important use case is for content that is auto-generated. Case in point: topic 30783. All of that content is generated by a single tool which spits out *one* file. If I have to split topic 30783 out into multiple topics, then I have to maintain each of those multiple topics separately. 

All in all, I am very surprised that this change was introduced. I don't see any real benefit to it from a content creation or maintenance point of view. And now I have to update several content specs for an update that is normally a fully automated process.

Comment 1 Lee Newson 2014-07-14 02:00:11 UTC
This is not a regression. The fact that this was ever allowed was a regression in PressGang 1.4 (see BZ#1097062). As such I'm converting this to an RFE.

Comment 2 Don Domingo 2014-07-14 05:27:03 UTC
Does this mean that this RFE will not get implemented? Also, is there any good reason that the ability to nest sections was removed to begin with? 

What we have here is a feature that was actually being used by users (OpenStack team), and it has since been taken away. Is there any *practical* use case that made BZ#1097062 absolutely necessary?

Comment 7 Matthew Casperson 2014-07-16 20:40:36 UTC
Initial testing of csprocessor-1.8.1-2 against the dev server shows that specs with topics including nested sections used in initial text containers works as expected with the --skip-nested-section-validation flag.

Will do some more testing though.

Comment 8 Matthew Casperson 2014-07-16 21:03:24 UTC
See Also and Prerequisites links will have to be disabled when using the --skip-nested-section-validation flag. Currently having these links on a topic with nested sections will either fail validation when the spec is built, or create invalid XML that publican can not build.

There is something odd happening with Parts too. The following snippet (where topic 1234 is a topic with nested sections):

Part: Test Part
  Chapter: Release Notes
    Initial Text:
      Release Notes [1234]
    Release Notes [1234] 

Generated the following error:

ERROR: Line 50: Invalid Topic! The Topic specified has content that cannot be used in the initial content of a Chapter/Preface/Section/Appendix/Part.
       -> Release Notes [1234]
ERROR: The Content Specification is not valid.

These snippets work though:

Part: Test Part
  Chapter: Release Notes
#    Initial Text:
#      Release Notes [1234]
    Release Notes [1234] 

or

Part: Test Part
  Chapter: Release Notes
    Initial Text:
      Release Notes [1234]
#    Release Notes [1234]

Comment 10 Matthew Casperson 2014-07-16 21:56:12 UTC
Confirmed that csprocessor-1.8.1-3 fixes the issues with Parts. All other edge cases I could think of worked ok.

Comment 11 Matthew Casperson 2014-07-16 21:57:46 UTC
For future reference, this was the test spec. The revision history and feedback topics, as well as the Release Notes topic had nested sections.

Title = Nested section test
Subtitle = Nested section test
Product = PressGang
Abstract = Abstract
Version = 5
Format = DocBook 4.5
Copyright Holder = Red Hat, Inc
Brand = RedHat
Bug Links = Bugzilla
Default Preface = On
BZProduct = Red Hat OpenStack
BZComponent = doc-Release_Notes
Revision History = [1234]
Author Group = [1235]
Legal Notice = [1236]
Feedback = [1237]
Locale = en-US

[condition = acondition]
Chapter: Chapter with child
  Release Notes [1238] [T1]

Chapter: Chapter with Initial Text
  Initial Text: [T2]
    Release Notes [1238]

Process: Process with nested topics
  Release Notes [1238]
  Release Notes [1238]

Part: Test Part
  Chapter: Release Notes
    Initial Text:
      Release Notes [1238]
    Release Notes [1238]

Appendix: Test Appendix
  Release Notes [1238] [T4]

Comment 12 Lee Newson 2014-07-16 23:13:14 UTC
I just want to note that while the above does let you build content with nested sections, it still is unsupported so if you use nested sections you are using them at your own risk. Some things that will not work are:

- Report a bug and editor links
- Relationships
- Multiple initial text topics with nested sections (this won't validate anyways for other reasons).
- Linking to the nested sections from other topics (you can probably hack a way to do this but there isn't any promise it'll work long term)
- DocBuilder
- The WebUI live rendering

Comment 13 Don Domingo 2014-07-17 01:22:36 UTC
Thanks guys. When can we get csprocessor-1.8.1-3 for testing?

Also:

(In reply to Lee Newson from comment #12)
> I just want to note that while the above does let you build content with
> nested sections, it still is unsupported so if you use nested sections you
> are using them at your own risk. Some things that will not work are:
> 
> - Report a bug and editor links
> - Relationships
> - Multiple initial text topics with nested sections (this won't validate
> anyways for other reasons).
> - Linking to the nested sections from other topics (you can probably hack a
> way to do this but there isn't any promise it'll work long term)
> - DocBuilder
> - The WebUI live rendering

If by 'Relationships' you mean the 'See Also' and 'Prerequisite' links, then that's fine. We don't use them anymore for RHOS5 docs onwards (we use in-topic 'Inject' instead). 

We are OK without the rest of the things on this list as well.

Comment 14 Lee Newson 2014-07-17 02:19:11 UTC
(In reply to Don Domingo from comment #13)
> Thanks guys. When can we get csprocessor-1.8.1-3 for testing?
> 
> Also:
> 
> (In reply to Lee Newson from comment #12)
> > I just want to note that while the above does let you build content with
> > nested sections, it still is unsupported so if you use nested sections you
> > are using them at your own risk. Some things that will not work are:
> > 
> > - Report a bug and editor links
> > - Relationships
> > - Multiple initial text topics with nested sections (this won't validate
> > anyways for other reasons).
> > - Linking to the nested sections from other topics (you can probably hack a
> > way to do this but there isn't any promise it'll work long term)
> > - DocBuilder
> > - The WebUI live rendering
> 
> If by 'Relationships' you mean the 'See Also' and 'Prerequisite' links, then
> that's fine. We don't use them anymore for RHOS5 docs onwards (we use
> in-topic 'Inject' instead). 
> 
> We are OK without the rest of the things on this list as well.

We need to apply a patch to the servers as well, I'll email you guys the details after we do that today. Also yeah that is what I meant by "Relationships".

Comment 15 Lee Newson 2014-11-27 00:33:16 UTC
Closing this as WONTFIX since we do not want to allow nested sections. We have however added the workaround for anyone who specifically wants to use nested sections, but as mentioned above this is done at the writers risk. Additionally using the "--skip-nested-sections" workaround has the side effects mentioned in comment #12.


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