Setting up to use Cross-References

DITA-FMx offers two types of cross-references, a DITA-based cross-reference (the xref element) and a FrameMaker-based cross-reference (the fm-xref element). This distinction only exists within the FrameMaker user interface; when exported to a DITA XML file, both types appear as standard xref 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 set up FrameMaker to use either or both of these cross-reference types. The provided structure applications are set up to use both, the fm-xref element and the xref element.

In the following descriptions, the element names “xref” and “fm-xref” can be replaced with any other element names as long as you have updated the DTD and EDD files accordingly.

To use DITA-based cross-references only

In your EDD, define the xref element as a Container element. When you insert an xref element, DITA-FMx will display the Reference Manager dialog which lets you specify the cross-reference target and optionally some alternate text for the xref. If you’re making an external cross-reference, choose the External Xref button in the Reference Manager.

In the ditafmx.ini file make the following modifications:

• Set General\FmXrefElem to ““ (nothing)
• Set GeneralExport\XrefProcessing to 1
• Set GeneralExport\CrossRefToXref to 0
• Set GeneralExport\DitaXrefElem to xref

To use FrameMaker-based cross-references only

In your EDD, define the xref element as a Cross-Reference element. When you insert an xref element, you’ll get the default FrameMaker cross-reference dialog. Use this dialog to specify the cross-reference target element. On export, DITA-FMx will convert the cross-reference into a valid DITA element (cross-refs will have a type attribute set to “fm:<cross-ref_format>”). On import, the xref will convert back into a FrameMaker-based cross-reference. No read/write rules or other structure application modifications are needed.

In the ditafmx.ini file make the following modifications:

• Set General\FmXrefElem to “xref“
• Set GeneralExport\XrefProcessing to 1
• Set GeneralExport\CrossRefToXref to 0
• Set GeneralExport\DitaXrefElem to xref

To use the same XML element for DITA- and FrameMaker-based cross-references

This uses different elements in FrameMaker but the same element in XML (meaning that you don’t need to modify the DITA DTD files). In your EDD, define the xref element as a Container element and make a copy of xref and name it fm-xref. Change the fm-xref element to a Cross-Reference type and update the general rules for all elements that allowed the xref element as a child to now allow xref and fm-xref elements (replace “xref” with “xref | fm-xref”). Other modifications may be needed to make the new fm-xref element definition valid.

In the ditafmx.ini file make the following modifications:

• Set General\FmXrefElem to fm-xref
• Set GeneralExport\XrefProcessing to 1
• Set GeneralExport\CrossRefToXref to 1
• Set GeneralExport\DitaXrefElem to xref

When you insert an xref element, the plugin will display the Reference Manager, and when you insert an fm-xref element, you’ll get the default FrameMaker cross-reference dialog. On export, DITA-FMx will convert both types of cross-reference data into a valid DITA elements (the FM-based cross-refs will have a type attribute set to “fm:<cross-ref_format>”). On import, each type of xref will convert back into the appropriate cross-reference type. No read/write rules or other structure application modifications are needed.

To use different XML elements for DITA- and FrameMaker-based cross-references

In the DITA DTD and in your EDD, define a new fm-xref (Cross-Reference) element. The xref element should be defined as a Container in the EDD. Other modifications may be needed to make the new fm-xref element definition valid.

In the ditafmx.ini file make the following modifications:

• Set General\FmXrefElem to ““ (nothing)
• Set GeneralExport\XrefProcessing to 1
• Set GeneralExport\CrossRefToXref to 0
• Set GeneralExport\DitaXrefElem to xref

This will allow you to work with both cross-ref types in FrameMaker and they will remain as separate elements in XML.

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 General\FmXrefElem to ““ (nothing)
• Set GeneralExport\XrefProcessing to 0
• Set GeneralExport\CrossRefToXref to 0
• Set GeneralExport\DitaXrefElem to ““ (nothing)