Using coderefs

The coderef element lets you directly reference a text file in your documentation.

A coderef is basically a conref to a non-DITA file. If your documentation contains code samples, you can use a coderef to include code samples from the actual code files rather than copying and pasting that content into your document. This allows you to include real, working (and tested) code samples in your documentation rather than running the risk of accidentally modifying that code making it invalid.

To use a coderef, insert the element into a codeblock element. It can be the only element in the codeblock or you can add other content including other coderef elements.

The content of the referenced code file is inserted into FrameMaker as a locked range (like a text inset).

Any tabs within the code file are converted to spaces. By default each tab converts to 4 spaces, but you can set the value in the Authoring Options dialog.

Double-click the coderef to access the Coderef Manager dialog.

Figure 1. DITA-FMx Coderef Manager dialog

Through this dialog, you can edit the code file or modify the referenced file. Use the Key Reference button to select a key to use for referencing the code file.

Figure 2. DITA-FMx Keyref File Browser dialog

By default, when selecting a key reference for a coderef, the Keyref File Browser displays keys that reference all file types. If you want to browse for specific file types, edit the Filter field in the dialog. This field can be set to a space delimited list of one or more file extensions (no wild cards), such as “.txt .java .js”.