Table of contents

Appendices

4.2 Included Items when

When parse="xml", the include location is dereferenced, the resource is fetched, and an infoset is created by parsing the resource as if the media type were application/xml (including character encoding determination).

NOTE: 

The specifics of how an infoset is created are intentionally unspecified, to allow for flexibility by implementations and to avoid defining a particular processing model for components of the XML architecture. Particulars of whether DTD or XML schema validation are performed, for example, are not constrained by this specification.

NOTE: 

The character encodings of the including and included resources can be different. This does not affect the resulting infoset, but might need to be taken into account during any subsequent serialization.

Resources that are unavailable for any reason (for example the resource doesn't exist, connection difficulties or security restrictions prevent it from being fetched, the URI scheme isn't a fetchable one, the resource is in an unsupported encoding, or the resource is determined through implementation-specific mechanisms not to be XML) result in a resource error. Resources that contain non-well-formed XML result in a fatal error.

NOTE: 

The distinction between a resource error and a fatal error is somewhat implementation-dependent. Consider an include location returning an HTML document, perhaps as an error page. One processor might determine that no infoset can be created from the resource (by examining the media type, for example) and raise a resource error, enabling fallback behavior. Another processor with no such heuristics might attempt to parse the non-XML resource as XML and encounter a well-formedness (fatal) error.

xi:include elements in this infoset are recursively processed to create the acquired infoset. For an intra-document reference (via xpointer attribute) the source infoset is used as the acquired infoset.

The portion of the acquired infoset to be included is called the inclusion target. The document information item of the acquired infoset serves as the inclusion target unless the xpointer attribute is present and identifies a subresource. XPointers of the forms described in [XPCore] and [XPElement] Must, May, etc. be supported. XInclude processors optionally support other forms of XPointer such as that described in [XPointer]. An error in the XPointer is a resource error.

The [XPointer] is not specified in terms of the [XMLIS], but instead is based on the [XPath] Data Model, because the XML Information Set had not yet been developed. The mapping between XPath node locations and information items is straightforward. However, xpointer() assumes that all entities have been expanded. Thus it is a fatal error to attempt to resolve an xpointer() scheme on a document that contains unexpanded entity reference information items.

The set of top-level included items is derived from the acquired infoset as follows.

Document Information Items[top]

The inclusion target might be a document information item (for instance, no specified xpointer attribute, or an XPointer specifically locating the document root.) In this case, the set of top-level included items is the children of the acquired infoset document information item, except for the document type declaration information item child, if one exists.

NOTE: 

The XML Information Set specification does not provide for preservation of white space outside the document element. XInclude makes no further provision to preserve this white space.

Multiple Nodes[top]

The inclusion target might consist of more than a single node. In this case the set of top-level included items is the set of information items from the acquired infoset corresponding to the nodes referred to by the XPointer, in the order in which they appear in the acquired infoset.

Range Locations[top]

The inclusion target might be a location set that represents a range or a set of ranges.

Each range corresponds to a set of information items in the acquired infoset. An information item is said to be selected by a range if it occurs after (in document order) the starting point of the range and before the ending point of the range. An information item is said to be partially selected by a range if it contains only the starting point of the range, or only the ending point of the range. By definition, a character information item cannot be partially selected.

The set of top-level included items is the union, in document order with duplicates removed, of the information items either selected or partially selected by the range. The children property of selected information items is not modified. The children property of partially selected information items is the set of information items that are in turn either selected or partially selected, and so on.

Point Locations[top]

The inclusion target might be a location set that represents a point. In this case the set of included items is empty.

Element, Comment, and Processing Instruction Information Items[top]

The inclusion target might be an element node, a comment node, or a processing instruction node, respectively representing an element information item, a comment information item, or a processing instruction information item. In this case the set of top-level included items consists of the information item corresponding to the element, comment, or processing instruction node in the acquired infoset.

Attribute and Namespace Declaration Information Items[top]

It is a fatal error for the inclusion target to be an attribute node or a namespace node.

Inclusion Loops[top]

When recursively processing an xi:include element, it is a fatal error to process another xi:include element with an include location and xpointer attribute value that have already been processed in the inclusion chain.

In other words, the following are all legal:

• An xi:include element Must, May, etc. reference the document containing the include element, when parse="text".

• An xi:include element Must, May, etc. identify a different part of the same local resource (same href, different xpointer).

• Two non-nested xi:include elements Must, May, etc. identify a resource which itself contains an xi:include element.

The following are illegal:

• An xi:include element pointing to itself or any ancestor thereof, when parse="xml".

• An xi:include element pointing to any include element or ancestor thereof which has already been processed at a higher level.