Stefan Behnel <sco...@users.sourceforge.net> added the comment:

I started a mailing list thread on the same topic:

http://thread.gmane.org/gmane.comp.python.devel/127963

Especially see

http://thread.gmane.org/gmane.comp.python.devel/127963/focus=128162

where I extract a proposal from the discussion. Basically, there should be a 
note at the top of the xml.dom documentation as follows:

"""
[[Note: The xml.dom.minidom module provides an implementation of the W3C-DOM 
whose API is similar to that in other programming languages. Users who are 
unfamiliar with the W3C-DOM interface or who would like to write less code for 
processing XML files should consider using the xml.etree.ElementTree module 
instead.]]
"""

I think this should go on the xml.dom.minidom page as well as the xml.dom 
package page. Hand-wavingly, users who are new to the DOM are more likely to 
hit the package page first, whereas those who know it already will likely find 
the MiniDOM page directly.

Note that I'd still encourage the removal of the misleading word "lightweight" 
until it makes sense to put it back in a meaningful way. I therefore propose 
the following minimalistic changes to the first paragraph on the minidom page:

"""
xml.dom.minidom is a [-XXX: light-weight] implementation of the Document Object 
Model interface. It is intended to be simpler than the full DOM and also [+XXX: 
provide a] significantly smaller [+XXX: API].
"""

Additionally, the documentation on the xml.sax page would benefit from the 
following paragraph:

"""
[[Note: The xml.sax package provides an implementation of the SAX interface 
whose API is similar to that in other programming languages. Users who are 
unfamiliar with the SAX interface or who would like to write less code for 
efficient stream processing of XML files should consider using the iterparse() 
function in the xml.etree.ElementTree module instead.]]
"""

----------

_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to