Skip to main content

Add a Cross-Reference to an Element in a Specific Fork

This article is designed to help you when all of the following apply:

  • You have reused the same topic several times in the same publication

  • You want to add a cross-reference to a specific element in the reused topic

  • You want the cross-reference to target a specific instance of the topic, rather than the first instance.

    Note

    Each time a topic appears in a publication, we call it an "instance" of that topic. For each instance, the publication has a separate reference, called a fork.

For example, let's say you have reused a "Reset system" four times in the same publication. You want to add a cross-reference to a para element in the "Reset system" topic, but you specifically want to target the fourth instance of the topic and not the other three. For that, you need to add a cross-reference to a specific element (para) for a specific fork (fourth topic instance).

XML tree view of the reset system topic. A callout points to a specific para element.

Cross-reference is going to target a specific element ...

A publication structure. It has several chapters. 4 of the chapters contain the same reused topic, called Reset system. Callouts point to all 4 of the reused topics, but there is a red cross next to the first three. The fourth reused topic has a green and white check mark.

... in a specific instance of a topic in the publication.

The following steps explain how to set up a cross-reference to an element in a specific instance of a topic:

  1. The element that you are going to cross-reference needs to have an xml:id attribute, otherwise you will be unable to reference it.

    To check if the target element has an xml:id:

    1. Open the topic that contains the target element.

    2. Click inside the target element.

    3. Look in the Element attributes side panel. If the element has an xml:id, it will be listed there.

    To learn how to create an xml:id for an element, see Manually Generate IDs for Cross-references.

  2. Open the topic that will contain the cross-reference.

  3. Position the cursor where you want the cross-reference to appear.

  4. Select the Insert tab.

  5. Select Link and choose Cross-reference in the toolbar. Insert_Link.png

    Insert tab on the main editor.

  6. Enter a Link label. [Optional].

  7. Navigate to the publication.

    Link target section of the new cross-reference dialog. It shows a publication and a list of topics. There is a callout arrow pointing to the publication and also a green and white checkmark. There is a red cross next to each of the topics. This shows that you should expand the publication. Do not select a topic.

    Note

    The cross reference dialog shows the targets both as part of the publication and as topic (outside the publication tree). It is important to select the one in the publication tree to get the fork link!

    Learn the difference between topics and forks, see Topic or Fork.

  8. Open the publication branch and navigate to instance of the topic that has the target element. For example, to link to the fourth instance of a topic, navigate to the fourth instance inside the publication structure.

    Link target section of the new cross-reference dialog. It shows the publication structure and there are two instances of the reset system topic visible. One Reset system instance is labelled 3, and there is a red cross next to it. The other is labelled 4 and there is a green and white check mark next to it.

  9. Select the arrow in front of the topic to see linkable elements.

    Link target dialog. It shows the publication structure and one instance of a Reset system topic is selected. Below it, there is a list of the elements inside the Reset system topic that are available as cross-reference targets.

  10. Select the target element to add a cross-reference to it in your topic.

    link-to-element-in-fork.webp

  11. Select the link in the topic and look in the Element attributes panel. You should see that the link has an xlink:href attribute.

    Element attributes panel shows a link element is selected. The link element has the attribute xlink:href and a value beginning with urn:resource:fork.

    The value for the attribute should have this structure:

    urn:resource:fork:<fork id number>/<element>-idm<element id number>

    For example:

    urn:resource:fork:1665535/para-idm243468712643086

    If your link does not use this structure or has no link at all, repeat this procedure and make sure you:

    • Navigate to the topic instance inside the publication and not directly to the topic itself

    • Link to the element in the appropriate instance of the topic.

  12. Select Save. Save icon.

Note

When you publish to PDF, cross-references to elements in reused topics get the text for the link plus a page number in square brackets.

A bullet list. The first entry is Table 1, "Measurements" [9], the second entry is Table 4, "Measurements" [11], and the third entry is Table 9, "Measurements" [18].