Walter Dörwald committed cb65178

Update documentation in XIST_Howto.xml.

Comments (0)

Files changed (1)


 <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>
-<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="">ElementTree</a> &api;.</dd>
+provides several tools.</p>
 <p>For example, parsing a string can be done like this:</p>
 <example><h>Parsing a string</h>
 from ll.xist import parsers
 from ll.xist.ns import html
-node = parsers.parsestring("<p>Hello <a href=''>Python</a> world!</p>")
+node = parsers.tree(
+	"<p>Hello <a href=''>Python</a> world!</p>",
+	parsers.Expat(),
+	parsers.NS(html),
+	parsers.Instantiate()
 <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>
 <prompt>&gt;&gt;&gt; </prompt><input>node = html.a(u"Python", href=u"")</input>
 <prompt>&gt;&gt;&gt; </prompt><input>print node[u"href"].bytes()</input>
+ href=""
 <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""</input>
 <prompt>&gt;&gt;&gt; </prompt><input>print node.attrs.href.bytes()</input>
+ href=""
 s = '<cool xmlns=""><python/></cool>'
-node = parsers.parsestring(s, pool=pool)
+node = parsers.tree(s, parsers.Expat(ns=True), pool)
 s = '<cool><python/></cool>'
-node = parsers.parsestring(s, pool=pool, prefixes={None: ""})
+node = parsers.tree(s, parsers.Expat(), parsers.NS(""), pool)
 <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>
 print e.bytes(prefixes={html: None, xlink: "xl"})
-<p>Finally it's possible to suppress output of namespace declarations
-for certain namespaces by using the <var>hidexmlns</var> attribute:</p>
+<p>Furthermore it's possible to suppress output of namespace declarations
+for certain namespaces by using the <var>hidexmlns</var> argument:</p>
-print e.bytes(prefixes={html: None, xlink: "xl"}, hidexmlns=[html, xlink])
+print e.bytes(prefixes={html: None, xlink: "xl"}, hidexmlns=(html, xlink))
 <p>This will output:</p>
+<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>
+print html.div().bytes(prefixes={html: None, xlink: "xl"}, showxmlns=(xlink,))
+<p>This will output:</p>
+<prog><![CDATA[<div xmlns="" xmlns:xl=""></div>]]></prog>