| Summary: | RFE: Reduce noise with small topics | ||
|---|---|---|---|
| Product: | [Community] PressGang CCMS | Reporter: | Lee Newson <lnewson> |
| Component: | CCMS-Core | Assignee: | Lee Newson <lnewson> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | |
| Severity: | unspecified | Docs Contact: | |
| Priority: | unspecified | ||
| Version: | 1.2 | CC: | lcarlon, mcaspers |
| Target Milestone: | --- | ||
| Target Release: | 1.4 | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | Bug Fix | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2014-02-23 23:44:01 UTC | Type: | Bug |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
| Bug Depends On: | |||
| Bug Blocks: | 1017465 | ||
|
Description
Lee Newson
2013-11-13 22:36:49 UTC
We'll go with this format: Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321] What is Fuzzball [1234] [append=true] What is Foobar [1235] [append=true] What is the Mad Hatter website [1236] [append=true] Downloading Foobar from the Mad Hatter website [1237] Installing Fuzzball in Foobar [1238] At a Chapter level Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321] [append=true] What is Fuzzball [1234] What is Foobar [1235] What is the Mad Hatter website [1236] Downloading Foobar from the Mad Hatter website [1237] Installing Fuzzball in Foobar [1238] Some additional details from planning/working on the implementation of this: 1. If we are to allow only certain topics to be inlined/appended then the <simplesect> approach won't work because it'll produce invalid xml. ie (using the first example above): title, simplesect, simplesect, simplesect, section, section 2. xreflabel will need to be used if we are to leave in "See Also" and "Prerequisite" or even injection links, otherwise the link won't have any text associated with it. However xreflabel is a disallowed attribute based on the PUG, see: http://jfearn.fedorapeople.org/en-US/Publican/4.0/html-single/Users_Guide/index.html#sect-Publican-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes In saying that however the reasons outlined there shouldn't apply to us as the content we put in xreflabel should have been translated. 3. I don't really think "append" is the best verb to use here as it's rather vague. I think "bodyOnly" or "appendToPrevious" would be the better options to use of the options discussed. I personally prefer "bodyOnly" as "append"/"appendToPrevious" doesn't indicate that the title will be removed. 4. I mentioned this during the meeting but said I'd come back to it. I believe to keep with how content specs currently work, the inline attribute should be enclosed in the topic grouping to avoid confusion. ie What is Fuzzball [1234, bodyOnly = true] and for containers Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321] [bodyOnly = true] (the container is placed differently because you are not applying it to the front matter topic, but instead applying it to all elements in the container) Here is an example with some other attributes included: Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321, rev: 248543] [bodyOnly = true, Writer = lnewson] We'd also probably want to print a warning if "bodyOnly" was applied on the Front Matter topic, as it would have no effect. ie Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321, bodyOnly = true] [bodyOnly = true] Will this be valid? If so, then there is no need to have individually appended topics.
Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321] [bodyOnly = true]
What is Fuzzball [1234]
What is Foobar [1235]
What is the Mad Hatter website [1236]
Section: Downloading Foobar from the Mad Hatter website [1237] [bodyOnly = true]
Installing Fuzzball in Foobar [1238]
After talking more about this on IRC we've decided to dump the "bodyOnly" attribute entirely and allow for multiple "Front Matter" topics to be specified using the following format:
Chapter: Installing Fuzzball in Foobar from the Mad Hatter website
Front Matter:
Installing Fuzzball in Foobar from the Mad Hatter website [4321]
What is Fuzzball [1234]
What is Foobar [1235]
What is the Mad Hatter website [1236]
Section: Downloading Foobar from the Mad Hatter website
Front Matter:
Downloading Foobar from the Mad Hatter website [1237]
Installing Fuzzball in Foobar [1238]
Something else [5555]
We need to make sure that the pressgang_website.js file contains sensible mappings for bodyOnly topics. Confirmed building a spec with multiple topics in the initial text, including some that failed validation. Confirmed that trying to add author group, revision history, abstract and legal notice to initial text topics results in validation errors. Confirmed that an empty Initial Text block results in a validation error. The following spec
Chapter: test
a [33]
Section: test 2
Initial Text:
a [34]
b [35]
c [36]
results in the error
WARN: No Subtitle specified, so a default will be used instead.
ERROR: Line 13: Invalid Section! No topics or levels in this Section.
-> Section: test 2
ERROR: The Content Specification is not valid.
I would expect to be able to define a section made up with initial text topics.
Confirmed that relationships between initial text topics result in validation errors. When this spec is saved
Chapter: test
Initial Text: [T1]
About Managed Domains [33]
Appendix: whatever
Initial Text: [R: T1]
Limitations of Domain Mode [34]
Application Server Domain [35]
About Host Controller [36]
the link target on the first initial text is removed, so any subsequent saves result in an invalid spec.
Confirmed that injections point to the initial text topic as expected. (In reply to Matthew Casperson from comment #9) > The following spec > > Chapter: test > a [33] > Section: test 2 > Initial Text: > a [34] > b [35] > c [36] > > results in the error > > WARN: No Subtitle specified, so a default will be used instead. > ERROR: Line 13: Invalid Section! No topics or levels in this Section. > -> Section: test 2 > ERROR: The Content Specification is not valid. > > I would expect to be able to define a section made up with initial text > topics. Good point, a user may want to combine multiple topics without it having to have child content. FWIW this check is in place so that users cannot do the following: Chapter: test a [33] Section: test 2 Initial Text: a [34] as they should just be doing: Chapter: test a [33] a [34] because a "Section" with just one Initial Text topic and no other children is just an ordinary topic and opens up the possibility of hacking the topic title. Anyways this particular issue has been fixed in 1.4-SNAPSHOT build 201402120940. I've updated the check so that it will now only throw the error when the section has no children and only has one initial text topic. (In reply to Matthew Casperson from comment #11) > When this spec is saved > > Chapter: test > Initial Text: [T1] > About Managed Domains [33] > > Appendix: whatever > Initial Text: [R: T1] > Limitations of Domain Mode [34] > Application Server Domain [35] > About Host Controller [36] > > the link target on the first initial text is removed, so any subsequent > saves result in an invalid spec. Fixed in 1.4-SNAPSHOT build 201402121004 This was caused by the target not being added for initial text containers in the string representation. Note: This version is now live on the test/development server. Confirmed that targets on initial text blocks are preserved. Confirmed that sections with more than one topic in initial text are now valid. Confirmed that sections with only one topic in initial text are invalid. |