[docs] [issue10665] Expand unicodedata module documentation

[Alexander Belopolsky]

Alexander Belopolsky <belopolsky at users.sourceforge.net> added the comment:

On Fri, Dec 10, 2010 at 6:04 PM, Martin v. Löwis <report at bugs.python.org> wrote:
..
>> Why?  I thought "release early, release often" was a good thing.
>
> Create a branch for that, or post an issue on Rietveld.

Martin,

This is a documentation patch affecting a single HTML page.  An svn
branch for something like this is certainly an overkill.  Maybe when
branches become more user-friendly with Hg, it will make sense to do
something like this in a branch.   Rietveld is great for code reviews,
but for doc patches its is sometimes desirable to post a rendered page
for a review.  In this particular case, however the reST in diff is
quite readable.

> W-I-P IMO
> confuses people reviewing the patches, running into the same ones
> over-and-over again, only to find out every time "it's not ready yet".

I posted this patch with a specific question: "how much of the Unicode
Standard information we would want to present?"   The patch included
several tables similar to what a determined reader can find at
unicode.org.   I think it is useful to present this information in the
Python docs for several reasons:

1. It makes the information more readily accessible to someone who
just want to figure out what the code returned by
unicodedata.category() means.

2. We can present examples using Python notation and focus on what is
relevant to Python users.  For example, what are the digits other than
0-9, or what is the difference between a digit and a decimal.

3. Other parts of the documentation can refer to this information more
easily.  For example, str.isdigit() can refer to 'Nd' general
category.

The downside is that we may need to update this info when Unicode
Standard changes.  Given the pace of change for this info, I don't
think this is serious burden and most of the data can be
auto-generated from UCD files.

> So the natural reaction is to close it as rejected, for it being
> incomplete.

Are you going to reject say issue2636 on this basis? :-)   Has *any*
patch ever been rejected as incomplete?

Seriously, I had a specific reason to post an incomplete patch for
review: formatting reST tables is tedious and if others think we
should not include this info in Python docs, I don't want to spend
more time polishing the patch.  On the other hand, an incomplete patch
is helpful because it demonstrates how much information I am proposing
to include.  If I just posted a request without a patch, a natural
reaction would be: do you have a patch?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10665>
_______________________________________