Hi,
After reading tomo cocoa mail at docs@ I gave a look at c-api/unicode file and fixed some minor editing issues.

Regards,
Sandro

In addition, is there a reason for the sorting of UTF-8 UTF-32 UTF-16 and UTF-7 sections? why not alphabetically?

Also, several parts of the doc would need paragraph re-indentation (not done in this patch due to clarity).

Sandro Tosi wrote:
> 
> Sandro Tosi <sandro.tosi@gmail.com> added the comment:
> 
> In addition, is there a reason for the sorting of UTF-8 UTF-32 UTF-16 and UTF-7 sections? why not alphabetically?

No particular reason. Alphabetical order would be just as good.

Note that such changes would have to be backported in order to
keep the merge conflicts to a minimum.

> Also, several parts of the doc would need paragraph re-indentation (not done in this patch due to clarity).

Not sure what you mean here.

Sandro Tosi wrote:
> 
> New submission from Sandro Tosi <sandro.tosi@gmail.com>:
> 
> Hi,
> After reading tomo cocoa mail at docs@ I gave a look at c-api/unicode file and fixed some minor editing issues.

Thanks. Looks good !

On Tue, Apr 12, 2011 at 23:34, Marc-Andre Lemburg
<report@bugs.python.org> wrote:
> Sandro Tosi wrote:
>>
>> Sandro Tosi <sandro.tosi@gmail.com> added the comment:
>>
>> In addition, is there a reason for the sorting of UTF-8 UTF-32 UTF-16 and UTF-7 sections? why not alphabetically?
>
> No particular reason. Alphabetical order would be just as good.
>
> Note that such changes would have to be backported in order to
> keep the merge conflicts to a minimum.

It applies cleanly on 3.2 (module some offsets), not as good on 3.1
and 2.7: do you want me to prepare patches specifically for those 2
brances?

>> Also, several parts of the doc would need paragraph re-indentation (not done in this patch due to clarity).
>
> Not sure what you mean here.

sorry, I meant wrap at 80th column (or so) :)

Cheers.
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

Sandro Tosi wrote:
> 
> Sandro Tosi <sandro.tosi@gmail.com> added the comment:
> 
> On Tue, Apr 12, 2011 at 23:34, Marc-Andre Lemburg
> <report@bugs.python.org> wrote:
>> Sandro Tosi wrote:
>>>
>>> Sandro Tosi <sandro.tosi@gmail.com> added the comment:
>>>
>>> In addition, is there a reason for the sorting of UTF-8 UTF-32 UTF-16 and UTF-7 sections? why not alphabetically?
>>
>> No particular reason. Alphabetical order would be just as good.
>>
>> Note that such changes would have to be backported in order to
>> keep the merge conflicts to a minimum.
> 
> It applies cleanly on 3.2 (module some offsets), not as good on 3.1
> and 2.7: do you want me to prepare patches specifically for those 2
> brances?

I think you misunderstood: when reorganizing the contents of
a file, it's better to apply the patch to all branches, rather
than just the current, since otherwise future patches that do
have to be merged to all branches would cause lots of merge
conflicts.

>>> Also, several parts of the doc would need paragraph re-indentation (not done in this patch due to clarity).
>>
>> Not sure what you mean here.
> 
> sorry, I meant wrap at 80th column (or so) :)

Ah, ok.

That's the same category of change as the reorg above
(due to diff working line-based and not word based).

Such changes are fine, but should only be applied occasionally
and then preferably as one big commit to minimize disruption.

Rewrapping the paragraphs you are changing is fine, the others can be left as they are.
Patches should be against the oldest branch where they can be applied, and since this is a doc patch it can go in 2.7 and 3.1 too.
Regarding the order of the codecs, I would leave UTF-7 last because it's not commonly used, changing them to 8/16/32/7 is probably OK though.

On Tue, Apr 12, 2011 at 23:56, Marc-Andre Lemburg
<report@bugs.python.org> wrote:
> Marc-Andre Lemburg <mal@egenix.com> added the comment:
> I think you misunderstood: when reorganizing the contents of
> a file, it's better to apply the patch to all branches, rather
> than just the current, since otherwise future patches that do
> have to be merged to all branches would cause lots of merge
> conflicts.

the problem is: the file Doc/c-api/unicode.rst is already different
between all the "open" branches. I'll provide patches for each of
them, or specify where the patch can be merged (and from where).

> Ezio Melotti <ezio.melotti@gmail.com> added the comment:
>
> Rewrapping the paragraphs you are changing is fine, the others can be left as they are.

Once I was told not to, since in this case it will hide the changes I
made in between the rewrap.

> Patches should be against the oldest branch where they can be applied, and since this is a doc patch it can go in 2.7 and 3.1 too.

I'm just about to prepare patches for all the supported branches
(where a merge is not possible).

The status of the patches is this:

unicode_doc-2.7.patch - to be applied on 2.7
unicode_doc-3.1.patch - to be applied on 3.1
unicode_doc-default.patch - to be applied on 3.2 and then merged on default

I had to prepare multiple patches since the files are very different between supported branches.

New changeset 11c72a305eb5 by Ezio Melotti in branch '3.1':
#11840: Improve c-api/unicode documentation. Patch by Sandro Tosi.
http://hg.python.org/cpython/rev/11c72a305eb5

New changeset 62679f2ca9e5 by Ezio Melotti in branch '3.2':
#11840: Merge with 3.1.
http://hg.python.org/cpython/rev/62679f2ca9e5

New changeset 1f767f834e67 by Ezio Melotti in branch 'default':
#11840: Merge with 3.2.
http://hg.python.org/cpython/rev/1f767f834e67

New changeset 7f873729484c by Ezio Melotti in branch '2.7':
#11840: Improve c-api/unicode documentation. Patch by Sandro Tosi.
http://hg.python.org/cpython/rev/7f873729484c

Fixed, thanks for the patch!

About the rewrapping:
  * rewrapping what you change is OK, because I know that you changed something and had to rewrap it;
  * leaving what you changed badly-wrapped is not OK, because it makes the doc a mess after a while;
  * rewrapping unrelated things with no changes in the same patch is not OK, because it's hard to see if it's just rewrapping or changes+rewrapping;
  * doing rewrap-only changes might be OK but usually not worth it, and if done it should be done on all the branches.