Bug 885564

Just thought I'd jump onboard here. I can't speak for Misha, but I can give an example of a use case. 

Here is a topic that is a special type of overview topic.

<section>
<title>Overview of Openstack Administration</title>
<xref>Installation</xref> - procedures for installing Openstack.
<xref>Configuration</xref> - procedures and explanations of the initial Open Stack configuration tasks
<xref>User administration</xref> - procedures and explanations of integration with directory services. 
</section>


To start with, it presumes that all of the linked topics(or chapters, or parts) are in the built document. Ideally, there would be some logic built into the ccms that, upon encountering this topic during a build, checks to see if the linked topics are in the map.

If they are not, the pre-build will ask if they should be included in the build, dropped from the special overview topic, or if the special overview topic should be dropped from the build.

Sounds about right. The primary use case I had in mind myself was something similar:

http://documentation-devel.engineering.redhat.com/docs/en-US/JBoss_Data_Grid/6.1/html/Administration_and_Configuration_Guide/JBoss_Data_Grid_Cache_Architecture.html

In the XML, I am manually setting up xref linkends pointing to the chapters I want. This seems like a good workaround for now but dangerous if chapter names change.

For Tim's comment the CSP already does this some what. If the links don't exist in a content spec than the topic is replaced with a template that mentions that the links don't exist. If the link is an Injection than it goes further and adds details that the topic needs to be injected into the book.

In saying that though I can't see us ever removing links as they may have contextual importance that we can't decide. As for asking I can't see that either as the build primarily has to be able to be run without user input, so that it can be run on servers and be run identically by anyone without having to know the command options used (ID and Server excluded). So this should be left up to the writers. If you need to use the topic across different books than conditional statements should be used. ie <xref linkend="" condition="cond" />

So in the end this RFE should be about having a way to inject a link to a chapter or section in the same way you inject a topic. That way the CSP can determine the ID of the section/chapter/part to be included in the xref.

Misty mentioned today that the following syntax could be used (or something similar):

Map:

Chapter: Name [T-MyRef]

Topic:

<section>
    <title></title>
    <para> A link to a chapter <!-- Inject: T-MyRef --> or possibly <xref linkend="T-MyRef" /></para>
</section>

To follow the way injections are currently done I think the first would possibly be better.

I think we should be able to do this now that chapters and sections (and parts too) are treated as topics themselves, so suggest closing this off.

*** Bug 989860 has been marked as a duplicate of this bug. ***

I'm going to keep this bug open because while that does cover cases where you use some Front Matter content eg.

Chapter: Introduction [3737]

it only works for those instances. As such we should still provide a way to do this without having to use a Front Matter topic just to do the link.

From the little I've looked into this I believe misty's idea would be the best approach (see comment #4).

So for now the only way to do this is to use a Front Matter Topic with the chapter/appendix/whatever, or to manually set them as Misha said in comment #2.

Added in 1.4-SNAPSHOT build 201402101456

You can now use targets in injections to reference levels (chapters, parts, appendixes, etc...) or topics. The syntax is <!-- Inject: TARGET_ID --> where TARGET_ID is the target in a content spec. When a target doesn't exist the topic is replaced with the error template and an error is added to the error chapter in the build output.

Note: At this stage the UI injected link, links to nothing as we have no way to search for content specs based on the target id.

Tested valid links to link targets ok. Tested invalid links to targets ok. Tested links in UI ok.

Misty documented this feature in Topic 17887. I have removed the admonition to make the feature no longer "aspirational".