[4suite-checkins] In 4Suite/docs/xml/CoreManualSections, files Domlette.xml

[Mike Brown]

Update of /var/local/cvsroot/4Suite/docs/xml/CoreManualSections
In directory dollar:/tmp/cvs-serv29501/docs/xml/CoreManualSections

Modified Files:
	Domlette.xml 
Log Message:
in 'Building a DOM from scratch', changed examples to make it clear that the baseURI attribute is read-only;
expanded intro to state that DOM building is not really meant to be full featured

ViewCVS diff:
  http://cvs.4suite.org/viewcvs/4Suite/docs/xml/CoreManualSections/Domlette.xml.diff?r1=1.14&r2=1.15
ViewCVS view:
  http://cvs.4suite.org/viewcvs/4Suite/docs/xml/CoreManualSections/Domlette.xml?rev=1.15&content-type=text/vnd.viewcvs-markup

Index: Domlette.xml
===================================================================
RCS file: /var/local/cvsroot/4Suite/docs/xml/CoreManualSections/Domlette.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -U2 -r1.14 -r1.15
--- Domlette.xml	12 Apr 2006 21:06:12 -0000	1.14
+++ Domlette.xml	25 May 2006 05:04:21 -0000	1.15
@@ -24,5 +24,5 @@
 <methodname>Ft.Xml.CreateInputSource</methodname> for constructing <classname>InputSource</classname> instances.  In rare cases you might need lower-level APIs in in the <systemitem
         class="library">Ft.Xml.InputSource</systemitem> module. Read <xref
-        linkend="full_domlette_reader" /> if 
+        linkend="full_domlette_reader" /> if
         <methodname>Ft.Xml.Parse</methodname> isn't enough.
         </para>
@@ -332,5 +332,5 @@
       <methodname>parseString</methodname>(), or wrap it in an
       <classname>InputSource</classname> using <methodname>Ft.Xml.CreateInputSource</methodname>, or the
-      <methodname>fromString</methodname>() method of an 
+      <methodname>fromString</methodname>() method of an
       <classname>InputSourceFactory</classname>. If the string is not UTF-16 or
       UTF-8 encoded, then you must tell the reader what encoding it actually
@@ -1703,15 +1703,22 @@
 
     <para>As an alternative to parsing a preexisting XML document, you can
-    also build a document model from the ground up. The <systemitem
-    class="library">Ft.Xml.Domlette</systemitem> module contains a
-    <classname>DOMImplementation</classname> instance named
+    also build a document model, with certain limitations, from the ground up.
+    W3C and Python DOM facilities for doing this are intended mainly for creating
+    a temporary document whose nodes will be imported into an existing document,
+    and while Domlette does offer a more convenient document creation method,
+    it has many of the same limitations and also does not allow DOCTYPE info to be
+    set. However, for simple documents, its capabilities should be sufficient.</para>
+
+    <para>The <systemitem class="library">Ft.Xml.Domlette</systemitem> module
+    contains a <classname>DOMImplementation</classname> instance named
     <property>implementation</property> which provides a set of methods for
     initializing new <classname>Document</classname>s. The
-    <methodname>implementation.createRootNode</methodname> method provides a
-    natural approach for creating an XPath model root node. This is similar to
-    the DOM idea of a document node and even closer to a DOM document fragment
-    (multiple element children are allowed). The
+    <methodname>implementation.createRootNode</methodname> method takes a base URI
+    argument and provides a natural approach for creating an XPath model root node.
+    This is similar to the DOM idea of a document node and even closer to a DOM
+    document fragment (multiple element children are allowed). The
     <methodname>implementation.createDocument</methodname> method, on the
-    other hand, is designed to come close to the DOM interface.</para>
+    other hand, is designed to come close to the DOM interface, although its
+    doctype argument must be None.</para>
 
     <programlisting>doc = implementation.createRootNode('file:///article.xml')</programlisting>
@@ -1720,8 +1727,11 @@
 
     <programlisting>from Ft.Xml import EMPTY_NAMESPACE
-doc = implementation.createDocument(EMPTY_NAMESPACE, None, None)
-doc.baseURI = 'file:///article.xml'</programlisting>
+doc = implementation.createDocument(EMPTY_NAMESPACE, None, None)</programlisting>
+
+    <para>with the added advantage of doc.baseURI being set to
+    'file:///article.xml', which is not possible to set via standard DOM interfaces
+    (the baseURI attribute is read-only).</para>
 
-    <para>And similarly</para>
+    <para>Similarly,</para>
 
     <programlisting>from Ft.Xml import EMPTY_NAMESPACE
@@ -1733,6 +1743,7 @@
 
     <programlisting>from Ft.Xml import EMPTY_NAMESPACE
-doc = implementation.createDocument(EMPTY_NAMESPACE, 'article', None)
-doc.baseURI = 'file:///article.xml'</programlisting>
+doc = implementation.createDocument(EMPTY_NAMESPACE, 'article', None)</programlisting>
+
+    <para>plus doc.baseURI being set to 'file:///article.xml'.</para>
 
     <para>If you want as much fidelity to the DOM API as Domlette offers, use