Update tostring docs, plus more doc cleanup

2 files changed, 40 insertions, 11 deletions

diff --git a/docs/api/xmlstream/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst
index afed7655..f575299e 100644
--- a/docs/api/xmlstream/stanzabase.rst
+++ b/docs/api/xmlstream/stanzabase.rst
@@ -1,13 +1,13 @@
 .. _stanzabase:
 
-==========
-stanzabase
-==========
+==============
+Stanza Objects
+==============
 
 .. module:: sleekxmpp.xmlstream.stanzabase
 
-The :mod:`sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the
-standard :mod:`xml.etree.cElementTree` module that makes working with XML
+The :mod:`~sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the
+standard :mod:`~xml.etree.ElementTree` module that makes working with XML
 less painful. Instead of having to manually move up and down an element
 tree and insert subelements and attributes, you can interact with an object
 that behaves like a normal dictionary or JSON object, which silently maps
@@ -52,7 +52,7 @@ elements of the original XML chunk.
 .. seealso::
     :ref:`create-stanza-interfaces`.
 
-Because the :mod:`sleekxmpp.xmlstream.stanzabase` module was developed
+Because the :mod:`~sleekxmpp.xmlstream.stanzabase` module was developed
 as part of an `XMPP <http://xmpp.org>`_ library, these chunks of XML are
 referred to as :term:`stanzas <stanza>`, and in SleekXMPP we refer to a
 subclass of :class:`ElementBase` which defines the interfaces needed for
diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst
index 038b7876..82a8c2a5 100644
--- a/docs/api/xmlstream/tostring.rst
+++ b/docs/api/xmlstream/tostring.rst
@@ -1,17 +1,46 @@
-========
-tostring
-========
-
 .. module:: sleekxmpp.xmlstream.tostring
 
 .. _tostring:
 
 XML Serialization
------------------
+=================
+
+Since the XML layer of SleekXMPP is based on :mod:`~xml.etree.ElementTree`,
+why not just use the built-in :func:`~xml.etree.ElementTree.tostring`
+method? The answer is that using that method produces ugly results when
+using namespaces. The :func:`tostring()` method used here intelligently
+hides namespaces when able and does not introduce excessive namespace
+prefixes::
+
+    >>> from sleekxmpp.xmlstream.tostring import tostring
+    >>> from xml.etree import cElementTree as ET
+    >>> xml = ET.fromstring('<foo xmlns="bar"><baz /></foo>')
+    >>> ET.tostring(xml)
+    '<ns0:foo xmlns:ns0="bar"><ns0:baz /></foo>'
+    >>> tostring(xml)
+    '<foo xmlns="bar"><baz /></foo>'
+
+As a side effect of this namespace hiding, using :func:`tostring()` may
+produce unexpected results depending on how the :func:`tostring()` method
+is invoked. For example, when sending XML on the wire, the main XMPP
+stanzas with their namespace of ``jabber:client`` will not include the
+namespace because that is already declared by the stream header. But, if
+you create a :class:`~sleekxmpp.stanza.message.Message` instance and dump
+it to the terminal, the ``jabber:client`` namespace will appear.
 
 .. autofunction:: tostring
 
 Escaping Special Characters
 ---------------------------
 
+In order to prevent errors when sending arbitrary text as the textual
+content of an XML element, certain characters must be escaped. These
+are: ``&``, ``<``, ``>``, ``"``, and ``'``. The default escaping
+mechanism is to replace those characters with their equivalent escape
+entities: ``&amp;``, ``&lt;``, ``&gt;``, ``&apos;``, and ``&quot;``.
+
+In the future, the use of CDATA sections may be allowed to reduce the
+size of escaped text or for when other XMPP processing agents do not
+undertand these entities.
+
 .. autofunction:: xml_escape