Commits

Walter Dörwald committed cb65178

Update documentation in XIST_Howto.xml.

Comments (0)

Files changed (1)

docs/XIST_Howto.xml

 <section><h>Generating &xml; trees from &xml; files</h>
 <p>&xml; trees can also be generated by parsing &xml; files.
 For this the module <pyref module="ll.xist.parsers"><mod>ll.xist.parsers</mod></pyref>
-provides several functions:</p>
-<dl>
-<dt><lit>parsestring(data, base=None, encoding=None, **builderargs)</lit></dt>
-<dd>Parse the string <var>data</var> into an &xist; tree.</dd>
-<dt><lit>parseiter(iterable, base=None, encoding=None, **builderargs)</lit></dt>
-<dd>Parse the input from the iterable <var>iterable</var> (which must produce the
-input in chunks of bytes) into an &xist; tree.</dd>
-<dt><lit>parsestream(stream, base=None, encoding=None, bufsize=8192, **builderargs)</lit></dt>
-<dd>Parse &xml; from the stream <var>stream</var> into an &xist; tree.</dd>
-<dt><lit>parsefile(filename, base=None, encoding=None, bufsize=8192, **builderargs)</lit></dt>
-<dd>Parse &xml; input from the file named <var>filename</var>.</dd>
-<dt><lit>parseurl(name, base=None, encoding=None, bufsize=8192, headers=None, data=None, **builderargs)</lit></dt>
-<dd>Parse &xml; input from the &url; <var>name</var> into an &xist; tree.</dd>
-<dt><lit>parseetree(tree, base=None, **builderargs)</lit></dt>
-<dd>Parse &xml; input from the object <var>tree</var> which must support the
-<a href="http://effbot.org/zone/element-index.htm">ElementTree</a> &api;.</dd>
-</dl>
+provides several tools.</p>
+
 <p>For example, parsing a string can be done like this:</p>
 <example><h>Parsing a string</h>
 <prog><![CDATA[
 from ll.xist import parsers
 from ll.xist.ns import html
 
-node = parsers.parsestring("<p>Hello <a href='http://www.python.org/'>Python</a> world!</p>")
+node = parsers.tree(
+	"<p>Hello <a href='http://www.python.org/'>Python</a> world!</p>",
+	parsers.Expat(),
+	parsers.NS(html),
+	parsers.Instantiate()
+)
 ]]></prog>
 </example>
 
 <p>For further info about the arguments to the parsing functions, see the
 documentation for
-<pyref module="ll.xist.parsers" class="Builder"><class>ll.xist.parsers.Builder</class></pyref>.</p>
+<pyref module="ll.xist.parsers"><mod>ll.xist.parsers</mod></pyref>.</p>
 </section>
 </section>
 
 <tty>
 <prompt>&gt;&gt;&gt; </prompt><input>node = html.a(u"Python", href=u"http://www.python.org/")</input>
 <prompt>&gt;&gt;&gt; </prompt><input>print node[u"href"].bytes()</input>
-href="http://www.python.org/"
+ href="http://www.python.org/"
 <prompt>&gt;&gt;&gt; </prompt><input>del node.attrs.href</input>
 <prompt>&gt;&gt;&gt; </prompt><input>print node[u"href"].bytes()</input>
 
 <prompt>&gt;&gt;&gt; </prompt><input>node[u"href"] = u"http://www.python.org"</input>
 <prompt>&gt;&gt;&gt; </prompt><input>print node.attrs.href.bytes()</input>
-href="http://www.python.org/"
+ href="http://www.python.org/"
 </tty>
 </example>
 
 <prog><![CDATA[
 s = '<cool xmlns="http://xmlns.example.org/foo"><python/></cool>'
 
-node = parsers.parsestring(s, pool=pool)
+node = parsers.tree(s, parsers.Expat(ns=True), pool)
 ]]></prog>
 </example>
 
 <prog><![CDATA[
 s = '<cool><python/></cool>'
 
-node = parsers.parsestring(s, pool=pool, prefixes={None: "http://xmlns.example.org/foo"})
+node = parsers.tree(s, parsers.Expat(), parsers.NS("http://xmlns.example.org/foo"), pool)
 ]]></prog>
 </example>
 
 <p>If you have many elements, registering them in a pool becomes cumbersome.
 In this case you can put your element classes into a module and then
-register the module in the pool:</p>
+register all elements in the the module:</p>
 
 <example><h>Registering modules in a pool</h>
 <prog>
 print e.bytes(prefixes={html: None, xlink: "xl"})
 </prog>
 
-<p>Finally it's possible to suppress output of namespace declarations
-for certain namespaces by using the <var>hidexmlns</var> attribute:</p>
-</section>
+<p>Furthermore it's possible to suppress output of namespace declarations
+for certain namespaces by using the <var>hidexmlns</var> argument:</p>
 
 <prog>
-print e.bytes(prefixes={html: None, xlink: "xl"}, hidexmlns=[html, xlink])
+print e.bytes(prefixes={html: None, xlink: "xl"}, hidexmlns=(html, xlink))
 </prog>
 
 <p>This will output:</p>
 </html>
 ]]></prog>
 
+
+<p>Finally it's possible to force the output of namespace declarations
+for certain namespaces (even if elements from those namespaces are not in the
+tree) by using the <var>showxmlns</var> argument:</p>
+
+<prog>
+print html.div().bytes(prefixes={html: None, xlink: "xl"}, showxmlns=(xlink,))
+</prog>
+
+<p>This will output:</p>
+<prog><![CDATA[<div xmlns="http://www.w3.org/1999/xhtml" xmlns:xl="http://www.w3.org/1999/xlink"></div>]]></prog>
+
+</section>
 </section>
 </spc:wrap>