This service will be undergoing maintenance at 00:00 UTC, 2017-10-23 It is expected to last about 30 minutes
Bug 1030099 - RFE: Reduce noise with small topics
RFE: Reduce noise with small topics
Status: CLOSED CURRENTRELEASE
Product: PressGang CCMS
Classification: Community
Component: CCMS-Core (Show other bugs)
1.2
Unspecified Unspecified
unspecified Severity unspecified
: ---
: 1.4
Assigned To: Lee Newson
:
Depends On:
Blocks: 1017465
  Show dependency treegraph
 
Reported: 2013-11-13 17:36 EST by Lee Newson
Modified: 2014-02-23 18:44 EST (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2014-02-23 18:44:01 EST
Type: Bug
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 2013-11-13 17:36:49 EST
From an email thread in pressgang-ccms-dev:

I would rather be able to specify individual specific topics in the map as “inline” so they appear without the <section><title>.

A common Docbook structure structure is to start a chapter or section with some introductory overview content, and then sub-sections for the specific areas.

e.g

Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321]
  What is Fuzzball [1234][inline=true]
  What is Foobar [1235][inline=true]
  What is the Mad Hatter website [1236][inline=true]
  Downloading Foobar from the Mad Hatter website [1237]
  Installing Fuzzball in Foobar [1238]

The only catch there would be that you couldn’t have an inline topic after a non-inline one.  Because you can’t have anything after a section other than another section.  Easy enough to check for that in the content map I guess.

Additionally, you might be able to set an attribute on a chapter/section to make all of it’s contents inline, instead of setting them individually.

Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [4321][inlineall=true]

Also I don’t know what the “report a bug” link would use as an ID in this case?

Just a side point that occurred to me just then: It might be better to have the report a bug links near the titles rather than at the end of the content.  

-------------------------------------------------------------------------------

On 11 Nov 2013, at 9:33 am, Matt Casperson <mcaspers@redhat.com> wrote:

I'm not sure we should disable prereqs and see also links because they are still useful constructs. Maybe for virtual chapters (and we should find a better name for that) the prereqs and see also links should be combined and added to the end of the chapter. Or they can only be defined at the chapter level (since the children are like one big front matter topic), like:

Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [Virtual = true] [P: 4321]
  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]

I'd be happy with using titleless simplesects with the fixed urls as ids, and reporting validation issues if any topic uses a simplesect or refentry.

Regards

Matthew Casperson
RHCE, RHCJA # 111-072-237
Engineering Content Services
Brisbane, Australia

-------------------------------------------------------------------------------

From: "Lee Newson" <lnewson@redhat.com>
To: "Matt Casperson" <mcaspers@redhat.com>
Cc: "Lee Carlon" <lcarlon@redhat.com>, pressgang-ccms-dev@redhat.com
Sent: Monday, 11 November, 2013 8:46:42 AM
Subject: Re: Reducing noise with small topics

Hmm, I can see the issue though I'd prefer not to have different types of containers just for how the content should be built. Instead I'd say an attribute would be better suited at the chapter/section level, so something like:

Chapter: Installing Fuzzball in Foobar from the Mad Hatter website [Virtual = 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]

That way someone who's not all that familiar with a spec can still look at it and see it's a chapter  and not wonder what a virtual chapter means. As for the attribute name, I'm sure we can come up with something other than "virtual" that matches the what the attribute actually does. I'd also recommend for virtual chapters/sections if we replace the sections as simplesects with blank titles, as that should have the least chance of breaking anything. As for the other points:

2. For invalid attributes it would go back to the report a bug link issue, so the only problem should be: simplesect and refentry.

3. Couldn't we just set the id (Fixed URL) on the simplesect instead of the section?

The bigger question to me here is where should the prereqs and see also content get injected to (ie if someone on "What is Foobar" add [P: 3737])? To me I think that in this case it shouldn't validate as I can't personally see a use case where someone would want to do this, if not then I can't really see a way that they could be injected nicely (though I'll have more of a think on that one).

4. This pretty much already happens, the only difference would be the title assigned (in the comment section) would be that of the chapter/section instead of the topic. I'd also recommend that the environment field would include the list of topic ids/revisions used in the chapter (currently it only includes the single id)

Cheers Lee

-------------------------------------------------------------------------------

From: "Matt Casperson" <mcaspers@redhat.com>
To: "Lee Carlon" <lcarlon@redhat.com>, pressgang-ccms-dev@redhat.com
Sent: Monday, 11 November, 2013 7:54:22 AM
Subject: Reducing noise with small topics

