Bug 1087097

A few thoughts:

In addition to topics, PressGang could support "fragments" and fragments could be "embedded" into topics. 

So a <para> could be a fragment topic, and could be embedded into another topic using an embed code like <!--_PGEmbed: 11306 -->.

PressGang would perform the embed when rendering the topic and when building a book. Otherwise, when sending it from the REST point to an editor, the editor would be responsible for retrieving and embedding the fragment topic 11306.

As long as the root node of <para> was always enforced for topic 11306, validation would be deterministic.

This feature would probably satisfy https://bugzilla.redhat.com/show_bug.cgi?id=809680 as well.

Using an embed code sounds perfect. 

(In reply to Joshua Wulf from comment #1)
> So a <para> could be a fragment topic, and could be embedded into another
> topic using an embed code like <!--_PGEmbed: 11306 -->.
> 
> PressGang would perform the embed when rendering the topic and when building
> a book. Otherwise, when sending it from the REST point to an editor, the
> editor would be responsible for retrieving and embedding the fragment topic
> 11306.
> 
> As long as the root node of <para> was always enforced for topic 11306,
> validation would be deterministic.

You may find that the Initial Text container will solve the use cases 2, 3 and 4.

Imagine that the following content spec snippet references a topic with an ID of 1234 with a <para> or <formalpara> that provides an overview of a feature.

There are two unique procedure topics with the ids 1235 and 1236.

Chapter: Introduction
  Section: This is a common procedure
    Initial Text:
      A common introduction to a procedure [1234]
      The procedure itself [1235]
  Section: This is a second procedure
    Initial Text:
      A common introduction to a procedure [1234]
      The second procedure [1236]

Essentially the contents of the topics in a Initial Text container are unwrapped and combined into a single section in the output. 

This means that to the reader, the section "This is a common procedure" and "This is a second procedure" appears to be a single unit of information. These sections have one title, and are chunked as a single section would be. 

However, to the writer, these sections are the combination of a common introductory topic, and the unique procedure topic.

The same process can be used for a common warning or note.

The Initial Text container won't let you unwrap one topic inside of another one, so it won't let you have a common step for example. But you can stack common content inside an Initial Text container to achieve most of the outcomes you have listed in the initial bug.

If I understand correctly, that means that if I wanted to insert a "shareable" block inside a topic, then I would have to split that into:

* a topic for all of the content that appears before the shareable block
* a topic for all of the content that appears after the shareable block

And you'd need to do that for every piece of shareable block. 

Now, consider PressGang topics 30449, 30450, and 30451 -- all of which deal with configuring RabbitMQ for different OpenStack components. As you'll see, several <para>s are identical between all three, but a few of them are at the beginning, one at the end, some at the middle, etc. This would mean that if I really wanted to share these identical blocks of text, I'd have to split each topic into at least 5 topics... I'd end up with 15 topics where there should have been 3.

Another thing to consider here is that AFAICT PressGang allows me to search through topics, but not Content Specs. The method you've described is dependent on the use of the CS to combine all those discrete topics to form a cohesive narrative. If other users search through PressGang, how will they know that a complete topic for configuring RabbitMQ for Nova has already been written? They'll probably find the bits, but not how those bits fit together. And while we could probably group different topics together if BZ#752710 gets implemented, will those different topic groups be searchable?

I'm also concerned about how your described method will affect writers who have little experience with single-sourcing. I'm worried that its level of complexity might discourage them from actually practicing it: if I have to split one cohesive topic into 5 unrelated ones just to single-source chunks between 4 major topics, I'm more likely to just avoid single-sourcing altogether.

Whereas I'm confident a simpler workflow would facilitate single-sourcing better:

* Write your topics.
* Find the shared chunks between the topics, make them shaerable blocks.
* Put the topics in Content Specs.

Going back to the PressGang topics I showed, if somebody went and looked for "OpenStack RabbitMQ" topics, he'd find those 3 stand-alone, cohesive topics. And with this feature, upon opening any of those topics they'd also find whichever blocks within are shared. In my experience, they're likely to develop content around the shared blocks whenever possible, thereby promoting content reuse when warranted. 

I'd be happy to sit down and explain the benefits of this feature further, as I feel very strongly about this. :-)