<include>

Included content is a reference to non-DITA content outside the current document that will be rendered at the location of the reference. The resource is specified using either a URI or a key reference. Processing expectations for the referenced data can also be specified.

Usage information

The <include> element is intended as a base for specialization and for the following use cases:

  • The transclusion of non-DITA XML within <foreign> element using parse="xml"
  • The transclusion of preformatted textual content within <pre> element using parse="text"
  • The transclusion of plain-text prose within DITA elements using parse="text"

In addition, processors can support additional values for the @parse attribute.

For example, the <include> element can be specialized to an element such as <coderef> as a way to include preformatted sample programming code.

The <include> element is not intended to reference DITA content. Use @conref or @conkeyref to reuse DITA content.

Processing expectations

The <include> element instructs processors to insert the contents of the referenced resource at the location of the <include> element. If the content is unavailable to the processor or cannot be processed using the specified @parse value, the contents of the <fallback> element, if any, are presented instead.

Processors SHOULD support the @parse values text and xml.

Processors SHOULD detect the encoding of the referenced document based on the rules described for the @encoding attribute.

Attributes

The following attributes are available on this element: inclusion attributes, link-relationship attributes, universal attributes, and @keyref.

Examples

For the most part, <include> is intended to be used as a base for specialization. The following examples use it directly for purposes of illustration.

Figure 1. Inclusion of XML markup other than SVG or MathML

In the following code sample, the <include> element references a tag library descriptor file:

<fig>
  <title>JSP tag library elements and attributes</title>
  <foreign outputclass="tld">
    <include href="../src/main/webapp/WEB-INF/jsp-tag-library.tld"
             parse="xml" format="tld"/>
  </foreign>
</fig>
Figure 2. Inclusion of README text into a DITA topic, with fallback

In the following code sample, a README text file is referenced in order to reuse a list of changes to a set of source code:

<topic id="readme">
  <title>Summary of changes</title>
  <shortdesc>This topic describes changes in the project source code.</shortdesc>
  <body>
    <section>
      <include href="../src/README.txt" parse="text" encoding="UTF-8">
        <fallback>See README.txt in the source package for a list of changes.</fallback>
      </include>
    </section>
  </body>
</topic>
Figure 3. Inclusion of preformatted text

In the following code sample, the <include> element references a JSON file:

<pre>
  <include href="../src/config.json" format="json" parse="text" encoding="UTF-8"/>
</pre>
Figure 4. Proprietary vendor handling for CSV tables

In the following code sample, the <include> element specifies a proprietary @parse value that instructs a processor how to render a comma-separated data set within the figure:

<fig>
  <title>Data Table</title>
  <include href="data.csv" encoding="UTF-8"
    parse="http://www.example.com/dita/includeParsers/csv-to-simpletable"/>
</fig>