You can use the Manage Internal References tool in Arbortex Editor or Oxygen XML Author to create an internal reference in a DM to elements within the DM. The tool includes all the required markup for the internal reference based on the applicable S1000D issue and assigns a unique ID to the target element if one does not already exist.
Before you begin
You can edit the Manage Internal References tool configuration files to customize the values used to generate markup and populate the list of potential cross-reference target elements before using the tool.
Procedure
- In the editor, open the DM in which you want to create an internal reference.
- Navigate to the place in the DM where you want to create the internal reference.
Note: This must be a location where an xref or internalRef element is allowed.
- Do one of the following.
- In Arbortext Editor, if the Manage Internal References dialog is not visible, select (or Ctrl+Shift+M) to insert markup.
- In Oxygen XML Author, select the tool panel Reference tab.
- Select one of the following element types.
- In an S1000D Issue 3.0 or earlier DM, select
xref
- In an S1000D Issue 4.0 or later DM, select
internalRef
- Click Insert.
The Manage Internal References tool launches, displaying a dialog listing the elements to which you can refer, as in the following example.
Note: The list of potential target elements is determined by the default configuration file named xref_targets_dflt_xxx.txt (where xxx represents the S1000D spec issue with which you are working). The spec issue is included in the file name in three digits without decimals; for example, 420 represents issue 4.2. To populate the list, the tool searches the DM for each element type listed in the applicable default configuration file and lists each such element found. You can control which elements are included in the search by editing the default configuration file.
An element ID is shown for each potential internal reference target. If an element has not already been assigned an ID, the tool generates one (based on values specified in the xref_target_fmt.xml file) and shows it marked with an asterisk (*). In such a case, the ID will be assigned to the target element when you click the Select Xref target or Assign Pending IDs button.
- Optionally, use the Hide/Show IDs button to toggle display of the IDs associated with each potential internal reference target.
- Optionally, use the Filter drop down to filter the list by element type. The drop down shows each applicable target element type with the number of instances found in the DM in parentheses. If the dialog contains a long list of potential internal reference targets, filtering the list can make finding the desired target easier.
- Optionally, assign an ID to each of the elements visible in the list with a pending ID.
Note: If you plan to insert multiple internal references in a single session, assigning all the pending IDs first can save time by eliminating the need for the tool to assign an ID each time a reference is added.
- Select the target element and click Select Xref target.
Results
The tool does the following.
- inserts the required markup for the internal reference
- assigns an ID to the reference target (if one does not already exist)
- closes the dialog