A cross-reference is a reference to another part of the document. In an SPS a cross-reference is created in two parts: First, by setting the target of the cross-reference. Second, by defining the link to the target. Setting a target consists of creating a TOC bookmark within a TOC level. The link to the target is a Text Reference within a TOC reference (TOCref). The Text Reference generates the output text and serves as the link. Building a cross-reference therefore consists of the following three steps:
Step 1: Levels
The document is structured into TOC levels as described in the section Structuring the Design in Levels. TOC levels will be used during referencing to specify the scope of the referencing. Only those TOC bookmarks having the specified name and falling within the specified scope will be targeted. In the screenshot below, a level has been created on the n1:Office element.
Step 2: Creating TOC bookmarks
Within a level, a TOC bookmark is created by placing the cursor at the required location, right-clicking, and selecting Insert Table of Contents | TOC Bookmark. The TOC bookmark is given a name and an XPath expression that generates the output text. The XPath expression will typically identify a node in the document, the contents of which is the required text.
In the screenshot below, the TOC bookmark within the n1:Name element has a name of toc3 and an XPath expression that locates the current node. This means that the output text will be the contents of the n1:Name node.
When the XML document is processed, an anchor is created for every n1:Name element. This anchor will have a text reference (the text of the cross-reference) that is the value of the n1:Name element.
Step 3: Creating TOC references
A TOC reference (TOCref) is inserted (context menu, Insert Table of Contents | TOC Reference) to create a link to the anchors generated by a TOC Bookmark.
In the screenshot above, the TOCref named toc3 (screenshot above) is within the same TOC level as the TOC bookmark it references (the Office level). You must also specify the scope of the TOCref. The scope specifies what TOC levels must be searched for TOC bookmarks of the same name as the TOCref. In the example shown above, the scope is the current level. This means that TOC bookmarks within the current level that have a name of toc3 are targeted by this reference.
The screenshot above shows an n1:Office template. When an n1:Office node is processed, an anchor is created with output text that is the content of the n1:Name node. This is because the TOC bookmark specifies in an XPath expression (via the Text from property of the TOC bookmark) that the contents of this node will be the output text. The TOCref in the next line identifies the anchor with the name toc3, and the Text reference component generates the output text of the link to the anchor (purple text in the screenshot below). The output will look something like this:
In the example above, the scope was set to the current level. There are two other possibilities for the scope: (i) a global scope, (ii) scope for the current level and below. With these options, it is possible to also target TOC Bookmarks in other levels of the design.