[Python-Dev] Fixing the XML batteries

[Nick Coghlan]

On Fri, Dec 9, 2011 at 6:41 PM, "Martin v. Löwis" <martin at v.loewis.de> wrote:
>> a) The stdlib documentation should help users to choose the right tool
>> right from the start. Instead of using the totally misleading wording
>> that it uses now, it should be honest about the performance
>> characteristics of MiniDOM and should actively suggest that those who
>> don't know what to choose (or even *that* they can choose) should not
>> use MiniDOM in the first place.
>
> I disagree. The right approach is not to document performance problems,
> but to fix them.

When we offer a better way to do something that new users are want to
do, we generally redirect them to the more recent alternative. I
believe the redirection from the getopt module to the argparse module
strikes the right tone for that kind of thing:
http://docs.python.org/library/getopt

For the various XML libraries, a message along the lines of "Note: The
<whatever> module is a <yada, yada, DOM based, whatever>. If all you
are trying to do is read and write XML files, consider using the
xml.etree.ElementTree module instead".

I'd also be +1 on adjusting the order of the XML pages in the main
index such that xml.etree.ElementTree appeared before xml.parser.expat
and all the others slid down one entry.

These are simple changes that don't harm current users of the modules
in the least, while being up front and very helpful for beginners.
Again, I think argparse vs getopt is a good comparison: argparse
appears first in the main index, and there's a redirection from getopt
to argparse that says "if you don't have a specific reason to be using
getopt, you probably want argparse instead".

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia