Using the Reference Manager

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

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

To insert a reference of either kind, first specify the file that contains the reference source. All files currently open will be available in the Source File drop-down list. If you want to place a reference to a file that is not open, use the Browse button to open another file. For conrefs, the Element Tag list displays all of the elements that are valid at the current insertion point. For xrefs, the Element Tag list displays the all of the elements that are valid xref targets (those that can have an id attribute). If you want to limit the xref 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. 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.

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 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 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.”

External Xref

Choose the External Xref button in the Reference Manager dialog to insert an xref that links to 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.