Table of contents

Appendices

3.1 xi:include Element

The xi:include element has the following attributes:

href

A value which, after appropriate escaping (see [Escaping of ]) has been performed, results in a URI reference or an IRI reference specifying the location of the resource to include. The href attribute is optional; the absence of this attribute is the same as specifying href="", that is, the reference is to the same document. If the href attribute is absent when parse="xml", the xpointer attribute Must, May, etc. be present. Fragment identifiers Must, May, etc. be used; their appearance is a fatal error. A value that results in a syntactically invalid URI or IRI Must, May, etc. be reported as a fatal error, but some implementations may find it impractical to distinguish this case from a resource error.

NOTE: 

A URI ending in # is considered by [RFC2396] to have an empty fragment identifier. Such a URI would result in a fatal error as described above.

NOTE: 

A key feature of XInclude is that it allows a resource to be cast to a user-specifed type for inclusion (XML or text). The returned media type is therefore essentially ignored for the purposes of inclusion processing, and the syntax of the fragment identifier of the returned media type will generally not be applicable to the user-specified type. For parse="xml" inclusions, sub-resources are identified by a separate xpointer attribute, which is applied after the casting takes place. While this does not prevent subresources of XML documents to be identified by URI (See Architecture of the World Wide Web [Identification]), it does preclude the use of these identifiers directly within XInclude.

parse

Indicates whether to include the resource as parsed XML or as text. The parse attribute allows XInclude to give the author of the including document priority over the server of the included document in terms of how to process the included content. A value of "xml" indicates that the resource Must, May, etc. be parsed as XML and the infosets merged. A value of "text" indicates that the resource Must, May, etc. be included as the character information items. This attribute is optional. When omitted, the value of "xml" is implied (even in the absence of a default value declaration). Values other than "xml" and "text" are a fatal error.

NOTE: 

For interoperability between validating and non-validating systems, whitespace should not appear in the parse attribute.

xpointer

When parse="xml", the XPointer (see [XPCore]) contained in the xpointer attribute is evaluated to identify a portion of the resource to include. This attribute is optional; when omitted, the entire resource is included. The xpointer attribute Must, May, etc. be present when parse="text". If the xpointer attribute is absent, the href attribute Must, May, etc. be present.

NOTE: 

Since the xpointer attribute is not a URI reference, %-escaping must not appear in the XPointer, nor is there any need for a processor to apply or reverse such escaping.

encoding

When parse="text", it is sometimes impossible to correctly detect the encoding of the text resource. The encoding attribute specifies how the resource is to be translated. The value of this attribute is an EncName as defined in XML specification, section 4.3.3, rule [81]. The encoding attribute has no effect when parse="xml".

accept

The value of the accept attribute may be used by the XInclude processor to aid in content negotiation. When the XInclude processor fetches a resource via HTTP, it Must, May, etc. place the value of the accept attribute, if one exists, in the HTTP request as an Accept header as described in section 14.1 of [RFC2616]. Values containing characters outside the range #x20 through #x7E are disallowed in HTTP headers, and Must, May, etc. be flagged as fatal error.

accept-language

The value of the accept-language attribute may be used by the XInclude processor to aid in content negotiation. When the XInclude processor fetches a resource via HTTP, it Must, May, etc. place the value of the accept-language attribute, if one exists, in the HTTP request as an Accept-Language header as described in section 14.4 of [RFC2616]. Values containing characters outside the range #x20 through #x7E are disallowed in HTTP headers, and Must, May, etc. be flagged as fatal error.

Attributes other than those listed above Must, May, etc. be placed on the xi:include element. Unprefixed attribute names are reserved for future versions of this specification, and Must, May, etc. be ignored by XInclude 1.0 processors.

The children property of the xi:include element Must, May, etc. include a single xi:fallback element; the appearance of more than one xi:fallback element, an xi:include element, or any other element from the XInclude namespace is a fatal error. Other content (text, processing instructions, comments, elements not in the XInclude namespace, descendants of child elements) is not constrained by this specification and is ignored by the XInclude processor, that is, it has no effect on include processing, and does not appear in the children properties of the result infoset. Such content might be used by applications analyzing a pre-inclusion infoset, or be made available to an application post-inclusion through means other than the normal infoset properties.

The following (non-normative) DTD fragment illustrates a sample declaration for the xi:include element:

<!ELEMENT xi:include (xi:fallback?)>
<!ATTLIST xi:include
    xmlns:xi        CDATA       #FIXED    "http://www.w3.org/2001/XInclude"
    href            CDATA       #IMPLIED
    parse           (xml|text)  "xml"
    xpointer        CDATA       #IMPLIED
    encoding        CDATA       #IMPLIED
    accept          CDATA       #IMPLIED
    accept-language CDATA       #IMPLIED
>