Bug 748168

Second priority.

Think about this while implementing the piece above, and try to design to make this possible / easy to implement. If there turns out to be an elegant solution that enables this at the same time, then by all means do them together.

Allow a chapter or a section to be a relationship target.

So, we need two things.

1. The ability to identify a Chapter or Section
2. The ability to specify a Chapter or Section a relationship target

In the Content Spec:

The CS Syntax needs to allow an identifier for a Chapter or Section, so that it can be specified as a target.

It can't be numerical, for the obvious reason that this would ambiguous with topics. N (New Topic identifier), X (reuse New Topic) and C (Clone existing topic) are already taken. Perhaps Z?

Chapter Z23:
 Section Z44:

In Docbook:

Currently Chapters and Sections are written out by the builder with no id attribute. In order to be a link target for an xref they'll require a unique id. Chapter and Section names are not guaranteed to be unique, so simply the name is not reliable.

Can we make Prerequisite relationships part of the tier 1 requirement...?


Syntax Option 1:
Existing Topic Title [32] [R345] [P23, 45]

Syntax Option 2:
Existing Topic Title [32] [R345, P23, P45]

renders as:

<section>
  <title>Existing Topic Title</title>
  
  <formalpara>
    <title>Prerequisites</title>
    <para>
      <itemizedlist>
        <listitem><para><xref linkend="topic23"/></para></listitem>
        <listitem><para><xref linkend="topic45"/></para></listitem>
      </itemizedlist>
    </para>

   [Topic 32 content is here]

  <formalpara>
    <title>Related:</title>
    <para><itemizedlist>
        <listitem><para><xref linkend="topic345"></para></listitem>
    </itemizedlist></para>
  </formalpara>
</section>

Target aliases.

This allows us to:

* include the same topic more than one time in the output (reuse from single source) *and*
* have each of those occurrence have its own unique ID and be a target for relationship links
* specify chapters and sections as targets for relationships

Here is the syntax by example:

1. Specify a new topic in a content spec, include it somewhere else in the book, and have both of those occurrences as a distinct relationship target.
2. Specify a section as a target

Chapter: Fun and Games
  New Topic [N1, Concept] [T1]
  I Point to the first New Topic [23] [R:T1]
  New Topic [X1] [T2] 
  I Point to the second occurrence of New Topic [34] [R:T2, 345]
  Section: I Can be a target too! [T3]
    Some Content [345]
    Some more Content [456]
    New Topic [X1]

Chapter: More Fun and Games
  Did you read that section first? [678] [R:T2] [P:T3] [next:] [prev:]
  Some more Content [456] [T5]
  Make sure you read Some more Content first! [N, Task] [P:T5]

So:

To enable as a link target a chapter or section:
* Add [Txx] after the chapter or section title, where T is the "Target" key glyph, and xxx is a unique numerical ID

To enable as a link target a topic that is included multiple times (whether existing or new):
* Add [Txx] after the [TopicID] specifier (for existing topics), [Nxxx] specifier (for new topics), or [Xyyy] specifier (for reoccurrences of a new topic)

[P: x,y,z] specifies the prerequisites of the topic. These are injected after the topic's <title> element as an itemizedlist with the title "Prerequisites".

[R: x,y,z] specifies the related topics for the topic. These are injected before the topic's </section> tag as an itemizedlist with the title "See also:"

[next: x] takes a single argument and specifies the "Next" topic in a process. It is injected before the related topics (if any exist - so it should be injected before the </section> element before related topics are injected) as:

<para role="next-link">Next: <xref linkend="target_topic_docbook_id"/></para>

[prev: x] takes a single argument and specifies the "Previous" topic in a process. It is injected before the Prerequisites (so after the <title> before Prerequisites are processed) as:

<para role="previous-link">Previous: <xref linkend="target_topic_docbook_id"/></para>

New Feature has been added. 

Relationships can be either a Related, Prerequisite, Next or Previous relationship.

Target's can be applied to any Topic, Chapter, Section or Appendix. Each Topic, Chapter, Section or Appendix may only have one target.

Topic ID's can be used within a relationship if and only if that Topic is used once within the Content Spec. As such all Duplicated Topics can't be directly related. To be able to relate to these topics Targets must be used.

Related Relationships are used by specifying the Related sequence and then a list of Topic or Target ID's. ie [R: 567, N3, T5]

Prerequisite Relationships are used by specifying the Prerequisite sequence and then a list of Topic or Target ID's. ie [P: 567, N3, T5]

Next Relationships are used by specifying the Next keyword and then a Topic or Target ID. ie [Next: 569]

Previous Relationships are used by specifying the Prev keyword and then a Topic or Target ID. ie [Prev: 239]

The book building process will also now incorporate the relationships. Previous relationships will always be under the title, followed by prerequisites. Related topics will be at the very end of the topic and above that will be the Next relationship. Each relationship type is only added if a relationship exists for that type.

Along with the book building, topics now have different names and are duplicated where required. Sections also have a unique ID that corresponds to the LevelID field in the database.

Please avoid using the "Next" and "Previous" relationship types. We are going to obsolete those with bug 749735, which implements a more sophisticated entity, "Process", that supports conditional branching.

Verified with:


CSProcessor client version: 0.17.0
Web Service at http://csprocessor.cloud.lab.eng.bne.redhat.com:8080/ version: 0.21.4