<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.

Content model

( <data> | <sort-as> )**, <fallback> ?, <foreign> *

In order
  1. Zero or more Zero or more
  2. Optional <fallback>
  3. Zero or more <foreign>

Attributes

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

The following attributes are available on this element: universal attributes and the attributes defined below.

@encoding (inclusion attributes)
Specifies the character encoding to use when translating the character data from the referenced content. The value should be a valid encoding name. If not specified, processors may make attempts to automatically determine the correct encoding, for example using HTTP headers, through analysis of the binary structure of the referenced data, or the <?xml?> processing instruction when including XML as text. The resource should be treated as UTF-8 if no other encoding information can be determined.

When parse="xml", standard XML parsing rules apply for the detection of character encoding. The necessity and uses of @encoding for non-standard values of @parse are implementation-dependent.

@format (link-relationship attributes)
Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.
@href (link-relationship attributes)
Specifies a reference to a resource. See The href attribute for detailed information on supported values and processing implications.
@keyref
Specifies a key name that acts as a redirectable reference based on a key definition within a map. See The keyref attribute for information on using this attribute.
@parse (inclusion attributes)
Specifies the processing expectations for the referenced resource. Processors must support the following values:
text

The contents should be treated as plain text. Reserved XML characters should be displayed, and not interpreted as XML markup.

xml

The contents of the referenced resource should be treated as an XML document, and the referenced element should be inserted at the location of the <include> element. If a fragment identifier is included in the address of the content, processors must select the element with the specified ID. If no fragment identifier is included, the root element of the referenced XML document is selected. Any grammar processing should be performed during resolution, such that default attribute values are explicitly populated. Prolog content must be discarded.

It is an error to use parse="xml" anywhere other than within <foreign> or a specialization thereof.

Processors may support other values for the @parse attribute with proprietary processing semantics. Processors should issue warnings and use <fallback> when they encounter unsupported @parse values. Non-standard @parse instructions should be expressed as URIs.

Note (non-normative):
Proprietary @parse values will likely limit the portability and interoperability of DITA content, so should be used with care.
@scope (link-relationship attributes)
Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See The scope attribute for detailed information on supported values and processing implications.

@type (link-relationship attributes)
Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications.

Examples

This section is non-normative.

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.

Example 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>
Example 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>
Example 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>
Example 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>