There is a problem that has emerged in some books where topics are one sentence long, resulting in the final output being very noisy with titles and bug links taking up more space than the actual content itself. 

An example of what is currently happening is:

Chapter: Installing Fuzzball in Foobar from the Mad Hatter website
  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]

If topics 1234, 1235 and 1236 are one or two sentences, then the output looks something like:

Installing Fuzzball in Foobar from the Mad Hatter website

What is Fuzzball
Fuzzball is an application to transform the widget into a thingamajig.
Report a bug.

What is Foobar
Foobar is an execution environment that provides centralised distribution, configuration, reporting and security auditing of applications.
Report a bug.

What is the Mad Hatter website
The Mad Hatter website is provides customers with links to download all applications their subscription entitles them to. It also provides a knowledgebase to aid in solving common issues, and links to official documentation.
Report a bug.

Downloading Foobar from the Mad Hatter website
15 step procedure for downloading the application here
Report a bug

Installing Fuzzball in Foobar
15 step procedure for installing the application here
Report a bug

This output has a lot of unnecessary titles, bug links and other boilerplate content. Lee Carlon has suggested that the chunked output (i.e what is displayed in a single page in the HTML format) should resemble a self contained article rather than an individual topic.

I think a solution would be to implement the notion of a virtual chapter/section in a content spec. Virtual sections would contain multiple topics without titles, and present them as a single chapter/section in the output.

So lets look at a virtual chapter. 

Virtual Chapter: Installing Fuzzball in Foobar from the Mad Hatter website
  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]

This involves very little change in the content spec, but the output changes to:

Installing Fuzzball in Foobar from the Mad Hatter website
 
Fuzzball is an application to transform the widget into a thingamajig.

Foobar is an execution environment that provides centralised distribution, configuration, reporting and security auditing of applications.

The Mad Hatter website is provides customers with links to download all applications their subscription entitles them to. It also provides a knowledgebase to aid in solving common issues, and links to official documentation.

15 step procedure for downloading the application here
 
15 step procedure for installing the application here

Report a bug

So the questions we need to answer are:

Is this useful?

Do the DocBook elements permitted in topics allow us to recombine them into a single chapter or section?
I can't think of any Docbook elements currently allowed in topics that are required to be at the beginning or end of a section, but I'll have to confirm this.

Where do "See Also" and other relationships go when there is no title for topics in a virtual chapter?
I think what should happen here is that the first child of the topic <section> after the <title> (i.e the first "content" Docbook element which is added to the virtual chapter/section) assumes the ID that would be assigned to the section itself, and the xreflabel is set to the title of the topic. So you would have this in the virtual chapter: 
<para id="topic1234" xreflabel="What is Fuzzball">Fuzzball is an application to transform the widget into a thingamajig.</para>
The only difference to xrefs then would be the loss of the toc position prefix (i.e. the "1.2.2" part of "1.2.2 What is Fuzzball").

 What happens to the Report a Bug links?
Losing the Report a Bug links means that we lose the ability to assign a bug to an individual topic. In this case we should expand the environment bugzilla field to be able to map bugs to specs instead of individual topics, and include the title of the virtual chapter/section so authors can work out which collection of topics the bug could belong to.
Regards

Matthew Casperson
RHCE, RHCJA # 111-072-237
Engineering Content Services
Brisbane, Australia
Comment 1 Matthew Casperson 2014-01-13 19:31:14 EST
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]
Comment 2 Lee Newson 2014-01-17 00:32:08 EST
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]
Comment 3 Matthew Casperson 2014-01-19 18:34:59 EST
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]
Comment 4 Lee Newson 2014-01-19 19:17:38 EST
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]
Comment 5 Matthew Casperson 2014-01-20 17:49:09 EST
We need to make sure that the pressgang_website.js file contains sensible mappings for bodyOnly topics.
Comment 8 Matthew Casperson 2014-02-11 18:30:10 EST
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.
Comment 9 Matthew Casperson 2014-02-11 18:32:20 EST
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.
Comment 10 Matthew Casperson 2014-02-11 18:35:04 EST
Confirmed that relationships between initial text topics result in validation errors.
Comment 11 Matthew Casperson 2014-02-11 18:36:36 EST
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.
Comment 12 Matthew Casperson 2014-02-11 18:42:39 EST
Confirmed that injections point to the initial text topic as expected.
Comment 13 Lee Newson 2014-02-11 18:44:39 EST
(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.
Comment 14 Lee Newson 2014-02-11 19:24:09 EST
(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.
Comment 16 Matthew Casperson 2014-02-11 20:48:03 EST
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.

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