DITA-FMx User Guide

Using the Reference Manager

Lets you select a conref, xref, or link target by specifying the file, element type, and element.

The Reference Manager is displayed when inserting a conref, xref, or link. To insert a conref, choose Insert Conref from the DITA menu, to insert an xref or link, use the Element Catalog. Note that the Reference Manager is only displayed for xref or link elements if they are defined as a “Container” rather than a “Cross-Reference” element in your EDD.

Figure 1. DITA-FMx Reference Manager

To insert a reference of any kind, first specify the file that contains the reference source. To select a source file, specify the file location using the File Location list. This list will initially only contain the label “Files Currently Open in FrameMaker” but you can choose the Browse button (“...”) to add additional folders to this list for quick access to files in those locations. Selecting “Files Currently Open in FrameMaker” will display those files in the Source File list. Selecting another file location will list all “.xml” and “.dita” files in that folder. If you want to place a reference to a file that is not open, use the Browse button (“...”) to open another file.

By default the Element Tag list displays only elements that have id attribute values in the source file. For conrefs, this list is further restricted by displaying only elements that are valid at the current insertion point. If you want to limit the xref or link targets to a specific list of elements, use the XrefElements parameter in the ditafmx.ini file (for details, see INI-Only Settings). When you select an element tag name from the list, the available target elements display in the Element Data list. By default, only elements that have an ‘id’ value are available, but if you select the Show All Elements option, you will be able to select from all available elements of the selected type (this option is only available if the “Files Currently Open in FrameMaker” file location is selected). The elements are listed with their ‘id’ and textual content. To place the reference, select an element and choose the Insert button. If you have selected an element that does not have an ‘id’ value, you will be prompted to provide an ‘id’ for that element (the ‘id’ is written to the source file, so be sure to save that file before exiting). If you want to specify text for the xref that is different than that of the target element, enter that text in the Alternate Xref Text field. To insert an xref to an external file, choose the External Xref button.

If you double-click a conref or xref, the Reference Manager displays with the current reference selected. Choosing the Replace button inserts a new reference using the selected criteria in place of the old reference.

Note: Replacing an existing reference removes any existing locally applied attribute data.

Conrefs are inserted as a locked range of text (like a text inset) and are tagged with the “DITA-Conref” color. By default this color is defined as blue, but because it is defined in the template, you can change it to suit your needs.

Xrefs and links are also inserted as a locked range of text, but no coloring or formatting is applied other than that specified by your structure application (EDD or template). When an xref or link is created or modified, the type attribute is set to the name of the target element, the format attribute is set to “dita,” and the scope attribute is set to “local.”

Tip: If you’d like more of the title text visible in the Reference Manager, enable the “Use Wide Reference Manager” option in the DITA-FMx Options dialog.

External Xref

Choose the External Xref button in the Reference Manager dialog to insert an xref or link that references files outside of the documentation set. Specify the xref target (the href attribute value) and the xref link text (the content of the xref element), as well as the value for the scope attribute (“external” or “peer”). For URLs, the format attribute is set to “html,” but for other types of file references the format attribute is set to the value of the file extension. For example, if you set the href attribute to “InstallGuide.pdf” the format attribute will be set to “pdf”.

Once an external reference has been created you can modify it by double-clicking the xref.

Figure 2. DITA-FMx External Xref dialog box