Table of Contents
User Guide

Cross-references (xrefs) are direct links to other files or external resources.


Cross-references enable you to directly link to another file in easyDITA or to external resources, such as websites or PDFs.



Maintenance Considerations

When you use cross references to link to other DITA resources, easyDITA manages the reference for you so if the topic is moved or renamed, the link will still work. Links will not work if the referenced topic is removed from your Content Library , but easyDITA will prevent you from doing so. When you attempt to move a file to the Trash , a warning will display if that file is referenced by any other files. You must remove the reference before moving the file to the trash. 
Also, any files you link to with an cross reference must be included in your publication map. If you fail to include a referenced topic in a map, the map will still publish, but the link won’t work.easyDITA
You can use the varsReports/reportLinkOutOfMapScope in easyDITA to check for any referenced topics that are not included in your map. As an administrator, you can access this in the Reports interface.
Before inserting links to external resources, such as web pages, you should consider the source you’re linking to. Will that web page be there in a year or more? Is it a reliable source? When you link to external resources, you’re relying on it being there in the future so you must consider whether it’s a reliable source.

Publishing Considerations

When using cross references, you should determine a consistent method of inserting links inline and naming your links. We recommend maintaining a consistent presentation of inline links throughout your documentation. For example, you might use the phrase:
“For more information, see _____.”
When determining the naming structure for you links, you have two options. easyDITA can manage link names for you or you can insert your own link text. If you insert a link to another DITA resource, the link will automatically display the title of the resource unless you manually change the link text. If you insert a link to an external resource, you should always insert your own link text. 
When you use cross-reference links to reference an external resource, you should consider the medium for publishing. For example, a link won’t be helpful to the reader if the document is delivered in print. You may want to put these links in their own paragraph or phrase element and apply conditional processing to that element so you can remove the links from certain publishes.