Working with Content References

The DITA conref feature (short for content reference) lets you insert
a piece of source content by referencing it from its source. When you need to update that
content, you only need to do it in one place.

There are several strategies for managing content references:

Reusable components - With this strategy, you create a new file for each piece of
content that you want to reuse and you insert references from the content of the reusable
component files. For example, suppose that you have a disclaimer that needs to be included
in certain sections of your documentation. You can create a reusable component that contains
your disclaimer and reuse it as often as you need to. If the disclaimer ever needed to be
updated, you only have to edit it in one file.

Single-source content references - You may prefer to keep many pieces of reusable
content in one file. For example, you might want to create a single file that contains all
the actions that are available in various menus or toolbars for your software application.
Then, wherever you need to describe or display an action in your documentation, you can
reuse content from that single file by inserting content references. This strategy requires
more setup than reusable components, but might make it easier to centrally managing the
reused content and it allows for more flexibility in the XML structure of the reusable
content.

Arbitrary content references - Although it is not recommended, you can create
content references amongst topics without storing the reusable content in components or a
single file. This strategy might make it difficult to manage content that is reused and to
maintain continuity and accuracy, since you may not have any indication that content you are
editing is reused elsewhere.

Oxygen XML Editor creates a reference to the external content by adding a
conref attribute to an element in the local document. The
conref attribute defines a link to the referenced content, made up of a
path to the file and the topic ID within the file. The path may also reference a specific
element ID within the topic. Referenced content is not physically copied to the referencing
file. However, by default Oxygen XML Editor displays it in Author
mode as if it is there in the referencing file. If you do not want referenced content
displayed, open the
Preferences dialog box (Options > Preferences), go to Editor > Edit modes > Author, and deselect the Display referenced content option.

Note: A reference also displays tracked
changes and comments that are included in the source fragment. To edit these
comments (or accept/reject changes) right-click the comment or tracked change and select
Edit Reference.

Tip: To search for references made through a direct
content references, use the Search References action from the
contextual menu.