[issue11379] Remove "lightweight" from minidom description

[Stefan Behnel]

Stefan Behnel <scoder at 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 <report at bugs.python.org>
<http://bugs.python.org/issue11379>
_______________________________________