Insert Conref

Displays the Reference Manager which lets you insert a content reference.

The Reference Manager (displayed when you choose DITA-FMx > Insert Conref) allows you to create a content reference (conref or conkeyref) to elements within the same file or in other files.

Select a source file from those currently open or from files in a folder or map (as defined by the File Location option). Select the target element type in the Element Tag list, then select an item from the Element Data list to create a conref to that element. Alternatively, you can use the Key Reference button to select the target content based on a key.

Figure 1. DITA-FMx Reference Manager dialog box

The Element Tag list displays the names of elements that exist in the source file and have an id attribute value. The Element Data list displays the id and text of the available elements.

If you are creating a conref range, select the end element from the Conref End list. Only elements that follow the selected item in the Element Data list are available as a conref end element.

To create a reference to an element defined by a key (conkeyref), choose the Key Reference button. The Keyref Manager dialog lets you select a key from the specified keyspace, then locate the required element id. For a conref, you should select both the key and the element id. Choosing OK in the Keyref Manager inserts the <key>/<elemid> into the Key Reference field.

The referenced element is inserted at the location specified. You can double click the conref to re-open the Reference Manager to change the referenced element or edit the source file. The Reference Manager also lets you display the list of all elements for conrefing (even if they have no id value), you must provide the id value at insertion time.

On the opening of a file, the content of any element included by conref is resolved and displayed as a locked text range (similar to a text inset). The color of conrefs is defined by the “DITA-Conref” color (this is a custom color definition and can be changed in the template). The auto-loading functionality may be enabled/disabled with the Options command.

The Update References command provides an option to load and build the conref elements (if they were not initially loaded by the auto-load functionality), and update the conrefs to reflect changes in the source files.

If you want to “break” a conref (make it into editable text rather than a locked range), select the conref and choose the Flatten Conref command (DITA-FMx > FM File Commands > Flatten Conrefs). To flatten all conrefs in the current file, use the same command, but place the insertion point away from a conref.