Bug 711334

Maybe to future-proof ourselves we should just have two generic injection points, <pre-content> (after the title) and <post-content> (before the </section>), and then express topic-type-specific logic in the builder.

It might seem counter-intuitive to put that logic into the builder,  but at least then it's in one place. To make changes to the topic assembly pattern at the moment (for example, to swap the relative positioning of the related tasks and related concepts blocks) will require us to retro-actively go back and change the topic content of all existing topics.

We could achieve some separation of concerns by injecting a user-defined injection block per-topic. So each topic type would have an injection block that we define somewhere, and we inject that, then process it.

Or we just hard code it. I'm not sure how generic or flexible the builder is at the moment; however, I just realized that we are in a very precarious situation by hardcoding the topic assembly pattern into each topic, and we should move it out where we can change it without having to change every existing topic.

References: 

Topic Assembly Pattern: http://ecs.pad.engineering.redhat.com/Topic-Assembly-Pattern
Current Implementation Mechanism of Topic Assembly Injection Points: https://svn.devel.redhat.com/repos/ecs/TopicRepository/Templates/Reference.xml

The per-topic-type injection idea looks like this in xml pseudo-code:

<concept>
  <title>O Hai!</title>
  <!-- Injection: Pre-content -->

  Topic content is here
  
  <!-- Injection: Post-content -->
</concept>


Then somewhere outside the actual topic assembly code we have per-topic injection assembly definitions:

<injection-assembly>
  <topic-type>concept</topic-type>
  <content-injection-block key="Pre-content">
     <item>
        <related>Concept_Overviews</related>
     </item>
     <item>
        <related>Task_Overviews</related>
     </item>
   </content-injection-block>
   <content-injection-block key="Post-content">
     <item>
        <related>References</related>
     </item>
   </content-injection-block>   
</injection-assembly>

Then the builder does it in two steps:

1. First it injects the custom injection assembly;
2. Then it processes the injection assembly.

That way we can write generic assembly code and (reasonably) generic topic templates, and have flexibility to change the Topic Assembly pattern.

Fixed in 20110629-1322.

Injection points are now defined by the DocbookBuilder.insertGenericInjectionLinks() function. The comments that were used previously are ignored.