New Python regex Doc (was: Python documentation moronicities)

[Jeff Epler]

To add to what others have said:

* Typos and lack of spell-checking, such as "occurances" vs "occurrences"

* Poor grammar, such as "Other characters that has special meaning
  includes:"

* You dropped version-related notes like "New in version 2.4"

* You seem to love the use of <HR>s, while docs.python.org uses them
  sparingly

* The category names you created, "Wildcards", "Repetition Qualifiers",
  and so forth, don't help me understand regular expressions any better
  than the original document

* Your document dropped some basic explanations of how regular
  expressions work, without a replacement text:
    Regular expressions can be concatenated to form new regular
    expressions; if A and B are both regular expressions, then AB is
    also a regular expression. In general, if a string p matches A and
    another string q matches B, the string pq will match AB. [...] Thus,
    complex expressions can easily be constructed from simpler primitive
    expressions like the ones described here.
  Instead, you start off with one unclear example ("a+" matching
  "aaaahh!") and one misleading example (a regular expression that
  matches some tiny subset of valid e-mail addresses)

* You write
    Characters that have special meanings in regex do not have special
    meanings when used inside []. For example, '[b+]' does not mean one
    or more b; It just matches 'b' or '+'.
  and then go on to explain that backslash still has special meaning; I
  see that the original documentation has a similar problem, but this
  just goes to show that you aren't improving the accuracy or clarity of
  the documentation in most cases, just rewriting it to suit your own
  style.  Or maybe just as an excuse to write offensive things like "[a]
  fucking toy whose max use is as a simplest calculator"

I can't see anything to make me recommend this documentation over the
existing documentation.

Jeff
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-list/attachments/20050506/983cfc60/attachment.sig>