Setting Up to Use Cross-References
Explains the differences between FrameMaker and DITA based xref or link elements and how they are used.
DITA-FMx offers two types of cross-references, a DITA-based cross-reference (the xref and link elements) and a FrameMaker-based cross-reference (the fm-xref and fm-link elements). This distinction only exists within the FrameMaker user interface; when exported to a DITA XML file, both types appear as standard xref and link elements.
The FrameMaker-based cross-reference is defined as a “Cross-Reference” element in the EDD as opposed to a DITA-based cross-reference which is defined as a “Container” element. FrameMaker-based cross-references take advantage of the formatting capabilities available to “standard” FrameMaker cross-references such as the inclusion of page numbers and additional text (this formatting is defined in the underlying FrameMaker template). DITA-based cross-references will either display the text of the target element or static arbitrary text that is entered when the cross-reference is created.
FrameMaker-based cross-references can only reference another element, while a DITA-based cross-reference can reference another element or content outside of the local scope such as a website. Both cross-reference types have their purpose and it’s up to the author to decide which suits their needs best.
You can use either or both of these cross-reference types. The provided structure applications are set up to use both types of references.
When saved to PDF, the FrameMaker-based cross-references will become live hyperlinks. In order for DITA-based references to become hyperlinks, you must run the Xref to Hyperlink command after generating the book/FM files.
By default, the structure application is set up to only allow fm-xref and fm-link elements to reference other topics (topic, task, concept, and reference elements) and section elements. You can customize the EDD to allow referencing of other elements if needed. In order for an element to appear in the FrameMaker Cross-Reference dialog as a cross-reference target, the “id” attribute of that element must be defined as a type of “UniqueID.” By default, most id attributes are defined as a type of “String.” Just change the type to UniqueID and that element will be listed in the Cross-Reference dialog.