<coderef>

Rendering expectations

When evaluated, the <coderef> element causes the target code to be displayed inline. If the target code contains non-XML characters such as '<' or '&', those characters need to be handled so that they can be displayed correctly by the final rendering engine.

Specialization hierarchy

The <coderef> element is specialized from <include>. It is defined in the programming domain module.

Content model

<fallback> ?

Optional <fallback>

Attributes

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

For this element, the @parse attribute has a default value of text.

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 STUB CONTENT for detailed information on supported values and processing implications.

@href (link-relationship attributes)

Specifies a reference to a resource. See STUB CONTENT 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 STUB CONTENT for information on using this attribute.

For HDITA, the equivalent of @keyref is @data-keyref

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

For this element, the @parse attribute has a default value of text.

@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 STUB CONTENT for detailed information on supported values and processing implications.

@type (link-relationship attributes)

Describes the target of a reference. See STUB CONTENT for detailed information on supported values and processing implications.