Non-DITA topic references

A ditamap can include references to non-DITA resources, such as PDF documents, spreadsheet files, presentation files, online tutorials, HTML files, and Internet addresses. The topicref element is used for these references, with format and scope attributes describing the type of resource.

Sometimes, a deliverable document in a DITA workflow will not be made up exclusively of DITA content. For example, a user manual may need to include a PDF form, or a Web site may need to include an interactive Flash tutorial created by another party. In such cases, when specifying the ditamap (a manifest of content for your deliverable document), you may need to include references to non-DITA resources.

These non-DITA resources are referenced through the standard topicref element, but with two attributes set to nominate that the referenced files are non-DITA, and external to the project. These two attributes are format and scope. You would also normally provide a navigation title (navtitle attribute) and lock the title (setting the locktitle attribute to yes) so that the processor doesn't try to retrieve the topic from the referenced resource.

Further, you may want the TOC in the output, generated from the ditamap, to include links to Web sites or e-mail addresses. You can do this by again using the standard topicref element, but with the format attribute set to html and the scope attribute set to external.

The following code example shows a reference to a Web site, and a reference to a PDF file located in a folder relative to the output folder.

<topicref 
  format="html"
  href="http://www.Supara.com.au/"
  locktitle="yes" navtitle="Supara Australia Web Site" scope="external"/>
<topicref format="pdf" href="pdf/2006_impre_brochure.pdf" locktitle="yes" navtitle="Supara Impress 2006 Brochure" scope="peer"/>

Valid format attribute values are:

dita: for DITA topics
html: for HTML or XHTML resources
pdf: for PDF documents
ditamap: for embedded ditamap files

However, the format attribute accepts any string, so if you are referencing another type of resource, you can use the file extension (without the .). For example, if you are referencing a Word 2007 document, you would use docx as the format attribute value.

Valid scope attribute values are:

local: the resource is part of the current content collection
peer: the resource is part of the current content collection, but will not be available when the ditamap is processed (the resource will be separately created)
external: the resource is not part of the current content collection

The scope attribute also has an effect on what window the resource opens in (when generated to a hypertext output).