Menu
▾
▴
[mvp-xml-cvs] WebSite/xinclude index.html,1.2,1.3
|
From: Oleg T. <he...@us...> - 2004-11-09 12:23:23
|
Update of /cvsroot/mvp-xml/WebSite/xinclude In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21807/xinclude Modified Files: index.html Log Message: fixed documentation Index: index.html =================================================================== RCS file: /cvsroot/mvp-xml/WebSite/xinclude/index.html,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- index.html 1 Nov 2004 17:42:04 -0000 1.2 +++ index.html 9 Nov 2004 12:23:11 -0000 1.3 @@ -5,7 +5,8 @@ <link href="../style.css" type="text/css" rel="stylesheet"> </head> <body> -<h1>Mvp.Xml Project: XInclude.NET module (version 1.3)<br> +<h1><a class="mozTocH1" name="mozTocId507464"></a><a + href="../index.html">Mvp.Xml Project</a>: XInclude.NET module<br> </h1> The XInclude.NET module provides an implementation of the <a href="http://www.w3.org/TR/xinclude/">W3C XML Inclusions (XInclude)1.0 @@ -22,16 +23,41 @@ XPointer xpointer() Scheme</a> (XPath subset only). XInclude.NET currently supports only streamable subset of the XInclude, implemented as fast, non-caching, forward-only <span - style="font-family: monospace;">Mvp.Xml.XInclude.XIncludingReader</span> -class. + style="font-family: monospace;">XIncludingReader</span> +class found in the <span style="font-family: monospace;">Mvp.Xml.XInclude</span> +namespace. <br> <p>XInclude.NET has been thoroughly tested against <!--StartFragment --><a href="http://www.w3.org/XML/Test/XInclude/">The XInclude Test Suite</a> under -Microsoft .NET 1.0 and 1.1 on Windows 2000 and Windows Server 2003.</p> -<h2>Requirements</h2> +Microsoft .NET 1.0 and 1.1 on Windows 2000 and Windows Server 2003.<br> +</p> +<p style="font-weight: bold;">Contents:</p> + <ol> + <li><a href="#mozTocId537061">Requirements</a></li> + <li><a href="#mozTocId172804">Download</a></li> + <li><a href="#mozTocId593736">Installation and +Documentation</a></li> + <li><a href="#mozTocId209347">History</a></li> + <li><a href="#mozTocId156645">Usage</a></li> + <li><a href="#mozTocId795134">Custom XmlResolver</a></li> + <li><a href="#mozTocId893216">XPointer</a></li> + <li><a href="#mozTocId299036">Conformance Issues </a></li> + <li><a href="#mozTocId670936">License</a></li> + <li><a href="#mozTocId666501">Bug reports</a></li> + <li><a href="#mozTocId594662">Feedback</a></li> + </ol> +<h2><a class="mozTocH2" name="mozTocId537061"></a>1. Requirements</h2> <p>XInclude.NET is .NET Framework application and requires <a href="http://msdn.microsoft.com/netframework/" target="_top"> .NET -Framework</a> version 1.0 or 1.1 to be installed. </p> -<h2>Installation and Documentation</h2> +Framework</a> version 1.0 or 1.1 to be installed.<br> +</p> +<h2><a class="mozTocH2" name="mozTocId172804"></a>2. Download</h2> +Go to the <a + href="http://sourceforge.net/project/showfiles.php?group_id=102352">Downloads</a> +page. You can download XInclude.NET module separately (with no +dependencies on other modules) or as part of the Mvp.Xml library +release (all modules in one).<br> +<h2><a class="mozTocH2" name="mozTocId593736"></a>3. Installation and +Documentation</h2> <p>Find precompiled <font style="font-family: monospace;" face="Courier New">Mvp.Xml.XInclude.dll</font> library in the "<font style="font-family: monospace;" face="Courier New">bin</font>" @@ -39,12 +65,16 @@ face="Courier New">src</font>" directory contains XInclude.NET sources in Visual Studio <br> .NET 2003 solution form. The API documentation can be found in the "<span - style="font-family: monospace;">doc</span>" directory (online version) -(#TODO). Test cases can be found in the "<span + style="font-family: monospace;">doc</span>" directory (<a + href="../api/">online version</a>). Test cases can be found in the "<span style="font-family: monospace;">test</span>" directory.<br> -In addition to the API documentation, refer to the "<a +In addition to the <a href="../api/">API documentation</a>, refer to +the "<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnxmlnet/html/xinclude.asp">Combining -XML Documents with XInclude</a>" article at the MSDN and the normative +XML Documents with XInclude</a>" article at the MSDN, which introduces +XInclude itself and provides details on usage and internal +implementation of the <span style="font-family: monospace;">XIncludingReader</span> +class. Additionally don't forget the normative specs:<br> </p> <ul> @@ -59,12 +89,13 @@ <li><a href="http://www.w3.org/TR/xptr-xpointer/">XPointer xpointer() Scheme</a></li> </ul> -<p></p> -<h2>History</h2> +<h2><a class="mozTocH2" name="mozTocId209347"></a>4. History</h2> Done since 1.2 release:<br> <ul> - <li>The new home - Mvp.Xml project and so the new namespace - -Mvp.Xml.XInclude instead of GotDotNet.XInclude.<br> + <li>The new home - <a href="http://mvp-xml.sf.net/">Mvp.Xml project</a> +and so the new namespace - <a href="../api/Mvp.Xml.XInclude.html"><span + style="font-family: monospace;">Mvp.Xml.XInclude</span></a> instead of + <span style="font-family: monospace;">GotDotNet.XInclude</span>.<br> </li> <li>Upgraded to support the new XInclude Proposed Rec syntax and semantics.</li> @@ -72,11 +103,16 @@ </li> <li>Performance improvements - documents included via XPointer are now cached.</li> - <li>Memory footprint is minimized.<br> + <li>Memory footprint is significantly minimized by using <a + href="http://msdn.microsoft.com/library/en-us/cpref/html/frlrfSystemXmlXPathXPathDocumentClassTopic.asp">XPathDocument</a> +instead of <a + href="http://msdn.microsoft.com/library/en-us/cpref/html/frlrfsystemxmlxmldocumentclasstopic.asp">XmlDocument</a> +for XPointer evaluation.<br> </li> <li>A suite of unit tests has been added, including the W3C XInclude Test Suite.</li> - <li>As a sequence - lots of bugs and incompatibilities has been fixed.<br> + <li>As a sequence - lots of bugs and incompatibilities have been +fixed.<br> </li> </ul> Done since 1.1 release:<br> @@ -101,11 +137,13 @@ schemas</li> <li>Minor bug fixes</li> </ul> -<h2>Usage</h2> -<p><a - href="../../../../temp/XInclude.NET-1.2/doc/GotDotNet.XInclude.XIncludingReader.html">XIncludingReader</a> -(#TODO) -class, found in the Mvp.Xml.XInclude namespace (#TODO), is the key +<h2><a class="mozTocH2" name="mozTocId156645"></a>5. Usage<br> +</h2> +<p><a style="font-family: monospace;" + href="../api/Mvp.Xml.XInclude.XIncludingReader.html">XIncludingReader</a> +class, found in the <a href="../api/Mvp.Xml.XInclude.html"><span + style="font-family: monospace;">Mvp.Xml.XInclude</span></a> namespace, +is the key class. It's customized <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemXmlXmlReaderClassTopic.asp"> XmlReader</a>, which implements streamable subset of the XInclude and @@ -120,10 +158,10 @@ in many different situations, e.g. before or after validation, before or after building XmlDocument or XPathDocument. Here are some obvious usage scenarios:</p> -<p>XML inclusion during reading XML:</p> +<p>XML inclusion during XML reading:</p> <p><code></code></p> <pre>XmlReader reader = new XIncludingReader("source.xml");<br>while (reader.Read()) {<br> ... <br> </pre> -<p>XML inclusion while building XmlDocument:</p> +<p>XML inclusion while building <span style="font-family: monospace;">XmlDocument</span>:</p> <p><code></code></p> <pre>XmlReader reader = new XIncludingReader(new XmlTextReader("source.xml"));<br>XmlDocument doc = new XmlDocument(); <br>doc.Load(reader);<br>... <br> </pre> <p>XML inclusion before an XSL Transformation:</p> @@ -131,67 +169,101 @@ <pre>XslTransform xslt = new XslTransform();<br>xslt.Load("stylesheet.xsl");<br>XmlReader reader = new XIncludingReader("source.xml");<br>XPathDocument xdoc = new XPathDocument(reader);<br>xslt.Transform(xdoc, null, new StreamWriter("result.xml"));<br>...</pre> <p>Find more examples and test cases in the "<font style="font-family: monospace;" face="Courier New">test</font>" -directory.</p> -<h2>Custom XmlResolver</h2> +directory.<br> +</p> +<p style="margin-left: 40px;"><span style="font-weight: bold;">Note</span>: +When using XInclude with XSLT, take a look at the <a + href="http://tkachenko.com/dotnet/nxslt.html">nxslt.exe</a> - +feature-rich .NET XSLT command line utility, which supports XInclude +via the XInclude.NET module.<br> +</p> +<h2><a class="mozTocH2" name="mozTocId795134"></a>6. Custom XmlResolver</h2> <p><span style="font-family: monospace;">XIncludingReader</span> -supports custom URI resolving. Just set your <span - style="font-family: monospace;">XmlResolver</span> object to the <span - style="font-family: monospace;">XmlResolver</span> property of the <span - style="font-family: monospace;">XIncludingReader</span>. <span +supports custom URI resolving. This way one can include XML documents +from a variety of sources, such as RDBMS or even generated on-the-fly. +Find a sample of inlcuding XML data from SQL Server <a + href="http://www.tkachenko.com/blog/archives/000105.html">here</a>.<br> +Just set your <span style="font-family: monospace;">XmlResolver</span> +object to the <a + href="../api/Mvp.Xml.XInclude.XIncludingReader.XmlResolver.html"><span + style="font-family: monospace;">XmlResolver</span> property</a> of the +<span style="font-family: monospace;">XIncludingReader</span>. <span style="font-family: monospace;">XIncludingReader</span> will call <span style="font-family: monospace;">ResolveUri()</span> and <span style="font-family: monospace;">GetEntity()</span> methods of your resolver when fetching a resource by URI referenced in "<span style="font-family: monospace;">href</span>" attribute of an <span style="font-family: monospace;">xi:include</span> element. A custom <span - style="font-family: monospace;">XmlResolver</span> must return either <span - style="font-family: monospace;">System.IO.Stream</span> or <span - style="font-family: monospace;">System.Xml.XmlReader</span> from the <span - style="font-family: monospace;">GetEntity()</span> method.</p> -<h2>XPointer</h2> -<p>XInclude.NET implements<!--StartFragment --> <a - href="http://www.w3.org/TR/xptr-framework/">XPointer Framework</a>,<!--StartFragment --> + style="font-family: monospace;">XmlResolver</span> must return either <a + href="http://msdn.microsoft.com/library/en-us/cpref/html/frlrfsystemiostreamclasstopic.asp"><span + style="font-family: monospace;">System.IO.Stream</span></a> or <span + style="font-family: monospace;"><a + href="http://msdn.microsoft.com/library/en-us/cpref/html/frlrfsystemiotextreaderclasstopic.asp">System.IO.TextReader</a> +or <a + href="http://msdn.microsoft.com/library/dotnet/cpref/frlrfsystemxmlxmlreaderclasstopic.htm">System.Xml.XmlReader</a></span> +from the <span style="font-family: monospace;">GetEntity()</span> +method.</p> +<h2><a class="mozTocH2" name="mozTocId893216"></a>7. XPointer</h2> +<p>XInclude.NET includes <a href="../xpointer/">XPointer.NET</a> +module, which implements <a href="http://www.w3.org/TR/xptr-framework/">XPointer +Framework</a><!--StartFragment -->, <a href="http://www.w3.org/TR/xptr-element/">XPointer element() Scheme</a>, <!--StartFragment --><a href="http://www.w3.org/TR/xptr-xmlns/">XPointer -xmlns() Scheme</a>,<!--StartFragment --> <a +xmlns() Scheme</a><!--StartFragment -->, <a href="http://www.simonstl.com/ietf/draft-stlaurent-xpath-frag-00.html">The XPointer xpath1() Scheme</a> and <a href="http://www.w3.org/TR/xptr-xpointer/"> XPointer xpointer() Scheme</a> (XPath subset only). </p> -<p><a - href="../../../../temp/XInclude.NET-1.2/doc/GotDotNet.XPointer.XPointerReader.html">XPointerReader</a> -class (#TODO), found in <span style="text-decoration: underline;">Mvp.Xml.</span><a - href="../../../../temp/XInclude.NET-1.2/doc/GotDotNet.XPointer.html">XPointer -namespace</a> (#TODO) represents XPointer-aware XmlReader and can -be used as such outside of XInclude context too.</p> -<h2>Conformance Issues<br> +<p><a href="../api/Mvp.Xml.XPointer.XPointerReader.html">XPointerReader</a> +class, found in the <a href="../api/Mvp.Xml.XPointer.html"><span + style="text-decoration: underline;">Mvp.Xml.</span></a><a + href="../api/Mvp.Xml.XPointer.html">XPointer +namespace</a> represents XPointer-aware XmlReader and can +be used as such outside of XInclude context too.<br> +Find more info at the <a href="../xpointer/">XPointer.NET</a> module +homepage.<br> +</p> +<h2><a class="mozTocH2" name="mozTocId299036"></a>8. Conformance Issues<br> </h2> <ol> - <li>Only streamable subset of XInclude is supported - intra-document -references are not supported.</li> - <li>Syntactically incorrect URI references are treated as resource -error.<br> + <li><span style="font-family: monospace;">XIncludingReader</span> +class only implenments the <a + href="http://www.w3.org/TR/2004/PR-xinclude-20040930/#include-location">streamable +subset</a> of XInclude - intra-document +references are not supported. That means <span + style="font-family: monospace;">XIncludingReader</span> treats absence +of an "<span style="font-family: monospace;">href</span>" attribute on +an <span style="font-family: monospace;">xi:include</span> element as <a + href="http://www.w3.org/TR/2004/PR-xinclude-20040930/#dt-resource-error">XInclude +resource error</a>.<br> + </li> + <li>Syntactically incorrect URI references are treated as <a + href="http://www.w3.org/TR/2004/PR-xinclude-20040930/#dt-resource-error">XInclude +resource +error</a>.</li> + <li>Only XPath subset of the <a + href="http://www.w3.org/TR/xptr-xpointer/">xpointer() XPointer Scheme</a> +is supported.<br> </li> </ol> -<h2>License</h2> -<p>XInclude.NET as part of the Mvp.Xml project is subject to the <a - href="../license.html">Common +<h2><a class="mozTocH2" name="mozTocId670936"></a>9. License</h2> +<p>XInclude.NET as part of the <a href="http://mvp-xml.sf.net/">Mvp.Xml +project</a> is subject to the <a href="../license.html">Common Public License</a> - <a href="http://www.opensource.org/licenses/index.php">OSI approved</a> -free open-source license.<a - href="http://gotdotnet.com/Community/Workspaces/License.aspx?id=cab253e8-cb4b-47c4-a9d9-6c42947b04a8"></a> +free open-source license. It's distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p> -<h2>Bug reports</h2> +<h2><a class="mozTocH2" name="mozTocId666501"></a>10. Bug reports</h2> <p>Please feel free to report any bugs to the Mvp.Xml project's <a href="http://sourceforge.net/tracker/?group_id=102352&atid=633328"> Bug Tracker</a>. Feature requests are also <a href="http://sourceforge.net/tracker/?group_id=102352&atid=633331">welcome</a>.<br> </p> -<h2>Feedback</h2> +<h2><a class="mozTocH2" name="mozTocId594662"></a>11. Feedback</h2> <p>We appreciate any kind of feedback, feel free to post any questions or comments about XInclude.NET and Mvp.Xml project in general in the <a |
