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 disable the Display referenced content option.