This patch should clarify how to use cElementTree usage, as well as improving indexing.

Éric, indeed it clarifies the usage, but my concern is that it also moves the first mention of the module further down.

There's no real reason for someone using CPython 2.7 or 3.2 *not* to use cET. So, some mention should appear in the opening paragraph. I'm attaching a patch that shows one possibility (based on your patch). It was generated vs. branch 2.7

Also, I must add that I absolutely hate the opening paragraph of the documentation in this module. Once 14006 is implemented, parts of it should be backported to 2.7 and 3.2

That would be an orthogonal change to what we're discussion here, though

+1.  Barring other feedback, I will commit your patch.

> Also, I must add that I absolutely hate the opening paragraph of the
> documentation in this module.

This:

  The :class:`Element` type is a flexible container object, designed to store
  hierarchical data structures in memory.  The type can be described as a cross
  between a list and a dictionary.

?  Yeah, it’s not quite good.

If you want to collect additional feedback, you may want to add some other people to the Nosy list :-) Alternatively, since it's a small doc change you can just commit it and it can be fixed later if someone strongly objects.

>>>
This:

  The :class:`Element` type is a flexible container object, designed to store
  hierarchical data structures in memory.  The type can be described as a cross
  between a list and a dictionary.

?  Yeah, it’s not quite good.
>>>

Yes. You read the first section of a module's doc and you have *no idea* what the module is and how to use it. I plant to work on this for 3.3 in the context of issue 14006.

> If you want to collect additional feedback, you may want to add some other
> people to the Nosy list :-)
I did not want more feedback, I wanted to leave time for interested parties to find this bug for themselves and eventually comment :)

One question: when I merge the new doc from 3.2 to 3.3, do I remove the new section, as the cET module is now deprecated?  If I do that we’d lose the indexing (i.e. without a module directive there will be no entry in the module index not the alphabetical index).  I could leave the cET section so that we get the indexing but change the text to “Deprecated alias of ET.”

> > If you want to collect additional feedback, you may want to add some
> other
> > people to the Nosy list :-)
> I did not want more feedback, I wanted to leave time for interested
> parties to find this bug for themselves and eventually comment :)
>
> One question: when I merge the new doc from 3.2 to 3.3, do I remove the
> new section, as the cET module is now deprecated?  If I do that we’d lose
> the indexing (i.e. without a module directive there will be no entry in the
> module index not the alphabetical index).  I could leave the cET section so
> that we get the indexing but change the text to “Deprecated alias of ET.”
>

I don't see a need for cElementTree to be indexed in the doc of 3.3
Assuming a new Python user who starts with 3.3, he should not even know
about the existence of cElementTree (bar a small notice that says it's
deprecated, which will be of no interest to him). The cElementTree module
stays in its place in 3.3, but that's only for backwards compatibility.
Officially, it doesn't exist :)

> Officially, it doesn't exist :)

Keep in mind that many users will find about it from the Internet, and it's better to clearly say what it is and that it shouldn't be used anymore than pretending it doesn't exist.  (AFAIU this is the current situation, since there is a warning, but leaving it indexed wouldn't hurt IMHO.)

Developers with existing code can reasonably be expected to look it up
based on what they're currently importing, so an entry that points to
the new recommended practice is good.

Éric, what stops us from closing this issue?

Given Ezio and Fred's feedback, I don't object to indexing cET in 3.3 - I guess it can't hurt.

I will commit the patch, keeping the indexing in 3.3 as agreed.  I just moved to a new city, so today is paperwork day but in the evening or tomorrow I’ll do Python work :)

The ET docs have been significantly revamped in 3.3

I don't think cET needs to be documented. It's just confusing.