Refreshed the documentation a bit

README.markdown

@@ -1,10 +1,14 @@
 Streamxmlwriter
 ===============
 
-Streamxmlwriter is a simple python library for writing XML files. It
-is very similar to the SimpleXMLWriter that is included in Fredrik
-Lundh's ElementTree package, but also supports pretty-printing and
-custom element attribute ordering.
+Streamxmlwriter is a simple python library for writing XML files.
+
+It allows you to generate XML documents without building the whole
+document tree in memory first, which means you can generate
+arbitrarily large documents with a very small memory footprint.
+
+Its features include pretty-printing and custom ordering of element
+attributes.
 
 
 Usage example
@@ -14,21 +18,31 @@ Usage example
     >>> output = StringIO()
 
     >>> from streamxmlwriter import XMLWriter
-    >>> writer = XMLWriter(output)
-    >>> writer.start("foo", one="1", two="2")
-    >>> writer.data("something")
+    >>> writer = XMLWriter(output, pretty_print=True)
+
+    >>> writer.start_ns("a", "http://example.org/ns")
+    >>> writer.start("foo", {"{http://example.org/ns}one": "1"}, two="2")
     >>> writer.start("bar")
+    >>> writer.data("something")
+    >>> writer.end("bar")
+    >>> writer.comment("hello")
+    >>> writer.element("{http://example.org/ns}baz", data="whatnot", x="y")
+    >>> writer.start("empty")
     >>> writer.close()
-    
+
     >>> print output.getvalue()
-    <foo one="1" two="2">something<bar /></foo>
-
+    <foo xmlns:a="http://example.org/ns" two="2" a:one="1">
+      <bar>something</bar>
+      <!--hello-->
+      <a:baz x="y">whatnot</a:baz>
+      <empty />
+    </foo>
+
 
 The API
 -------
 
-### writer = XMLWriter(file, encoding="utf-8", pretty_print=False, sort=True)
-
+### writer = XMLWriter(file, encoding="utf-8", pretty_print=False, sort=True, abbrev_empty=True)
 creates a new writer instance that writes its output to the file-like
 object you pass as the first argument. There are a few optional
 arguments as well:
@@ -40,12 +54,19 @@ arguments as well:
 * If `sort` is `True`, every element's attributes will be
   lexicographically sorted by name. See "Attribute ordering" below for
   more advanced options. Default: `True`.
+* If `abbrev_empty` is False, empty elements are serialized as a
+  start-end tag pair (`<foo></foo>`), instead of the shorter form
+  (`<foo />`). Default: `True`.
 
-### writer.start(tag, attributes=None, **kwargs)
+### writer.start(tag, attributes=None, nsmap=None, **kwargs)
 opens an element whose tag is `tag`. To specify attributes, you can
 pass it a dictionary as the second argument. In most cases, it's
 easier to specify each attribute as a keyword argument.
 
+`nsmap` is an optional dictionary, mapping namespace prefixes to URIs.
+This is used automatically if you serialize `Element` instances from
+lxml using the `element` method.
+
 ### writer.end(tag)
 closes the most recently opened element. If you pass it a `tag` that
 doesn't match the open element, the writer raises an `XMLSyntaxError`.
@@ -65,6 +86,27 @@ serialized, including children.
 ### writer.declaration()
 outputs an XML declaration. If the character encoding is not
 `us-ascii` or `utf-8`, it is called automatically by the constructor.
+Does nothing if a declaration has already been written. Raises
+`XMLSyntaxError` if XML element data has already been written.
+
+### writer.comment(data)
+outputs an XML comment.
+
+### writer.pi(target, data)
+outputs an XML processing instruction.
+
+### writer.start_ns(prefix, uri)
+adds a namespace prefix mapping to be included in the next start tag.
+
+### writer.end_ns()
+does nothing (namespace scope is handled automatically).
+
+### writer.iterwrite(events)
+writes XML data based on (event, elem) tuples of the kind that you get
+from `iterparse` in ElementTree and lxml. `start`, `end`, `start-ns`,
+`end-ns`, `comment` and `pi` events are currently supported. Note that
+the `events` iterable *must* include `start` events, since the
+document structure can't be inferred from `end` elements alone.
 
 ### writer.close()
 Closes all open elements.
@@ -80,10 +122,17 @@ the constructor's `sort` argument. In that dictionary:
 * each corresponding value is a list of attribute names in the order
   you want them to occur in the XML data for that tag.
 
-You can use `None` as a tag name to specify a default order for all
-tags that don't have specific entries. A `None` value in the list of
-attribute names can be used as a place marker for all attributes whose
-names are not in the list; by default, they will be placed last.
+If `None` appears in the list, it acts as a wildcard for all
+attributes not explicitly named in the list. (By default, they will be
+placed last.)
+
+Example::
+
+    attrib_order = {
+        "person": ["id", "first_name", "last_name"],
+        "foo": ["id", None, "put_me_last"],
+    }
+
 
 
 License