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 “alternate” 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 enable the “Convert Xrefs to Hyperlinks” option in the Book Build Setting dialog. Alternatively, you can 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 (such as 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.

Tip: If you are using FM-based cross-references, always use the Source Type of “Elements,” never use a Source Type of “Paragraphs” or “Cross-Ref Markers.” If the elements that you want to reference are not available, you need to update the EDD as described above.

Advanced Cross-Reference Options

Note: The following information is provided for those who want to change the default functionality for FrameMaker-based cross-references; there is no reason to read further if the default setup is fine for your needs.

To ensure compliance with the DITA specification, when an fm-xref or fm-link element is saved to XML, it is saved to the corresponding DITA element. By default the fm-xref element is saved to the xref element and the fm-link element becomes a link element. When reopened in FrameMaker, these elements convert back into the proper FM-based element. If needed, you can change the way this process works.

To save to specialized xref or link element names.

If your DITA model uses a specialized xref or link elements, as long as the class attribute values indicate the proper inheritance, they should function properly. If you make use of the fm-xref or fm-link functionality, you must choose only one element for each to convert into on file save. To specify an element other than the default xref or link for the fm-xref or fm-link elements make the following changes to the ditafmx.ini file:

Set GeneralExport\XrefProcessing to 1
Set GeneralExport\CrossRefToXref to 1
Set GeneralExport\DitaXrefElem to the “xref” element name
Set GeneralExport\DitaLinkElem to the “link” element name

To write the FM-based cross-reference text to XML.

Normally on file save, the FM-based cross-reference text is not saved to the XML file; it is regenerated on file open. If you want the reference text saved to the XML file, you must modify the ditafmx.ini file as follows:

Set GeneralExport\WriteLinkTextToFmXrefs to 1

To disable all cross-reference processing

If you want to manage all cross-reference processing through read/write rules or XSLT transformations, make the following modifications to the ditafmx.ini file:

Set GeneralExport\XrefProcessing to 0
Set GeneralExport\CrossRefToXref to 0
Set GeneralExport\DitaXrefElem to “” (nothing)
Set GeneralExport\DitaLinkElem to “” (nothing)