You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1190 lines
90 KiB
1190 lines
90 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html lang="EN"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>XML Inclusions (XInclude) Version 1.0 (Second Edition)</title><style type="text/css">
|
|
code { font-family: monospace; }
|
|
|
|
div.constraint,
|
|
div.issue,
|
|
div.note,
|
|
div.notice { margin-left: 2em; }
|
|
|
|
ol.enumar { list-style-type: decimal; }
|
|
ol.enumla { list-style-type: lower-alpha; }
|
|
ol.enumlr { list-style-type: lower-roman; }
|
|
ol.enumua { list-style-type: upper-alpha; }
|
|
ol.enumur { list-style-type: upper-roman; }
|
|
|
|
|
|
div.exampleInner pre { margin-left: 1em;
|
|
margin-top: 0em; margin-bottom: 0em}
|
|
div.exampleOuter {border: 4px double gray;
|
|
margin: 0em; padding: 0em}
|
|
div.exampleInner { background-color: #d5dee3;
|
|
border-top-width: 4px;
|
|
border-top-style: double;
|
|
border-top-color: #d3d3d3;
|
|
border-bottom-width: 4px;
|
|
border-bottom-style: double;
|
|
border-bottom-color: #d3d3d3;
|
|
padding: 4px; margin: 0em }
|
|
div.exampleWrapper { margin: 4px }
|
|
div.exampleHeader { font-weight: bold;
|
|
margin: 4px}
|
|
</style><link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-REC.css"></head><body><div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a></p>
|
|
<h1><a name="title" id="title"></a>XML Inclusions (XInclude) Version 1.0 (Second Edition)</h1>
|
|
<h2><a name="w3c-doctype" id="w3c-doctype"></a>W3C Recommendation 15 November 2006</h2><dl><dt>This version:</dt><dd>
|
|
<a href="http://www.w3.org/TR/2006/REC-xinclude-20061115/">http://www.w3.org/TR/2006/REC-xinclude-20061115/</a>
|
|
</dd><dt>Latest version:</dt><dd>
|
|
<a href="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</a>
|
|
</dd><dt>Previous versions:</dt><dd>
|
|
<a href="http://www.w3.org/TR/2006/PER-xinclude-20061003/">http://www.w3.org/TR/2006/PER-xinclude-20061003/</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd><dt>Editors:</dt><dd>Jonathan Marsh, Microsoft <a href="mailto:jmarsh@microsoft.com"><jmarsh@microsoft.com></a></dd><dd>David Orchard, BEA Systems <a href="mailto:dorchard@bea.com"><dorchard@bea.com></a></dd><dd>Daniel Veillard <a href="mailto:daniel@veillard.com"><daniel@veillard.com></a> - Second Edition</dd></dl><p>Please refer to the <a href="http://www.w3.org/XML/2006/11/xinclude-errata/"><strong>errata</strong></a> for this document, which may
|
|
include some normative corrections.</p><p>See also <a href="http://www.w3.org/2003/03/Translations/byTechnology?technology=xinclude10"><strong>translations</strong></a>.</p><p>This document is also available in these non-normative formats: <a href="http://www.w3.org/TR/2006/REC-xinclude-20061115/REC-xinclude-20061115.xml">XML</a> and <a href="http://www.w3.org/TR/2006/REC-xinclude-20061115/REC-xinclude-20061115-review.html">XHTML with color-coded revision indicators</a>.</p><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2006 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr><div>
|
|
<h2><a name="abstract" id="abstract"></a>Abstract</h2><p>This document specifies a processing model and syntax for general
|
|
purpose inclusion. Inclusion is accomplished by merging a
|
|
number of XML information sets into a single composite infoset.
|
|
Specification of the XML documents (infosets) to be merged and
|
|
control over the merging process is expressed in XML-friendly
|
|
syntax (elements, attributes, URI references).</p></div><div>
|
|
<h2><a name="status" id="status"></a>Status of this Document</h2><p>
|
|
<em>This section describes the status of this document at the time of its
|
|
publication. Other documents may supersede this document. A list of current
|
|
W3C publications and the latest revision of this technical report can be found
|
|
in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
|
|
http://www.w3.org/TR/.</em>
|
|
</p><p>This document has been produced by the
|
|
<a href="http://www.w3.org/XML/Core/">W3C XML Core Working Group</a> as part
|
|
of the <a href="http://www.w3.org/XML/Activity">XML Activity</a>.
|
|
The English version of this specification is the only normative version. However,
|
|
for translations of this document, see <a href="http://www.w3.org/2003/03/Translations/byTechnology?technology=xinclude10">http://www.w3.org/2003/03/Translations/byTechnology?technology=xinclude10</a>.</p><p>This document is a W3C Recommendation. This second edition is not a
|
|
new version of XInclude. As a convenience to readers, it incorporates
|
|
the changes dictated by the accumulated errata (available at <a href="http://www.w3.org/2004/12/xinclude-errata/">http://www.w3.org/2004/12/xinclude-errata/</a>
|
|
to the <a href="http://www.w3.org/TR/2004/REC-xinclude-20041220/">First
|
|
Edition of XInclude 1.0</a>, dated 20 December 2004, which it supersedes.</p><p>Please report errors in this document to the public <a href="mailto:www-xml-xinclude-comments@w3.org">www-xml-xinclude-comments@w3.org</a> mailing-list;
|
|
<a href="http://lists.w3.org/Archives/Public/www-xml-xinclude-comments/">archives</a> are available.
|
|
The errata list for this edition is available at <a href="http://www.w3.org/XML/2006/11/xinclude-errata/">http://www.w3.org/XML/2006/11/xinclude-errata/</a>.</p><p> Known implementations are documented in the
|
|
XInclude Implementation Report at <a href="http://www.w3.org/XML/2004/xinclude-implementation/report.html">http://www.w3.org/XML/2004/xinclude-implementation/report.html</a>. A
|
|
Test Suite is maintained at <a href="http://www.w3.org/XML/Test/XInclude/">http://www.w3.org/XML/Test/XInclude/</a> to
|
|
help in assessing conformance to this specification. The latest
|
|
release of the Test Suite includes new test cases which implementers
|
|
can use to check their conformance to the changes included in this new
|
|
edition.</p><p>This document has been reviewed by W3C Members, by software
|
|
developers, and by other W3C groups and interested parties, and is
|
|
endorsed by the Director as a W3C Recommendation. It is a stable
|
|
document and may be used as reference material or cited from another
|
|
document. W3C's role in making the Recommendation is to draw attention
|
|
to the specification and to promote its widespread deployment. This
|
|
enhances the functionality and interoperability of the Web.</p><p>This document is governed by the <a href="http://www.w3.org/TR/2002/NOTE-patent-practice-20020124">24 January 2002 CPP</a> as amended by the <a href="http://www.w3.org/2004/02/05-pp-transition">W3C Patent Policy Transition Procedure</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/18796/status">public list of any patent
|
|
disclosures</a> made in connection with the deliverables of the group;
|
|
that page also
|
|
includes instructions for disclosing a patent. An individual who has
|
|
actual knowledge of a patent which the individual believes contains
|
|
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance
|
|
with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p></div><div class="toc">
|
|
<h2><a name="contents" id="contents"></a>Table of Contents</h2><p class="toc">1 <a href="#intro">Introduction</a><br>
|
|
1.1 <a href="#rel-xlink">Relationship to XLink</a><br>
|
|
1.2 <a href="#rel-extent">Relationship to XML External Entities</a><br>
|
|
1.3 <a href="#rel-dtd">Relationship to DTDs</a><br>
|
|
1.4 <a href="#rel-xsd">Relationship to XML Schemas</a><br>
|
|
1.5 <a href="#rel-inc">Relationship to Grammar-Specific Inclusions</a><br>
|
|
2 <a href="#terminology">Terminology</a><br>
|
|
3 <a href="#syntax">Syntax</a><br>
|
|
3.1 <a href="#include_element">xi:include Element</a><br>
|
|
3.2 <a href="#fallback_element">xi:fallback Element</a><br>
|
|
4 <a href="#processing">Processing Model</a><br>
|
|
4.1 <a href="#include-location">The Include Location</a><br>
|
|
4.1.1 <a href="#IRIs">Escaping of href attribute values</a><br>
|
|
4.1.2 <a href="#content-negotiation">Using XInclude with Content Negotiation</a><br>
|
|
4.2 <a href="#xml-included-items">Included Items when parse="xml"
|
|
</a><br>
|
|
4.2.1 <a href="#docii">Document Information Items</a><br>
|
|
4.2.2 <a href="#multiple-nodes">Multiple Nodes</a><br>
|
|
4.2.3 <a href="#ranges">Range Locations</a><br>
|
|
4.2.4 <a href="#points">Point Locations</a><br>
|
|
4.2.5 <a href="#elements">Element, Comment, and Processing Instruction Information Items</a><br>
|
|
4.2.6 <a href="#attributes">Attribute and Namespace Declaration Information Items</a><br>
|
|
4.2.7 <a href="#loops">Inclusion Loops</a><br>
|
|
4.3 <a href="#text-included-items">Included Items when parse="text"
|
|
</a><br>
|
|
4.4 <a href="#fallback">Fallback Behavior</a><br>
|
|
4.5 <a href="#creating-result">Creating the Result Infoset</a><br>
|
|
4.5.1 <a href="#unparsed-entities">Unparsed Entities</a><br>
|
|
4.5.2 <a href="#notations">Notations</a><br>
|
|
4.5.3 <a href="#references-property">
|
|
references Property Fixup</a><br>
|
|
4.5.4 <a href="#namespaces">Namespace Fixup</a><br>
|
|
4.5.5 <a href="#base">Base URI Fixup</a><br>
|
|
4.5.6 <a href="#language">Language Fixup</a><br>
|
|
4.5.7 <a href="#properties">Properties Preserved by the Infoset</a><br>
|
|
5 <a href="#conformance">Conformance</a><br>
|
|
5.1 <a href="#markup">Markup Conformance</a><br>
|
|
5.2 <a href="#application">Application Conformance</a><br>
|
|
5.3 <a href="#infoset">XML Information Set Conformance</a><br>
|
|
</p>
|
|
<h3><a name="appendices" id="appendices"></a>Appendices</h3><p class="toc">A <a href="#references">References</a><br>
|
|
B <a href="#nn-refs">References</a> (Non-Normative)<br>
|
|
C <a href="#examples">Examples</a> (Non-Normative)<br>
|
|
C.1 <a href="#basic-example">Basic Inclusion Example</a><br>
|
|
C.2 <a href="#text-example">Textual Inclusion Example</a><br>
|
|
C.3 <a href="#xml-as-text-example">Textual Inclusion of XML Example</a><br>
|
|
C.4 <a href="#fragment-example">Fragment Inclusion Example</a><br>
|
|
C.5 <a href="#range-example">Range Inclusion Example</a><br>
|
|
C.6 <a href="#fallback-example">Fallback Example</a><br>
|
|
</p></div><hr><div class="body"><div class="div1">
|
|
<h2><a name="intro" id="intro"></a>1 Introduction</h2><p>Many programming languages provide an inclusion mechanism to
|
|
facilitate modularity. Markup languages also often have need of
|
|
such a mechanism. This specification introduces a generic mechanism
|
|
for merging XML documents (as represented by their information sets)
|
|
for use by applications that need such a facility. The syntax
|
|
leverages existing XML constructs - elements, attributes, and URI
|
|
references.</p><div class="div2">
|
|
<h3><a name="rel-xlink" id="rel-xlink"></a>1.1 Relationship to XLink</h3><p>XInclude differs from the linking features described in the
|
|
<a href="#XLink">[XML Linking Language]</a>, specifically links with the
|
|
attribute value <code>show="embed"</code>. Such links provide
|
|
a media-type independent syntax for indicating that a resource
|
|
is to be embedded graphically within the display of the document.
|
|
XLink does not specify a specific processing model, but simply
|
|
facilitates the detection of links and recognition of associated
|
|
metadata by a higher level application.</p><p>XInclude, on the other hand, specifies a media-type specific
|
|
(XML into XML) transformation. It defines a specific processing
|
|
model for merging information sets. XInclude processing occurs
|
|
at a low level, often by a generic XInclude processor which makes
|
|
the resulting information set available to higher level
|
|
applications.</p><p>Simple information item inclusion as described in this specification
|
|
differs from transclusion, which preserves contextual
|
|
information such as style.</p></div><div class="div2">
|
|
<h3><a name="rel-extent" id="rel-extent"></a>1.2 Relationship to XML External Entities</h3><p>There are a number of differences between XInclude and
|
|
<a href="#XML">[XML 1.0]</a> or <a href="#XML11">[XML 1.1]</a> external entities
|
|
which make them complementary technologies.</p><p>Processing of external entities (as with the rest of DTDs)
|
|
occurs at parse time. XInclude operates on information sets
|
|
and thus is orthogonal to parsing.</p><p>Declaration of external entities requires a DTD or internal subset.
|
|
This places a set of dependencies on inclusion, for instance, the syntax
|
|
for the DOCTYPE declaration requires that the document element be named -
|
|
orthogonal to inclusion in many cases. Validating parsers
|
|
must have a complete content model defined. XInclude is orthogonal
|
|
to validation and the name of the document element.</p><p>External entities provide a level of indirection - the external
|
|
entity must be declared and named, and separately invoked.
|
|
XInclude uses direct references. Applications which generate
|
|
XML output incrementally can benefit from not having to pre-declare
|
|
inclusions.</p><p>Failure to load an external entity is normally a fatal error.
|
|
XInclude allows the author to provide default content that will be
|
|
used if the remote resource cannot be loaded.</p><p>The syntax for an internal subset is cumbersome to many authors
|
|
of simple well-formed XML documents. XInclude syntax is based on
|
|
familiar XML constructs.</p></div><div class="div2">
|
|
<h3><a name="rel-dtd" id="rel-dtd"></a>1.3 Relationship to DTDs</h3><p>XInclude defines no relationship to DTD validation. XInclude
|
|
describes an infoset-to-infoset transformation and not a change
|
|
in XML parsing behavior. XInclude does not define a
|
|
mechanism for DTD validation of the resulting infoset.</p></div><div class="div2">
|
|
<h3><a name="rel-xsd" id="rel-xsd"></a>1.4 Relationship to XML Schemas</h3><p>XInclude defines no relationship to the augmented infosets
|
|
produced by applying an XML schema. Such an augmented infoset
|
|
can be supplied as the input infoset, or such augmentation might
|
|
be applied to the infoset resulting from the inclusion.</p></div><div class="div2">
|
|
<h3><a name="rel-inc" id="rel-inc"></a>1.5 Relationship to Grammar-Specific Inclusions</h3><p>Special-purpose inclusion mechanisms have been introduced
|
|
into specific XML grammars. XInclude provides a generic mechanism
|
|
for recognizing and processing inclusions, and as such can offer
|
|
a simpler overall authoring experience, greater performance, and
|
|
less code redundancy.</p></div></div><div class="div1">
|
|
<h2><a name="terminology" id="terminology"></a>2 Terminology</h2><p>
|
|
[<a name="dt-must" id="dt-must" title="Must, May, etc.">Definition</a>: The key words
|
|
<b>must</b>, <b>must not</b>, <b>required</b>,
|
|
<b>shall</b>, <b>shall not</b>, <b>should</b>,
|
|
<b>should not</b>, <b>recommended</b>, <b>may</b>,
|
|
and <b>optional</b> in this specification are to be interpreted
|
|
as described in <a href="#RFC2119">[IETF RFC 2119]</a>.]
|
|
</p><p>
|
|
[<a name="dt-infoset" id="dt-infoset" title="infoset">Definition</a>: The term <b>information
|
|
set</b> refers to the output of an <a href="#XML">[XML 1.0]</a> or
|
|
<a href="#XML11">[XML 1.1]</a> processor, expressed as a
|
|
collection of information items and properties as defined by the
|
|
<a href="#XMLIS">[XML Information Set]</a> specification.] In this document
|
|
the term <em>infoset</em> is used as a synonym for
|
|
<em>information set</em>.</p><p>
|
|
[<a name="dt-error" id="dt-error" title="fatal error">Definition</a>: The term <b>fatal
|
|
error</b> refers to the presence of factors that prevent normal
|
|
processing from continuing.]
|
|
[<a name="dt-resource-error" id="dt-resource-error" title="resource error">Definition</a>: The term
|
|
<b>resource error</b> refers to a failure of an attempt to
|
|
fetch a resource from a URL.] XInclude
|
|
processors <a title="Must, May, etc." href="#dt-must">must</a> stop processing
|
|
when encountering errors other than
|
|
<a title="resource error" href="#dt-resource-error">resource errors</a>, which
|
|
<a title="Must, May, etc." href="#dt-must">must</a> be handled as described in
|
|
<a href="#fallback"><b>4.4 Fallback Behavior</b></a>.</p></div><div class="div1">
|
|
<h2><a name="syntax" id="syntax"></a>3 Syntax</h2><p>XInclude defines a namespace associated with the URI
|
|
<code>http://www.w3.org/2001/XInclude</code>. The XInclude namespace contains two
|
|
elements with the local names <code>include</code> and
|
|
<code>fallback</code>. For convenience, within this specification
|
|
these elements are referred to as <code>xi:include</code> and
|
|
<code>xi:fallback</code> respectively.</p><p>The following (non-normative) XML schema <a href="#XMLSchemas">[XML Schemas]</a>
|
|
illustrates the content model of the <code>xi</code> namespace:</p><div class="exampleInner"><pre>
|
|
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
targetNamespace="http://www.w3.org/2001/XInclude"
|
|
finalDefault="extension">
|
|
|
|
<xs:element name="include" type="xi:includeType" />
|
|
|
|
<xs:complexType name="includeType" mixed="true">
|
|
<xs:choice minOccurs='0' maxOccurs='unbounded' >
|
|
<xs:element ref='xi:fallback' />
|
|
<xs:any namespace='##other' processContents='lax' />
|
|
<xs:any namespace='##local' processContents='lax' />
|
|
</xs:choice>
|
|
<xs:attribute name="href" use="optional" type="xs:anyURI"/>
|
|
<xs:attribute name="parse" use="optional" default="xml"
|
|
type="xi:parseType" />
|
|
<xs:attribute name="xpointer" use="optional" type="xs:string"/>
|
|
<xs:attribute name="encoding" use="optional" type="xs:string"/>
|
|
<xs:attribute name="accept" use="optional" type="xs:string"/>
|
|
<xs:attribute name="accept-language" use="optional" type="xs:string"/>
|
|
<xs:anyAttribute namespace="##other" processContents="lax"/>
|
|
</xs:complexType>
|
|
|
|
<xs:simpleType name="parseType">
|
|
<xs:restriction base="xs:token">
|
|
<xs:enumeration value="xml"/>
|
|
<xs:enumeration value="text"/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
<xs:element name="fallback" type="xi:fallbackType" />
|
|
|
|
<xs:complexType name="fallbackType" mixed="true">
|
|
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
|
<xs:element ref="xi:include"/>
|
|
<xs:any namespace="##other" processContents="lax"/>
|
|
<xs:any namespace="##local" processContents="lax"/>
|
|
</xs:choice>
|
|
<xs:anyAttribute namespace="##other" processContents="lax" />
|
|
</xs:complexType>
|
|
|
|
</xs:schema>
|
|
</pre></div><div class="div2">
|
|
<h3><a name="include_element" id="include_element"></a>3.1 xi:include Element</h3><p>The <code>xi:include</code> element has the following
|
|
attributes:</p><dl><dt class="label">href</dt><dd><p>A value which, after appropriate escaping (see <a href="#IRIs"><b>4.1.1 Escaping of href attribute values</b></a>)
|
|
has been performed, results in a URI reference or an
|
|
<a title="IRI reference" href="#dt-IRI">IRI reference</a>
|
|
specifying the location of the resource to
|
|
include. The <code>href</code> attribute is optional; the
|
|
absence of this attribute is the same as specifying
|
|
<code>href=""</code>, that is, the reference is to the same
|
|
document. If the <code>href</code> attribute is absent when
|
|
<code>parse="xml"</code>, the <code>xpointer</code> attribute
|
|
<a title="Must, May, etc." href="#dt-must">must</a> be present. Fragment
|
|
identifiers <a title="Must, May, etc." href="#dt-must">must not</a> be used;
|
|
their appearance is a <a title="fatal error" href="#dt-error">fatal error</a>.
|
|
A value that results in a syntactically invalid URI or IRI
|
|
<a title="Must, May, etc." href="#dt-must">should</a>
|
|
be reported as a <a title="fatal error" href="#dt-error">fatal error</a>, but
|
|
some implementations may find it impractical to distinguish this
|
|
case from a <a title="resource error" href="#dt-resource-error">resource error</a>.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>A URI ending in <code>#</code> is considered by <a href="#RFC2396">[IETF RFC 2396]</a>
|
|
to have an empty fragment identifier. Such a URI would result in a
|
|
<a title="fatal error" href="#dt-error">fatal error</a> as described above.</p></div><div class="note"><p class="prefix"><b>Note:</b></p><p>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 <code>parse="xml"</code> inclusions,
|
|
sub-resources are identified by a separate <code>xpointer</code>
|
|
attribute, which is applied after the casting takes place. While
|
|
this does not prevent subresources of XML documents to be
|
|
identified by URI (See <a href="http://www.w3.org/TR/webarch/#identification">Architecture
|
|
of the World Wide Web [Identification]</a>), it does preclude
|
|
the use of these identifiers directly within XInclude.</p></div></dd><dt class="label">parse</dt><dd><p>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 <a title="Must, May, etc." href="#dt-must">must</a>
|
|
be parsed as XML and the infosets merged. A value of "text" indicates
|
|
that the resource <a title="Must, May, etc." href="#dt-must">must</a> 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 <a title="fatal error" href="#dt-error">fatal error</a>.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>For interoperability between validating and non-validating
|
|
systems, whitespace should not appear in the parse attribute.</p></div></dd><dt class="label">xpointer</dt><dd><p>When <code>parse="xml"</code>, the XPointer (see <a href="#XPCore">[XPointer Framework]</a>)
|
|
contained in the <code>xpointer</code> attribute is evaluated to identify
|
|
a portion of the resource to include. This attribute is optional; when
|
|
omitted, the entire resource is included. The <code>xpointer</code>
|
|
attribute <a title="Must, May, etc." href="#dt-must">must not</a> be present when
|
|
<code>parse="text"</code>. If the <code>xpointer</code> attribute is absent,
|
|
the <code>href</code> attribute <a title="Must, May, etc." href="#dt-must">must</a> be
|
|
present.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>Since the <code>xpointer</code> attribute is not a URI reference,
|
|
<span>and %-escaping is not done in XPointers, '%' is
|
|
an ordinary character in the value of the xpointer
|
|
attribute</span>.</p></div></dd><dt class="label">encoding</dt><dd><p>When <code>parse="text"</code>, it is sometimes impossible to
|
|
correctly detect the encoding of the text resource. The
|
|
<code>encoding</code> attribute specifies how the resource is to
|
|
be translated. The value of this attribute <span><a title="Must, May, etc." href="#dt-must">should</a> be a valid encoding name</span>.
|
|
The <code>encoding</code> attribute has no effect when
|
|
<code>parse="xml"</code>.</p></dd><dt class="label">accept</dt><dd><p>The value of the <code>accept</code> attribute may be used by
|
|
the XInclude processor to aid in content negotiation. When the
|
|
XInclude processor fetches a resource via HTTP, it
|
|
<a title="Must, May, etc." href="#dt-must">should</a> place the
|
|
value of the <code>accept</code> attribute, if one exists, in
|
|
the HTTP request as an <code>Accept</code> header as
|
|
described in section 14.1 of <a href="#RFC2616">[IETF RFC 2616]</a>. Values containing
|
|
characters outside the range #x20 through #x7E <a title="Must, May, etc." href="#dt-must">must</a>
|
|
be flagged as <a title="fatal error" href="#dt-error">fatal errors</a>.</p></dd><dt class="label">accept-language</dt><dd><p>The value of the <code>accept-language</code> attribute may be used by
|
|
the XInclude processor to aid in content negotiation. When the
|
|
XInclude processor fetches a resource via HTTP, it
|
|
<a title="Must, May, etc." href="#dt-must">should</a> place the
|
|
value of the <code>accept-language</code> attribute, if one exists, in
|
|
the HTTP request as an <code>Accept-Language</code> header as
|
|
described in section 14.4 of <a href="#RFC2616">[IETF RFC 2616]</a>. Values containing
|
|
characters outside the range #x20 through #x7E are disallowed
|
|
in HTTP headers, and <a title="Must, May, etc." href="#dt-must">must</a>
|
|
be flagged as <a title="fatal error" href="#dt-error">fatal errors</a>.</p></dd></dl><p>Attributes other than those listed above <a title="Must, May, etc." href="#dt-must">may</a>
|
|
be placed on the <code>xi:include</code> element. Unprefixed
|
|
attribute names are reserved for future versions of this specification,
|
|
and <a title="Must, May, etc." href="#dt-must">must</a> be ignored by XInclude 1.0
|
|
processors.</p><p>The <em>children</em> property of the
|
|
<code>xi:include</code> element <a title="Must, May, etc." href="#dt-must">may</a>
|
|
include a single <code>xi:fallback</code> element; the appearance of
|
|
more than one <code>xi:fallback</code> element, an
|
|
<code>xi:include</code> element, or any other element from the
|
|
XInclude namespace is a <a title="fatal error" href="#dt-error">fatal error</a>.
|
|
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 <em>children</em>
|
|
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.</p><p>The following (non-normative) DTD fragment illustrates a sample
|
|
declaration for the <code>xi:include</code> element:</p><div class="exampleInner"><pre><!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
|
|
></pre></div></div><div class="div2">
|
|
<h3><a name="fallback_element" id="fallback_element"></a>3.2 xi:fallback Element</h3><p>The <code>xi:fallback</code> element appears as a child
|
|
of an <code>xi:include</code> element. It provides a mechanism
|
|
for recovering from missing resources. When a
|
|
<a title="resource error" href="#dt-resource-error">resource error</a> is
|
|
encountered, the <code>xi:include</code> element is replaced
|
|
with the contents of the <code>xi:fallback</code> element.
|
|
If the <code>xi:fallback</code> element is empty, the
|
|
<code>xi:include</code> element is removed from the result.
|
|
If the <code>xi:fallback</code> element is missing, a
|
|
<a title="resource error" href="#dt-resource-error">resource error</a> results
|
|
in a <a title="fatal error" href="#dt-error">fatal error</a>.</p><p>The <code>xi:fallback</code> element can appear only as a
|
|
child of an <code>xi:include</code> element. It is a
|
|
<a title="fatal error" href="#dt-error">fatal error</a> for an <code>xi:fallback</code>
|
|
element to appear in a document anywhere other than as the direct child
|
|
of the <code>xi:include</code> (before inclusion processing on
|
|
the contents of the element.) It is a <a title="fatal error" href="#dt-error">fatal error</a>
|
|
for the <code>xi:fallback</code> element to contain any elements from the
|
|
XInclude namespace other than <code>xi:include</code>.</p><p>Attributes <a title="Must, May, etc." href="#dt-must">may</a>
|
|
be placed on the <code>xi:fallback</code> element. Unprefixed
|
|
attribute names are reserved for future versions of this specification,
|
|
and <a title="Must, May, etc." href="#dt-must">must</a> be ignored by XInclude 1.0
|
|
processors.</p><p>The content of <code>xi:fallback</code> elements are ignored unless a
|
|
<a title="resource error" href="#dt-resource-error">resource error</a> occurs while processing the
|
|
surrounding <code>xi:include</code> element. In particular, apparent
|
|
<a title="fatal error" href="#dt-error">fatal errors</a> caused by the presence, absence, or
|
|
content of elements and attributes inside the <code>xi:fallback</code> element
|
|
<a title="Must, May, etc." href="#dt-must">must not</a> be reported in <code>xi:fallback</code>
|
|
elements that are ignored.</p><p>The following (non-normative) DTD fragment illustrates a sample
|
|
declaration for the <code>xi:fallback</code> element:</p><div class="exampleInner"><pre><!ELEMENT xi:fallback ANY>
|
|
<!ATTLIST xi:fallback
|
|
xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude"
|
|
></pre></div></div></div><div class="div1">
|
|
<h2><a name="processing" id="processing"></a>4 Processing Model</h2><p>Inclusion as defined in this document is a specific type of
|
|
<a href="#XMLIS">[XML Information Set]</a> transformation.</p><p>
|
|
[<a name="dt-source-infoset" id="dt-source-infoset" title="source infoset">Definition</a>: The
|
|
input for the inclusion transformation consists of a <b>source
|
|
infoset</b>.]
|
|
[<a name="dt-result-infoset" id="dt-result-infoset" title="result infoset">Definition</a>: The output, called the <b>result
|
|
infoset</b>, is a new infoset which merges the source infoset
|
|
with the infosets of resources identified by URI references or IRI references
|
|
appearing in <code>xi:include</code> elements.] Thus a
|
|
mechanism to resolve URIs or IRIs and return the identified resources as
|
|
infosets is assumed. Well-formed XML entities that do not have
|
|
defined infosets (e.g. an external entity with multiple
|
|
top-level elements) are outside the scope of this specification,
|
|
either for use as a <a title="source infoset" href="#dt-source-infoset">source
|
|
infoset</a> or the <a title="result infoset" href="#dt-result-infoset">result
|
|
infoset</a>.</p><p>
|
|
<code>xi:include</code> elements in the source infoset serve
|
|
as inclusion transformation instructions.
|
|
[<a name="dt-top-level-included-items" id="dt-top-level-included-items" title="top-level included items">Definition</a>: The
|
|
information items located by the <code>xi:include</code> element
|
|
are called the <b>top-level included items</b>
|
|
].
|
|
[<a name="dt-included-items" id="dt-included-items" title="included items">Definition</a>: The
|
|
<a title="top-level included items" href="#dt-top-level-included-items">top-level included items</a>
|
|
together with their attributes, namespaces, and descendants,
|
|
are called the <b>included items</b>
|
|
]. The
|
|
<a title="result infoset" href="#dt-result-infoset">result infoset</a> is
|
|
essentially a copy of the <a title="source infoset" href="#dt-source-infoset">source
|
|
infoset</a>, with each <code>xi:include</code> element
|
|
and its descendants replaced by its corresponding
|
|
<a title="included items" href="#dt-included-items">included items</a>.</p><div class="div2">
|
|
<h3><a name="include-location" id="include-location"></a>4.1 The Include Location</h3><p>The value of the <code>href</code> attribute, after escaping
|
|
according to <a href="#IRIs"><b>4.1.1 Escaping of href attribute values</b></a>, is interpreted as either a
|
|
URI reference or an <a title="IRI reference" href="#dt-IRI">IRI reference</a>.
|
|
The base URI for relative URIs or IRIs is the base URI of the <code>xi:include</code>
|
|
element as specified in <a href="#XMLBase">[XML Base]</a>.
|
|
[<a name="dt-include-location" id="dt-include-location" title="include location">Definition</a>: The
|
|
URI or IRI resulting from resolution of the normalized value of the
|
|
<code>href</code> attribute (or the empty string if no attribute appears)
|
|
to absolute URI or IRI form is called the <b>include location</b>.]
|
|
</p><p>The absence of a value for the <code>href</code> attribute, either
|
|
by the appearance of <code>href=""</code> or by the absence of the
|
|
<code>href</code> attribute, represents a case which may be incompatible
|
|
with certain implementation strategies. For instance, an XInclude
|
|
processor might not have a textual representation of the
|
|
<a title="source infoset" href="#dt-source-infoset">source infoset</a> to include
|
|
as <code>parse="text"</code>, or it may be unable to access another
|
|
part of the document using <code>parse="xml"</code> and an xpointer
|
|
because of streamability concerns. An implementation
|
|
<a title="Must, May, etc." href="#dt-must">may</a> choose to treat any or all
|
|
absences of a value for the <code>href</code> attribute as
|
|
<a title="resource error" href="#dt-resource-error">resource errors</a>.
|
|
Implementations <a title="Must, May, etc." href="#dt-must">should</a> document
|
|
the conditions under which such <a title="resource error" href="#dt-resource-error">resource
|
|
errors</a> occur.</p><div class="div3">
|
|
<h4><a name="IRIs" id="IRIs"></a>4.1.1 Escaping of <code>href</code> attribute values</h4><p>The value of this attribute is an XML resource identifer as
|
|
defined in <a href="#XML11">[XML 1.1]</a> section 4.2.2 "External Entities", which
|
|
is interpreted as [<a name="dt-IRI" id="dt-IRI" title="IRI reference">Definition</a>: an IRI Reference as defined in RFC 3987 <a href="#RFC3987">[IETF RFC 3987]</a>],
|
|
after the escaping procedure described in <a href="#XML11">[XML 1.1]</a> section
|
|
4.2.2 is applied. If necessary for the implementation, the value may be
|
|
further converted to a URI reference as described in <a href="#XML11">[XML 1.1]</a>.</p></div><div class="div3">
|
|
<h4><a name="content-negotiation" id="content-negotiation"></a>4.1.2 Using XInclude with Content Negotiation</h4><p>The use of a mechanism like HTTP <a href="#RFC2616">[IETF RFC 2616]</a> content
|
|
negotiation introduces an additional level of potential complexity
|
|
into the use of XInclude. Developers who use XInclude in situations
|
|
where content negotiation is likely or possible should be aware of
|
|
the possibility that they will be including content that may differ
|
|
structurally from the content they expected, even if that content
|
|
is XML. For example, a single URI or IRI may variously return a raw XML
|
|
representation of the resource, an XSL-FO <a href="#XSL-FO">[XSL-FO]</a>
|
|
representation, or an XHTML <a href="#XHTML">[XHTML]</a> representation,
|
|
as well as versions in different character encodings or languages.</p><p>Authors whose XInclude processing depends on the receipt of
|
|
a particular vocabulary of XML should use the <code>accept</code>
|
|
and <code>accept-language</code> attributes
|
|
to increase the probability that the resource is provided in the
|
|
expected format.</p></div></div><div class="div2">
|
|
<h3><a name="xml-included-items" id="xml-included-items"></a>4.2 Included Items when <code>parse="xml"</code>
|
|
</h3><p>When <code>parse="xml"</code>, the
|
|
<a title="include location" href="#dt-include-location">include location</a> 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).</p><div class="note"><p class="prefix"><b>Note:</b></p><p>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.</p></div><div class="note"><p class="prefix"><b>Note:</b></p><p>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.</p></div><p>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 <a title="resource error" href="#dt-resource-error">resource error</a>.
|
|
Resources that contain non-well-formed XML result in a
|
|
<a title="fatal error" href="#dt-error">fatal error</a>.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>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.</p></div><p>
|
|
[<a name="dt-acquired-infoset" id="dt-acquired-infoset" title="acquired infoset">Definition</a>:
|
|
<code>xi:include</code> elements in this infoset are recursively
|
|
processed to create the <b>acquired infoset</b>.
|
|
For an intra-document reference (via <code>xpointer</code> attribute)
|
|
the <a title="source infoset" href="#dt-source-infoset">source infoset</a> is
|
|
used as the acquired infoset.]
|
|
</p><p>
|
|
[<a name="dt-inclusion-target" id="dt-inclusion-target" title="inclusion target">Definition</a>: The portion
|
|
of the <a title="acquired infoset" href="#dt-acquired-infoset">acquired infoset</a> to be
|
|
included is called the <b>inclusion target</b>.] The
|
|
<em>document information item</em> of the
|
|
<a title="acquired infoset" href="#dt-acquired-infoset">acquired infoset</a> serves
|
|
as the <a title="inclusion target" href="#dt-inclusion-target">inclusion target</a>
|
|
unless the <code>xpointer</code> attribute is present and identifies a
|
|
subresource. XPointers of the forms described in <a href="#XPCore">[XPointer Framework]</a>
|
|
and <a href="#XPElement">[XPointer element() scheme]</a> <a title="Must, May, etc." href="#dt-must">must</a>
|
|
be supported. XInclude processors optionally support other forms of
|
|
XPointer such as that described in <a href="#XPointer">[XPointer xpointer() Scheme]</a>. An error
|
|
in the XPointer is a <a title="resource error" href="#dt-resource-error">resource
|
|
error</a>.</p><p>The <a href="#XPointer">[XPointer xpointer() Scheme]</a> is not specified in terms of the
|
|
<a href="#XMLIS">[XML Information Set]</a>, but instead is based on the
|
|
<a href="#XPath">[XPath 1.0]</a> 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 <a title="fatal error" href="#dt-error">fatal error</a> to attempt
|
|
to resolve an xpointer() scheme on a document that contains
|
|
<em>unexpanded entity reference information
|
|
items</em>.</p><p>The set of <a title="top-level included items" href="#dt-top-level-included-items">top-level
|
|
included items</a> is derived from the
|
|
<a title="acquired infoset" href="#dt-acquired-infoset">acquired infoset</a> as
|
|
follows.</p><div class="div3">
|
|
<h4><a name="docii" id="docii"></a>4.2.1 Document Information Items</h4><p>The <a title="inclusion target" href="#dt-inclusion-target">inclusion target</a>
|
|
might be a <em>document information item</em>
|
|
(for instance, no specified <code>xpointer</code> attribute, or an
|
|
XPointer specifically locating the document root.) In this case,
|
|
the set of <a title="top-level included items" href="#dt-top-level-included-items">top-level
|
|
included items</a> is the <em>children</em>
|
|
of the <a title="acquired infoset" href="#dt-acquired-infoset">acquired infoset's</a>
|
|
document information item, except for the
|
|
<em>document type declaration information item</em>
|
|
child, if one exists.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>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.</p></div></div><div class="div3">
|
|
<h4><a name="multiple-nodes" id="multiple-nodes"></a>4.2.2 Multiple Nodes</h4><p>The <a title="inclusion target" href="#dt-inclusion-target">inclusion target</a>
|
|
might consist of more than a single node. In this case the set of
|
|
<a title="top-level included items" href="#dt-top-level-included-items">top-level included
|
|
items</a> is the set of information items from the
|
|
<a title="acquired infoset" href="#dt-acquired-infoset">acquired infoset</a>
|
|
corresponding to the nodes referred to by the XPointer, in the order
|
|
in which they appear in the acquired infoset.</p></div><div class="div3">
|
|
<h4><a name="ranges" id="ranges"></a>4.2.3 Range Locations</h4><p>The <a title="inclusion target" href="#dt-inclusion-target">inclusion target</a> might
|
|
be a location set that represents a range or a set of ranges.</p><p>Each range corresponds to a set of information items in the
|
|
<a title="acquired infoset" href="#dt-acquired-infoset">acquired infoset</a>.
|
|
[<a name="dt-selected" id="dt-selected" title="selected">Definition</a>: An information item is
|
|
said to be <b>selected</b> by a range if it occurs after
|
|
(in document order) the starting point of the range and before
|
|
the ending point of the range.]
|
|
[<a name="dt-partially-selected" id="dt-partially-selected" title="partially selected">Definition</a>: An
|
|
information item is said to be <b>partially selected</b> 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
|
|
<a title="partially selected" href="#dt-partially-selected">partially selected</a>.</p><p>The set of <a title="top-level included items" href="#dt-top-level-included-items">top-level
|
|
included items</a> is the union, in document order with
|
|
duplicates removed, of the information items either
|
|
<a title="selected" href="#dt-selected">selected</a> or
|
|
<a title="partially selected" href="#dt-partially-selected">partially selected</a>
|
|
by the range. The <em>children</em>
|
|
property of <a title="selected" href="#dt-selected">selected</a>
|
|
information items is not modified. The
|
|
<em>children</em> property of
|
|
<a title="partially selected" href="#dt-partially-selected">partially selected</a>
|
|
information items is the set of information items that are in
|
|
turn either <a title="selected" href="#dt-selected">selected</a> or
|
|
<a title="partially selected" href="#dt-partially-selected">partially selected</a>,
|
|
and so on.</p></div><div class="div3">
|
|
<h4><a name="points" id="points"></a>4.2.4 Point Locations</h4><p>The <a title="inclusion target" href="#dt-inclusion-target">inclusion target</a>
|
|
might be a location set that represents a point. In this case the
|
|
set of <a title="included items" href="#dt-included-items">included items</a> is
|
|
empty.</p></div><div class="div3">
|
|
<h4><a name="elements" id="elements"></a>4.2.5 Element, Comment, and Processing Instruction Information Items</h4><p>The <a title="inclusion target" href="#dt-inclusion-target">inclusion target</a>
|
|
might be an element node, a comment node, or a processing instruction
|
|
node, respectively representing an <em>element
|
|
information item</em>, a <em>comment information
|
|
item</em>, or a <em>processing instruction information
|
|
item</em>. In this case the set of
|
|
<a title="top-level included items" href="#dt-top-level-included-items">top-level included items</a>
|
|
consists of the information item corresponding to the element, comment, or
|
|
processing instruction node in the <a title="acquired infoset" href="#dt-acquired-infoset">acquired
|
|
infoset</a>.</p></div><div class="div3">
|
|
<h4><a name="attributes" id="attributes"></a>4.2.6 Attribute and Namespace Declaration Information Items</h4><p>It is a <a title="fatal error" href="#dt-error">fatal error</a> for the
|
|
<a title="inclusion target" href="#dt-inclusion-target">inclusion target</a> to be an
|
|
attribute node or a namespace node.</p></div><div class="div3">
|
|
<h4><a name="loops" id="loops"></a>4.2.7 Inclusion Loops</h4><p>When recursively processing an <code>xi:include</code>
|
|
element, it is a <a title="fatal error" href="#dt-error">fatal error</a> to process
|
|
another <code>xi:include</code> element with an
|
|
<a title="include location" href="#dt-include-location">include location</a> and
|
|
<code>xpointer</code> attribute value that have already been processed in the
|
|
inclusion chain.</p><p>In other words, the following are all legal:</p><ul><li><p>An <code>xi:include</code> element
|
|
<a title="Must, May, etc." href="#dt-must">may</a> reference the document
|
|
containing the include element, when <code>parse="text"</code>.</p></li><li><p>An <code>xi:include</code> element
|
|
<a title="Must, May, etc." href="#dt-must">may</a> identify a different
|
|
part of the same local resource (same <code>href</code>,
|
|
different <code>xpointer</code>).</p></li><li><p>Two non-nested <code>xi:include</code> elements
|
|
<a title="Must, May, etc." href="#dt-must">may</a> identify a resource which
|
|
itself contains an <code>xi:include</code> element.</p></li></ul><p>The following are illegal:</p><ul><li><p>An <code>xi:include</code> element pointing to itself or any
|
|
ancestor thereof, when <code>parse="xml"</code>.</p></li><li><p>An <code>xi:include</code> element pointing to any include
|
|
element or ancestor thereof which has already been processed
|
|
at a higher level.</p></li></ul></div></div><div class="div2">
|
|
<h3><a name="text-included-items" id="text-included-items"></a>4.3 Included Items when <code>parse="text"</code>
|
|
</h3><p>When <code>parse="text"</code>, the <a title="include location" href="#dt-include-location">include
|
|
location</a> is dereferenced and the resource is fetched
|
|
and transformed to a set of character information items. This
|
|
feature facilitates the inclusion of working XML examples, as
|
|
well as other text-based formats.</p><p>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, or the resource is in an unsupported encoding) result in a
|
|
<a title="resource error" href="#dt-resource-error">resource error</a>.</p><p>The encoding of such a resource is determined by:</p><ul><li><p>external encoding information, if available, otherwise</p></li><li><p>if the media type of the resource indicates,
|
|
according to XML Media Types <a href="#RFC3023">[IETF RFC 3023]</a>, that the
|
|
resource is XML, for example <code>text/xml</code> or
|
|
<code>application/xml</code> or matches
|
|
<code>text/*+xml</code> or <code>application/*+xml</code>, then the
|
|
encoding is determined as specified in <a href="#XML">[XML 1.0]</a> or
|
|
<a href="#XML11">[XML 1.1]</a> section 4.3.3, as appropriate, otherwise</p></li><li><p>the value of the <code>encoding</code> attribute if one
|
|
exists, otherwise</p></li><li><p>UTF-8.</p></li></ul><p>Byte sequences outside the range allowed by the encoding are a
|
|
<a title="fatal error" href="#dt-error">fatal error</a>. Characters that are not
|
|
permitted in XML documents also are a
|
|
<a title="fatal error" href="#dt-error">fatal error</a>.</p><p>Each character obtained from the transformation of the resource is
|
|
represented in the <a title="top-level included items" href="#dt-top-level-included-items">top-level
|
|
included items</a> as a <em>character
|
|
information item</em> with the
|
|
<em>character code</em> set to the
|
|
character code in ISO 10646 encoding, and
|
|
the <em>element content whitespace</em> set
|
|
to false.</p><p>When the first character is U+FEFF and is interpreted as a
|
|
Byte-Order Mark, it should be discarded. It is interpreted as a BOM in UTF-8,
|
|
UTF-16, and UTF-32 encodings; it is not interpreted as a BOM in the UTF-16LE,
|
|
UTF-16BE, UTF-32LE, and UTF-32BE encodings.</p><p>The <a href="#CharMod">[Character Model]</a> discusses normalization of included text.</p></div><div class="div2">
|
|
<h3><a name="fallback" id="fallback"></a>4.4 Fallback Behavior</h3><p>XInclude processors <a title="Must, May, etc." href="#dt-must">must</a> perform
|
|
fallback behavior in the event of a
|
|
<a title="resource error" href="#dt-resource-error">resource error</a>, as follows:</p><p>If the <em>children</em> of the
|
|
<code>xi:include</code> element information item in the
|
|
<a title="source infoset" href="#dt-source-infoset">source infoset</a> contain
|
|
exactly one <code>xi:fallback</code> element, the
|
|
<a title="top-level included items" href="#dt-top-level-included-items">top-level included items</a>
|
|
consist of the information items corresponding to the result of performing
|
|
XInclude processing on the <em>children</em>
|
|
of the <code>xi:fallback</code> element. It is a
|
|
<a title="fatal error" href="#dt-error">fatal error</a> if there is zero or more than
|
|
one <code>xi:fallback</code> element.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>Fallback content is not dependent on the value of the
|
|
<code>parse</code> attribute. The <code>xi:fallback</code>
|
|
element can contain markup even when <code>parse="text"</code>.
|
|
Likewise, it can contain a simple string when <code>parse="xml"</code>.</p></div></div><div class="div2">
|
|
<h3><a name="creating-result" id="creating-result"></a>4.5 Creating the Result Infoset</h3><p>The result infoset is a copy of the source infoset,
|
|
with each <code>xi:include</code> element processed as follows:</p><p>The information item for the <code>xi:include</code> element is
|
|
found. [<a name="dt-include-parent" id="dt-include-parent" title="include parent">Definition</a>: The
|
|
<em>parent</em> property of this item
|
|
refers to an information item called the <b>include parent</b>.]
|
|
The <em>children</em> property of the
|
|
<a title="include parent" href="#dt-include-parent">include parent</a>
|
|
is modified by replacing the <code>xi:include</code> element
|
|
information item with the <a title="top-level included items" href="#dt-top-level-included-items">top-level
|
|
included items</a>. The <em>parent</em>
|
|
property of each included item is set to the
|
|
<a title="include parent" href="#dt-include-parent">include parent</a>.</p><p>It is a fatal error to attempt to replace an <code>xi:include</code>
|
|
element appearing as the document (top-level) element in the source
|
|
infoset with something other than a list of zero or more comments,
|
|
zero or more processing instructions, and one element.</p><p>Some processors may not be able to represent an element's
|
|
<em>in-scope namespaces</em> property if
|
|
it does not include bindings for all the prefixes bound in its
|
|
parent's <em>in-scope namespaces</em>.
|
|
Such processors <a title="Must, May, etc." href="#dt-must">may</a> therefore include
|
|
additional namespace bindings inherited from the
|
|
<a title="include parent" href="#dt-include-parent">include parent</a> in the
|
|
<em>in-scope namespaces</em> of
|
|
the <a title="included items" href="#dt-included-items">included items</a>.</p><p>The inclusion history of each <a title="top-level included items" href="#dt-top-level-included-items">top-level
|
|
included item</a> is recorded in the extension property
|
|
<em>include history</em>. The
|
|
<em>include history</em> property is
|
|
a list of <em>element information items</em>,
|
|
representing the <code>xi:include</code> elements for recursive levels
|
|
of inclusion. If an <em>include history</em>
|
|
property already appears on a <a title="top-level included items" href="#dt-top-level-included-items">top-level
|
|
included item</a>, the <code>xi:include</code> element information
|
|
item is prepended to the list. If no <em>include
|
|
history</em> property exists, then this property is added with the
|
|
single value of the <code>xi:include</code> element information item.</p><p>The <a title="included items" href="#dt-included-items">included items</a> will all
|
|
appear in the result infoset. This includes <em>unexpanded
|
|
entity reference information items</em> if they are present.</p><p>Intra-document references within <code>xi:include</code> elements
|
|
are resolved against the source infoset. The effect of this is that
|
|
the order in which <code>xi:include</code> elements are processed
|
|
does not affect the result.</p><p>In the following example, the second include always points to
|
|
the first <code>xi:include</code> element and not to itself,
|
|
regardless of the order in which the includes are processed. Thus
|
|
the result of this inclusion is two copies of <code>something.xml</code>,
|
|
and does not produce an inclusion loop error.</p><div class="exampleInner"><pre><x xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<xi:include href="something.xml"/>
|
|
<xi:include xpointer="xmlns(xi=http://www.w3.org/2001/XInclude)xpointer(x/xi:include[1])"
|
|
parse="xml"/>
|
|
</x></pre></div><p>An XInclude processor <a title="Must, May, etc." href="#dt-must">may</a>, at
|
|
user option, suppress <code>xml:base</code> and/or <code>xml:lang</code> fixup.</p><div class="div3">
|
|
<h4><a name="unparsed-entities" id="unparsed-entities"></a>4.5.1 Unparsed Entities</h4><p>Any <em>unparsed entity information
|
|
item</em> appearing in the <em>references</em>
|
|
property of an attribute on the <a title="included items" href="#dt-included-items">included
|
|
items</a> or any descendant thereof is added to the
|
|
<em>unparsed entities</em>
|
|
property of the <a title="result infoset" href="#dt-result-infoset">result infoset</a>'s
|
|
<em>document information item</em>, if
|
|
it is not a duplicate of an existing member. Duplicates do not appear
|
|
in the result infoset.</p><p>Unparsed entity items with the same
|
|
<em>name</em>,
|
|
<em>system identifier</em>,
|
|
<em>public identifier</em>,
|
|
<em>declaration base URI</em>,
|
|
<em>notation name</em>, and
|
|
<em>notation</em> are
|
|
considered to be duplicate. An application
|
|
<a title="Must, May, etc." href="#dt-must">may</a> also be able to detect that
|
|
unparsed entities are duplicate through other means. For instance,
|
|
the URI resulting from combining the system identifier
|
|
and the declaration base URI is the same.</p><p>It is a <a title="fatal error" href="#dt-error">fatal error</a> to
|
|
include unparsed entity items with the same name, but which are not
|
|
determined to be duplicates.</p></div><div class="div3">
|
|
<h4><a name="notations" id="notations"></a>4.5.2 Notations</h4><p>Any <em>notation information item</em>
|
|
appearing in the <em>references</em>
|
|
property of an attribute in the <a title="included items" href="#dt-included-items">included
|
|
items</a> or any descendant thereof is added to the
|
|
<em>notations</em> property of the
|
|
<a title="result infoset" href="#dt-result-infoset">result infoset</a>'s
|
|
<em>document information item</em>, if
|
|
it is not a duplicate of an existing member. Likewise,
|
|
any notation referenced by an unparsed entity added as described
|
|
in <a href="#unparsed-entities"><b>4.5.1 Unparsed Entities</b></a>, is added unless it is
|
|
a duplicate. Duplicates do not appear in the result infoset.</p><p>Notation items with the same
|
|
<em>name</em>,
|
|
<em>system identifier</em>,
|
|
<em>public identifier</em>, and
|
|
<em>declaration base URI</em> are
|
|
considered to be duplicate. An application <a title="Must, May, etc." href="#dt-must">may</a>
|
|
also be able to detect that notations are duplicate through other means. For
|
|
instance, the URI resulting from combining the system identifier
|
|
and the declaration base URI is the same.</p><p>It is a <a title="fatal error" href="#dt-error">fatal error</a> to
|
|
include notation items with the same name, but which are not
|
|
determined to be duplicates.</p></div><div class="div3">
|
|
<h4><a name="references-property" id="references-property"></a>4.5.3
|
|
<em>references</em> Property Fixup</h4><p>During inclusion, an <em>attribute information
|
|
item</em> whose <em>attribute type</em>
|
|
property is IDREF or IDREFS has a <em>references</em>
|
|
property with zero or more element values from the source or included
|
|
infosets. These values <a title="Must, May, etc." href="#dt-must">must</a> be
|
|
adjusted to correspond to element values that occur in the result
|
|
infoset. During this process, XInclude also corrects inconsistencies
|
|
between the <em>references</em>
|
|
property and the <em>attribute type</em>
|
|
property, which might arise in the following circumstances:</p><ul><li><p>A document fragment contains an IDREF pointing to an element
|
|
in the included document but outside the part being included.
|
|
In this case there is no element in the result infoset that
|
|
corresponds to the element value in the original
|
|
<em>references</em> property.</p></li><li><p>A document or document fragment is not self-contained.
|
|
That is, it contains IDREFs which do not refer to an element within
|
|
that document or document fragment, with the intention that these
|
|
references will be realized after inclusion. In this case,
|
|
the value of the <em>references</em>
|
|
property is unknown or has no value.</p></li><li><p>The result infoset has ID clashes - that is, more than one
|
|
attribute with <em>attribute type</em>
|
|
ID with the same <em>normalized value</em>.
|
|
In this case, attributes with <em>attribute
|
|
type</em> IDREF or IDREFS with the same <em>
|
|
normalized value</em> might have different values for their
|
|
<em>references</em> properties.</p></li></ul><p>In resolving these inconsistencies, XInclude takes the
|
|
<em>attribute type</em> property as
|
|
definitive. In the result infoset, the value of the
|
|
<em>references</em> property of an
|
|
<em>attribute information item</em>
|
|
whose <em>attribute type</em> property
|
|
is IDREF or IDREFS is adjusted as follows:</p><p>For each token in the <em>normalized
|
|
value</em> property, the <em>references</em>
|
|
property contains an <em>element information
|
|
item</em> with the same properties as the
|
|
<em>element information item</em> in the result
|
|
infoset with an attribute with <em>attribute
|
|
type</em> ID and <em>normalized
|
|
value</em> equal to the token. The order of the elements in
|
|
the <em>references</em> property is
|
|
the same as the order of the tokens appearing in the
|
|
<em>normalize value</em>. If for any of the
|
|
token values, no element or more than one element is found, the
|
|
<em>references</em> property has no value.</p></div><div class="div3">
|
|
<h4><a name="namespaces" id="namespaces"></a>4.5.4 Namespace Fixup</h4><p>The <em>in-scope namespaces</em>
|
|
property ensures that namespace scope is preserved through inclusion.
|
|
However, after inclusion, the <em>namespace
|
|
attributes</em> property might not provide the full list of
|
|
namespace declarations necessary to interpret qualified names in
|
|
attribute or element content in the result. It is therefore not
|
|
recommended that XInclude processors expose
|
|
<em>namespace attributes</em> in the
|
|
result. If this is unavoidable, the implementation
|
|
<a title="Must, May, etc." href="#dt-must">may</a> add
|
|
<em>attribute information items</em> to the
|
|
<em>namespace attributes</em> property
|
|
in order to approximate the information conveyed by
|
|
<em>in-scope namespaces</em>.</p></div><div class="div3">
|
|
<h4><a name="base" id="base"></a>4.5.5 Base URI Fixup</h4><p>The base URI property of the acquired infoset is not changed as
|
|
a result of merging the infoset, and remains unchanged after merging.
|
|
Thus relative URI references in the included infoset resolve to the same
|
|
URI despite being included into a document with a potentially
|
|
different base URI in effect. <code>xml:base</code> attributes are added
|
|
to the result infoset to indicate this fact.</p><p>Each <em>element information item</em> in
|
|
the <a title="top-level included items" href="#dt-top-level-included-items">top-level included
|
|
items</a> which has a different <em>base
|
|
URI</em> than its <a title="include parent" href="#dt-include-parent">include parent</a>
|
|
has an <em>attribute information item</em> added to its
|
|
<em>attributes</em> property. This attribute has the following properties:</p><ol class="enumar"><li><p>A <em>namespace name</em> of
|
|
<code>http://www.w3.org/XML/1998/namespace</code>.</p></li><li><p>A <em>local name</em> of
|
|
<code>base</code>.</p></li><li><p>A <em>prefix</em> of
|
|
<code>xml</code>.</p></li><li><p>A <em>normalized value</em>
|
|
equal to either the <em>base
|
|
URI</em> of the element, or an equivalent URI reference
|
|
relative to the <em>base URI</em>
|
|
of the include parent. The circumstances in which a relative
|
|
URI is desirable, and how to compute such a relative URI,
|
|
are implementation-dependent.</p></li><li><p>A <em>specified</em> flag
|
|
indicating that this attribute was actually specified in the
|
|
start-tag of its element.</p></li><li><p>An <em>attribute type</em> of
|
|
<code>CDATA</code>.</p></li><li><p>A <em>references</em> property
|
|
with no value.</p></li><li><p>An <em>owner element</em> of the
|
|
information item of the element.</p></li></ol><p>If an <code>xml:base</code> attribute information item is already
|
|
present, it is replaced by the new attribute.</p></div><div class="div3">
|
|
<h4><a name="language" id="language"></a>4.5.6 Language Fixup</h4><p>While the <code>xml:lang</code> attribute is described as inherited
|
|
by XML, the XML Information Set makes no provision for preserving the
|
|
inheritance of this property through document composition such as XInclude
|
|
provides. This section introduces a <em>language</em>
|
|
property which records the scope of <code>xml:lang</code> information in
|
|
order to preserve it during inclusion.</p><p>An XInclude processor <a title="Must, May, etc." href="#dt-must">should</a> augment
|
|
the <a title="source infoset" href="#dt-source-infoset">source infoset</a> and the
|
|
<a title="acquired infoset" href="#dt-acquired-infoset">acquired infoset</a> by adding
|
|
the <em>language</em> property to each
|
|
<em>element information item</em>. The value of
|
|
this property is the <em>normalized value</em>
|
|
of the <code>xml:lang</code> attribute appearing on that element if one
|
|
exists, with <code>xml:lang=""</code> resulting in no value, otherwise it
|
|
is the value of the <em>language</em> property
|
|
of the element's parent element if one exists, otherwise the property
|
|
has no value.</p><p>Each <em>element information item</em> in the
|
|
<a title="top-level included items" href="#dt-top-level-included-items">top-level included items</a>
|
|
which has a different value of <em>language</em>
|
|
than its <a title="include parent" href="#dt-include-parent">include parent</a> (taking
|
|
case-insensitivity into account per <a href="#RFC3066">[IETF RFC 3066]</a>), or that has
|
|
a value if its <a title="include parent" href="#dt-include-parent">include parent</a> is
|
|
a <em>document information item</em>, has an
|
|
<em>attribute information item</em> added to its
|
|
<em>attributes</em> property. This attribute
|
|
has the following properties:</p><ol class="enumar"><li><p>A <em>namespace name</em> of
|
|
<code>http://www.w3.org/XML/1998/namespace</code>.</p></li><li><p>A <em>local name</em> of
|
|
<code>lang</code>.</p></li><li><p>A <em>prefix</em> of <code>xml</code>.</p></li><li><p>A <em>normalized value</em> equal to
|
|
the <em>language</em> property of the
|
|
element. If the <em>language</em> property
|
|
has no value, the normalized value is the empty string.</p></li><li><p>A <em>specified</em> flag indicating
|
|
that this attribute was actually specified in the start-tag of its
|
|
element.</p></li><li><p>An <em>attribute type</em> of
|
|
<code>CDATA</code>.</p></li><li><p>A <em>references</em> property with
|
|
no value.</p></li><li><p>An <em>owner element</em> of the
|
|
information item of the element.</p></li></ol><p>If an <code>xml:lang</code> attribute information item is already present,
|
|
it is replaced by the new attribute.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>The <code>xml:space</code> attribute is not treated specially by
|
|
XInclude.</p></div></div><div class="div3">
|
|
<h4><a name="properties" id="properties"></a>4.5.7 Properties Preserved by the Infoset</h4><p>As an infoset transformation, XInclude operates on the logical
|
|
structure of XML documents, not on their text serialization. All
|
|
properties of an information item described in <a href="#XMLIS">[XML Information Set]</a>
|
|
other than those specifically modified by this specification are
|
|
preserved during inclusion. The <em>include history</em>
|
|
and <em>language</em>
|
|
properties introduced in this specification is also preserved.
|
|
Extension properties such as
|
|
<a href="#XMLSchemas">[XML Schemas]</a> Post Schema Validation Infoset (PSVI)
|
|
properties are discarded by default. However, an XInclude
|
|
processor <a title="Must, May, etc." href="#dt-must">may</a>, at user option,
|
|
preserve these properties in the resulting infoset if they
|
|
are correct according to the specification describing the
|
|
semantics of the extension properties.</p><p>For instance, the PSVI <em>validity</em>
|
|
property describes the conditions of ancestors and descendants.
|
|
Modification of ancestors and descendants during the XInclude
|
|
process can render the value of this property inaccurate. By
|
|
default, XInclude strips this property, but by user option the
|
|
property could be recalculated to obtain a semantically accurate
|
|
value. Precisely how this is accomplished is outside the scope
|
|
of this specification.</p></div></div></div><div class="div1">
|
|
<h2><a name="conformance" id="conformance"></a>5 Conformance</h2><div class="div2">
|
|
<h3><a name="markup" id="markup"></a>5.1 Markup Conformance</h3><p>An <em>element information item</em> conforms
|
|
to this specification if it meets the structural requirements for
|
|
include elements defined in this specification. This specification
|
|
imposes no particular constraints on DTDs or XML schemas; conformance
|
|
applies only to elements and attributes.</p></div><div class="div2">
|
|
<h3><a name="application" id="application"></a>5.2 Application Conformance</h3><p>An application conforms to XInclude if it:</p><ul><li><p>supports <a href="#XML">[XML 1.0]</a> and <a href="#XMLNS">[Namespaces in XML]</a>
|
|
or <a href="#XML11">[XML 1.1]</a> and <a href="#XMLNS11">[Namespaces in XML 1.1]</a>,
|
|
the <a href="#XMLIS">[XML Information Set]</a>, <a href="#XMLBase">[XML Base]</a>, the
|
|
<a href="#XPCore">[XPointer Framework]</a>, and the <a href="#XPElement">[XPointer element() scheme]</a>;</p></li><li><p>stops processing when a <a title="fatal error" href="#dt-error">fatal
|
|
error</a> is encountered;</p></li><li><p>observes the mandatory conditions
|
|
(<a title="Must, May, etc." href="#dt-must">must</a>) set forth in this
|
|
specification, and for any optional conditions
|
|
(<a title="Must, May, etc." href="#dt-must">should</a> and
|
|
<a title="Must, May, etc." href="#dt-must">may</a>) it chooses to observe,
|
|
observes them in the way prescribed; and</p></li><li><p>performs markup conformance testing according to all the
|
|
conformance constraints appearing in this specification.</p></li></ul><p>Support for the <a href="#XPointer">[XPointer xpointer() Scheme]</a> is not mandatory for
|
|
full XInclude conformance. Authors are advised that use of
|
|
xpointer() and other XPointer schemes than element() might not be
|
|
supported by all conformant XInclude implementations.</p></div><div class="div2">
|
|
<h3><a name="infoset" id="infoset"></a>5.3 XML Information Set Conformance</h3><p>This specification conforms to the <a href="#XMLIS">[XML Information Set]</a>.
|
|
The following information items <a title="Must, May, etc." href="#dt-must">must</a>
|
|
be present in the input infosets to enable correct processing:</p><ul><li><p>
|
|
<em>Document information items</em> with
|
|
<em>children</em> and
|
|
<em>base URI</em> properties.</p></li><li><p>
|
|
<em>Element information items</em> with
|
|
<em>namespace name</em>,
|
|
<em>local name</em>,
|
|
<em>children</em>,
|
|
<em>attributes</em>,
|
|
<em>base URI</em> and
|
|
<em>parent</em> properties.</p></li><li><p>
|
|
<em>Attribute information items</em> with
|
|
<em>namespace name</em>,
|
|
<em>local name</em> and
|
|
<em>normalized value</em> properties.</p></li></ul><p>Additionally, XInclude processing might generate the following
|
|
kinds of information items in the result:</p><ul><li><p>
|
|
<em>Character information items</em> with
|
|
<em>character code</em>,
|
|
<em>element content whitespace</em> and
|
|
<em>parent</em> properties.</p></li></ul><p>XInclude extends the infoset with the property
|
|
<em>include history</em>, which
|
|
<a title="Must, May, etc." href="#dt-must">may</a> appear on the following
|
|
types of information items in the result:</p><ul><li><p>
|
|
<em>Element information items</em>.</p></li><li><p>
|
|
<em>Processing instruction information items</em>.</p></li><li><p>
|
|
<em>Comment information items</em>.</p></li><li><p>
|
|
<em>Character information items</em>.</p></li></ul><p>XInclude also extends the infoset with the property
|
|
<em>language</em>, which
|
|
<a title="Must, May, etc." href="#dt-must">may</a> appear on
|
|
<em>element information items</em>
|
|
in the result.</p></div></div></div><div class="back"><div class="div1">
|
|
<h2><a name="references" id="references"></a>A References</h2><dl><dt class="label"><a name="RFC2119" id="RFC2119"></a>IETF RFC 2119</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>RFC 2119: Key
|
|
words for use in RFCs to Indicate Requirement Levels</cite></a>.
|
|
Internet Engineering Task Force, 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)</dd><dt class="label"><a name="RFC3629"></a>IETF RFC 3629</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3629.txt"><cite>RFC 3629: UTF-8,
|
|
a transformation format of ISO 10646</cite></a>.
|
|
Internet Engineering Task Force, 2003. (See http://www.ietf.org/rfc/rfc3629.txt.)</dd><dt class="label"><a name="RFC2396" id="RFC2396"></a>IETF RFC 2396</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2396.txt"><cite>RFC 2396:
|
|
Uniform Resource Identifiers</cite></a>. Internet Engineering
|
|
Task Force, 1995. (See http://www.ietf.org/rfc/rfc2396.txt.)</dd><dt class="label"><a name="RFC2732" id="RFC2732"></a>IETF RFC 2732</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2732.txt"><cite>RFC 2732:
|
|
Format for Literal IPv6 Addresses in URL's</cite></a>.
|
|
Internet Engineering Task Force, 1999. (See http://www.ietf.org/rfc/rfc2732.txt.)</dd><dt class="label"><a name="RFC3023" id="RFC3023"></a>IETF RFC 3023</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3023.txt"><cite>RFC 3023:
|
|
XML Media Types</cite></a>.
|
|
Internet Engineering Task Force, 2001. (See http://www.ietf.org/rfc/rfc3023.txt.)</dd><dt class="label"><a name="RFC3987"></a>IETF RFC 3987</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3987.txt"><cite>RFC 3987:
|
|
Internationalized Resource Identifiers (IRIs)</cite></a>.
|
|
Internet Engineering Task Force, 2005. (See http://www.ietf.org/rfc/rfc3987.txt.)</dd><dt class="label"><a name="Unicode" id="Unicode"></a>Unicode</dt><dd>The Unicode Consortium.
|
|
<a href="http://www.unicode.org/unicode/standard/versions/"><cite>The
|
|
Unicode Standard, Version 4.0.</cite></a> Reading, Mass.: Addison-Wesley,
|
|
2003, as updated from time to time by the publication of new versions. (See
|
|
<a href="http://www.unicode.org/unicode/standard/versions/">
|
|
http://www.unicode.org/unicode/standard/versions/</a> for the latest version
|
|
and additional information on versions of the standard and of the Unicode
|
|
Character Database).</dd><dt class="label"><a name="XML" id="XML"></a>XML 1.0</dt><dd>
|
|
Tim Bray, Jean Paoli, C.M. Sperberg-McQueen, Eve Maler, François Yergeau, editors.
|
|
<a href="http://www.w3.org/TR/2004/REC-xml-20040204/"><cite>Extensible Markup
|
|
Language (XML) 1.0 (Third Edition)</cite></a>,
|
|
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml-20040204/.)</dd><dt class="label"><a name="XML11" id="XML11"></a>XML 1.1</dt><dd>
|
|
Tim Bray, Jean Paoli, C.M. Sperberg-McQueen, Eve Maler, François Yergeau,
|
|
John Cowan, editors.
|
|
<a href="http://www.w3.org/TR/2004/REC-xml11-20040204/"><cite>Extensible Markup
|
|
Language (XML) 1.1</cite></a>,
|
|
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml11-20040204/.)</dd><dt class="label"><a name="XMLBase" id="XMLBase"></a>XML Base</dt><dd>
|
|
Jonathan Marsh, editor.
|
|
<a href="http://www.w3.org/TR/2001/REC-xmlbase-20010627/"><cite>XML Base</cite></a>.
|
|
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xmlbase-20010627/.)</dd><dt class="label"><a name="XMLIS" id="XMLIS"></a>XML Information Set</dt><dd>
|
|
John Cowan and Richard Tobin, editors.
|
|
<a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204/"><cite>XML Information
|
|
Set (Second Edition)</cite></a>. World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.)</dd><dt class="label"><a name="XMLNS" id="XMLNS"></a>Namespaces in XML</dt><dd>
|
|
Tim Bray, Dave Hollander, and Andrew Layman, editors.
|
|
<a href="http://www.w3.org/TR/1999/REC-xml-names-19990114/"><cite>Namespaces in XML</cite></a>.
|
|
World Wide Web Consortium, 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114/.)</dd><dt class="label"><a name="XMLNS11" id="XMLNS11"></a>Namespaces in XML 1.1</dt><dd>Tim Bray, Dave Hollander, Andrew Layman, Richard Tobin, editors.
|
|
<a href="http://www.w3.org/TR/2004/REC-xml-names11-20040204/"><cite>Namespaces in XML 1.1</cite></a>.
|
|
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml-names11-20040204/.)</dd><dt class="label"><a name="XPCore" id="XPCore"></a>XPointer Framework</dt><dd>
|
|
Paul Grosso, Eve Maler, Jonathan Marsh, Norman Walsh, editors.
|
|
<a href="http://www.w3.org/TR/2003/REC-xptr-framework-20030325/"><cite>XPointer Framework</cite></a>.
|
|
World Wide Web Consortium, 2003. (See http://www.w3.org/TR/2003/REC-xptr-framework-20030325/.)</dd><dt class="label"><a name="XPElement" id="XPElement"></a>XPointer element() scheme</dt><dd>
|
|
Paul Grosso, Eve Maler, Jonathan Marsh, Norman Walsh, editors.
|
|
<a href="http://www.w3.org/TR/2003/REC-xptr-element-20030325/"><cite>XPointer element()
|
|
Scheme</cite></a>.
|
|
World Wide Web Consortium, 2003. (See http://www.w3.org/TR/2003/REC-xptr-element-20030325/.)</dd></dl></div><div class="div1">
|
|
<h2><a name="nn-refs" id="nn-refs"></a>B References (Non-Normative)</h2><dl><dt class="label"><a name="RFC2616" id="RFC2616"></a>IETF RFC 2616</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2616.txt"><cite>RFC 2616:
|
|
Hypertext Transfer Protocol -- HTTP/1.1</cite></a>.
|
|
Internet Engineering Task Force, 1999. (See http://www.ietf.org/rfc/rfc2616.txt.)</dd><dt class="label"><a name="RFC3066" id="RFC3066"></a>IETF RFC 3066</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3066.txt"><cite>RFC 3066:
|
|
Tags for the Identification of Languages</cite></a>.
|
|
Internet Engineering Task Force, 2001. (See http://www.ietf.org/rfc/rfc3066.txt.)</dd><dt class="label"><a name="XInclude-note" id="XInclude-note"></a>XML Inclusion Proposal</dt><dd>
|
|
Jonathan Marsh, David Orchard, editors.
|
|
<a href="http://www.w3.org/TR/1999/NOTE-xinclude-19991123"><cite>XML
|
|
Inclusion Proposal (XInclude).</cite></a>
|
|
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/1999/NOTE-xinclude-19991123.)</dd><dt class="label"><a name="XLink" id="XLink"></a>XML Linking Language</dt><dd>
|
|
Steve DeRose, Eve Maler, David Orchard, and Ben Trafford, editors.
|
|
<a href="http://www.w3.org/TR/2001/REC-xlink-20010627/"><cite>XML Linking Language (XLink).</cite></a>
|
|
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xlink-20010627/.)</dd><dt class="label"><a name="XPointer" id="XPointer"></a>XPointer xpointer() Scheme</dt><dd>
|
|
Steve DeRose, Ron Daniel, Eve Maler, editors.
|
|
<a href="http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219/"><cite>XPointer
|
|
xpointer() Scheme</cite></a>.
|
|
World Wide Web Consortium, 2002. (See http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219/.)</dd><dt class="label"><a name="XPath" id="XPath"></a>XPath 1.0</dt><dd>
|
|
James Clark, Steve DeRose, editors.
|
|
<a href="http://www.w3.org/TR/1999/REC-xpath-19991116"><cite>XML Path Language (XPath)
|
|
Version 1.0.</cite></a>
|
|
World Wide Web Consortium, 1999. (See http://www.w3.org/TR/1999/REC-xpath-19991116.)</dd><dt class="label"><a name="CharMod" id="CharMod"></a>Character Model</dt><dd>
|
|
Martin J. Dürst, François Yergeau, Misha Wolf, Asmus Freytag, Tex Texin.
|
|
<a href="http://www.w3.org/TR/charmod-norm/"><cite>Character Model for the
|
|
World Wide Web 1.0: Normalization</cite></a>.
|
|
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/charmod-norm/.)</dd><dt class="label"><a name="XMLSchemas" id="XMLSchemas"></a>XML Schemas</dt><dd>
|
|
Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, editors.
|
|
<a href="http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/"><cite>XML Schema Part 1:
|
|
Structures.</cite></a>
|
|
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)</dd><dt class="label"><a name="XSL-FO" id="XSL-FO"></a>XSL-FO</dt><dd>
|
|
Sharon Adler <em>et al</em>.
|
|
<a href="http://www.w3.org/TR/2001/REC-xsl-20011015/"><cite>Extensible Stylesheet
|
|
Language (XSL)</cite></a>.
|
|
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xsl-20011015/.)</dd><dt class="label"><a name="XHTML" id="XHTML"></a>XHTML</dt><dd>
|
|
Steven Pemberton <em>et al</em>.
|
|
<a href="http://www.w3.org/TR/2002/REC-xhtml1-20020801/"><cite>XHTML 1.0 The Extensible
|
|
HyperText Markup Language (Second Edition)</cite></a>.
|
|
World Wide Web Consortium, 2002. (See http://www.w3.org/TR/2002/REC-xhtml1-20020801/.)</dd></dl></div><div class="div1">
|
|
<h2><a name="examples" id="examples"></a>C Examples (Non-Normative)</h2><div class="div2">
|
|
<h3><a name="basic-example" id="basic-example"></a>C.1 Basic Inclusion Example</h3><p>The following XML document contains an <code>xi:include</code> element
|
|
which points to an external document. Assume the base URI of this document is
|
|
<code>http://www.example.org/document.xml</code>.</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<p>120 Mz is adequate for an average home user.</p>
|
|
<xi:include href="disclaimer.xml"/>
|
|
</document></pre></div><p>disclaimer.xml contains:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<disclaimer>
|
|
<p>The opinions represented herein represent those of the individual
|
|
and should not be interpreted as official policy endorsed by this
|
|
organization.</p>
|
|
</disclaimer></pre></div><p>The infoset resulting from resolving inclusions on this document
|
|
is the same (except for the <em>include history</em>
|
|
and <em>language</em> properties)
|
|
as that of the following document:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<p>120 Mz is adequate for an average home user.</p>
|
|
<disclaimer xml:base="http://www.example.org/disclaimer.xml">
|
|
<p>The opinions represented herein represent those of the individual
|
|
and should not be interpreted as official policy endorsed by this
|
|
organization.</p>
|
|
</disclaimer>
|
|
</document></pre></div></div><div class="div2">
|
|
<h3><a name="text-example" id="text-example"></a>C.2 Textual Inclusion Example</h3><p>The following XML document includes a "working example" into
|
|
a document.</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<p>This document has been accessed
|
|
<xi:include href="count.txt" parse="text"/> times.</p>
|
|
</document></pre></div><p>where count.txt contains:</p><div class="exampleInner"><pre>324387</pre></div><p>The infoset resulting from resolving inclusions on this document
|
|
is the same (except for the <em>include history</em>
|
|
and <em>language</em> properties)
|
|
as that of the following document:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<p>This document has been accessed
|
|
324387 times.</p>
|
|
</document></pre></div></div><div class="div2">
|
|
<h3><a name="xml-as-text-example" id="xml-as-text-example"></a>C.3 Textual Inclusion of XML Example</h3><p>The following XML document includes a "working example" into
|
|
a document.</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<p>The following is the source of the "data.xml" resource:</p>
|
|
<example><xi:include href="data.xml" parse="text"/></example>
|
|
</document></pre></div><p>data.xml contains:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<data>
|
|
<item><![CDATA[Brooks & Shields]]></item>
|
|
</data></pre></div><p>The infoset resulting from resolving inclusions on this document
|
|
is the same (except for the <em>include history</em>
|
|
and <em>language</em> properties)
|
|
as that of the following document:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<p>The following is the source of the "data.xml" resource:</p>
|
|
<example>&lt;?xml version='1.0'?&gt;
|
|
&lt;data&gt;
|
|
&lt;item&gt;&lt;![CDATA[Brooks &amp; Shields]]&gt;&lt;/item&gt;
|
|
&lt;/data&gt;</example>
|
|
</document></pre></div></div><div class="div2">
|
|
<h3><a name="fragment-example" id="fragment-example"></a>C.4 Fragment Inclusion Example</h3><p>The following illustrates the results of including fragments of
|
|
another XML document. Assume the base URI of the document is
|
|
<code>http://www.example.com/JoeSmithQuote.xml</code>.</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<price-quote xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<prepared-for>Joe Smith</prepared-for>
|
|
<good-through>20040930</good-through>
|
|
<xi:include href="price-list.xml" xpointer="w002-description"/>
|
|
<volume>40</volume>
|
|
<xi:include href="price-list.xml" xpointer="element(w002-prices/2)"/>
|
|
</price-quote></pre></div><p>price-list.xml references a DTD which declares the <code>id</code>
|
|
attributes as type <code>ID</code>, and contains:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<!DOCTYPE price-list SYSTEM "price-list.dtd">
|
|
<price-list xml:lang="en-us">
|
|
<item id="w001">
|
|
<description id="w001-description">
|
|
<p>Normal Widget</p>
|
|
</description>
|
|
<prices id="w001-prices">
|
|
<price currency="USD" volume="1+">39.95</price>
|
|
<price currency="USD" volume="10+">34.95</price>
|
|
<price currency="USD" volume="100+">29.95</price>
|
|
</prices>
|
|
</item>
|
|
<item id="w002">
|
|
<description id="w002-description">
|
|
<p>Super-sized widget with bells <i>and</i> whistles.</p>
|
|
</description>
|
|
<prices id="w002-prices">
|
|
<price currency="USD" volume="1+">59.95</price>
|
|
<price currency="USD" volume="10+">54.95</price>
|
|
<price currency="USD" volume="100+">49.95</price>
|
|
</prices>
|
|
</item>
|
|
</price-list></pre></div><p>The infoset resulting from resolving inclusions on this document
|
|
is the same (except for the <em>include history</em>
|
|
and <em>language</em> properties)
|
|
as that of the following document:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<price-quote xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<prepared-for>Joe Smith</prepared-for>
|
|
<good-through>20040930</good-through>
|
|
<description id="w002-description" xml:lang="en-us"
|
|
xml:base="http://www.example.com/price-list.xml">
|
|
<p>Super-sized widget with bells <i>and</i> whistles.</p>
|
|
</description>
|
|
<volume>40</volume>
|
|
<price currency="USD" volume="10+" xml:lang="en-us"
|
|
xml:base="http://www.example.com/price-list.xml">54.95</price>
|
|
</price-quote></pre></div></div><div class="div2">
|
|
<h3><a name="range-example" id="range-example"></a>C.5 Range Inclusion Example</h3><p>The following illustrates the results of including a range
|
|
specified by an XPointer. Assume the base URI of the document
|
|
is <code>http://www.example.com/document.xml</code>.</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document>
|
|
<p>The relevant excerpt is:</p>
|
|
<quotation>
|
|
<include xmlns="http://www.w3.org/2001/XInclude"
|
|
href="source.xml" xpointer="xpointer(string-range(chapter/p[1],'Sentence 2')/
|
|
range-to(string-range(/chapter/p[2]/i,'3.',1,2)))"/>
|
|
</quotation>
|
|
</document></pre></div><p>source.xml contains:</p><div class="exampleInner"><pre><chapter>
|
|
<p>Sentence 1. Sentence 2.</p>
|
|
<p><i>Sentence 3. Sentence 4.</i> Sentence 5.</p>
|
|
</chapter></pre></div><p>The infoset resulting from resolving inclusions on this document
|
|
is the same (except for the <em>include history</em>
|
|
and <em>language</em> properties)
|
|
as that of the following document:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<document>
|
|
<p>The relevant excerpt is:</p>
|
|
<quotation>
|
|
<p xml:base="http://www.example.com/source.xml">Sentence 2.</p>
|
|
<p xml:base="http://www.example.com/source.xml"><i>Sentence 3.</i></p>
|
|
</quotation>
|
|
</document></pre></div></div><div class="div2">
|
|
<h3><a name="fallback-example" id="fallback-example"></a>C.6 Fallback Example</h3><p>The following XML document relies on the fallback mechanism to
|
|
succeed in the event that the resources <code>example.txt</code> and
|
|
<code>fallback-example.txt</code> are not available..</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<div>
|
|
<xi:include href="example.txt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<xi:fallback><xi:include href="fallback-example.txt" parse="text">
|
|
<xi:fallback><a href="mailto:bob@example.org">Report error</a></xi:fallback>
|
|
</xi:include></xi:fallback>
|
|
</xi:include>
|
|
</div></pre></div><p>If neither <code>example.txt</code> nor <code>fallback-example.txt</code>
|
|
are available, the infoset resulting from resolving inclusions on this document
|
|
is the same (except for the <em>include history</em>
|
|
and <em>language</em> properties)
|
|
as that of the following document:</p><div class="exampleInner"><pre><?xml version='1.0'?>
|
|
<div>
|
|
<a href="mailto:bob@example.org">Report error</a>
|
|
</div></pre></div></div></div></div></body></html>
|