[perl-python] Python documentation moronicities (continued)

[Xah Lee]

http://python.org/doc/2.4.1/lib/module-re.html
http://python.org/doc/2.4.1/lib/node114.html

---------
QUOTE
The module defines several functions, constants, and an exception. Some
of the functions are simplified versions of the full featured methods
for compiled regular expressions. Most non-trivial applications always
use the compiled form
UNQUOTE
What does a programer who wants to use regex gets out from this piece
of motherfucking irrevalent drivel?

----------
QUOTE
compile(
pattern[, flags])

Compile a regular expression pattern into a regular expression object,
which can be used for matching using its match() and search() methods,
described below.

The expression's behaviour can be modified by specifying a flags
value. Values can be any of the following variables, combined using
bitwise OR (the | operator).
UNQUOTE
What exactly is it fucking saying?

I wanted to use regex to find & replace on text. I've read in a file.
Trying to reading this fucking doc is a pain in the ass. What are these
"flags"? Do i do

re.compile(r'mypat','M') or
re.compile(r'mypat',M)
or perhaps
re.compile(r'mypat',re.M)

The M isn't a fucking variable. Why does the doc incompetently use that
term?
And what the fuck is it unclearly meant by "OR" operator with the
mother fucking bitwise jargon?

All a person reading regex really wanted is to see how to use a string
pattern and replace it with another. The fucking doc cannot be possibly
fucking worsely written.

Fuck the mother fucking coders in the IT industry.

So, is
re.compile(r'mypat','M')
re.compile(r'mypat','MULTILINE')
equivalent?

and, by that fucking bitwise shit is it meant to say like
re.compile(r'mypat','M'|'U')
?

why cannot this piece of shit writing give a single example of usage?
and motherfucking confusedly organized, with fucking variable terms the
writer don't fucking understand, and meanwhile always trying to sound
big asshole and don't stop at masturbation by mention a regex book and
not hesitate to mention another language Perl. Fucking morons.

for a exposition of IT's fucking stupid docs and their fuckhead coders,
see:
http://xahlee.org/Periodic_dosage_di...ami_cukta.html

a cleaned up account of this post will be appended to the above
exposition.

--------

One final piece of advice here to sober up the fuckheads who are
currently offended and defiant: you want to ask yourself this question:
Can a seasoned programer, who is expert at least 2 languages, who is
also a expert at Perl and knew regex well, and who has also read the
official Python tutorial and has written at least 10 simple python
programs over a span of a month, can such a person, who have not yet
used regex in Python but now wants to use regex in Python and have just
read the doc, must he, resort to many trial and error to see exactly
what the doc is talking about?

But, can this doc be (re-)written effectively and easily so that any
programers needn't do trial'n'error post-reading?

The answer to the questions are resounding yeses, you fucking asses.

paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours.

Fuck you the standard IT morons. Excuse me for i didn't have time to
write a more coherent and detailed analysis of the stupidities of the
re doc.

Xah
xa*@xahlee.org
∑ http://xahlee.org/PageTwo_dir/more.html ☄

[Michael Hoffman]

I've had enough.

*PLONK*
--
Michael Hoffman

[Joe Smith]

Xah Lee wrote:

of motherf***ing irrevalent drivel?

I am greatly amused.
A troll impersonating Xah Lee has made xah look like a total moron.
LOL

[Roman Neuhauser]

# xa*@xahlee.org / 2005-04-12 03:25:33 -0700:

QUOTE
compile(
pattern[, flags])

Compile a regular expression pattern into a regular expression object,
which can be used for matching using its match() and search() methods,
described below.

The expression's behaviour can be modified by specifying a flags
value. Values can be any of the following variables, combined using
bitwise OR (the | operator).
UNQUOTE And what the fuck is it unclearly meant by "OR" operator with the
mother fucking bitwise jargon?
"bitwise OR (the | operator)": it doesn't speak about an "OR
operator", does it?
for a exposition of IT's fucking stupid docs and their fuckhead coders,
see:
http://xahlee.org/Periodic_dosage_di...ami_cukta.html
Interesting reading, I might send you a few of my pet peeves for
inclusion.
you want to ask yourself this question:
Can a seasoned programer, who is expert at least 2 languages, who is
also a expert at Perl and knew regex well, and have just read the doc,
must he, resort to many trial and error to see exactly what the doc is
talking about?

While I understand your frustration (I curse the same when I try to
use the Python documentation), you are spoiling your message by
the (IMNSHO well granted, but still) unhelpful profanity.

Unfortunately, the python community seems to bathe in the
misorganized half-documentation, see e. g.
http://marc.theaimsgroup.com/?l=pyth...3919606261&w=2
especially the reply that (as I read it) suggested reverse
engineering as a viable alternative to documentation.

--
How many Vietnam vets does it take to screw in a light bulb?
You don't know, man. You don't KNOW.
Cause you weren't THERE. http://bash.org/?255991

[Richie Hindle]

[Xah]

motherfucking ... fucking ... fucking ... fucking ... fuck ... fucking
fucking ... fucking ... mother fucking ... fucking ... piece of shit ...
motherfucking ... fucking ... fucking ... big asshole ... masturbation ...
Fucking morons ... fucking stupid ... fuckhead coders ... fuckheads ...
you fucking asses. paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours.

Can we paypal you a hundred dollars to leave us alone? I'll pledge $10.
Are there another nine people here who'll do the same?

--
Richie Hindle
ri****@entrian.com

[Diez B. Roggisch]

> Can we paypal you a hundred dollars to leave us alone? I'll pledge $10.

Are there another nine people here who'll do the same?

Me, me. I'm good for ten, too. The current euro-dollar exchange course makes
that the price of a normal size McDonalds Menu - so sparing that makes me
healthier both mentally and physically. Great deal.
--
Regards,

Diez B. Roggisch

[Pokerface]

Gotta say, is we let this man write the docs for us, they'll sure a
sugar be more colorful than the ones we presently have, even if h
doesn't manage to make them better.

"The [insert relation]****ing Python interpreter is usually installe
as /usr/local/bin/python on those g*dd*mn machines where it i
available; putting /usr/local/bin in your ****ing Unix shell's searc
path makes it possible to start it by typing the command python to th
shell. F***er.

--
Pokerface:: Posted from Tactical Gamer - http://www.TacticalGamer.com :

[rbt]

Xah Lee wrote:

What does a programer who wants to use regex gets out from this piece
of motherf**king irrevalent drivel?

Any resume that ever crosses my desk that includes 'Xah Lee' anywhere in
the name will be automatically trashed.

[Ivan Van Laningham]

Hi All--

Richie Hindle wrote:

[Xah]

motherfucking ... fucking ... fucking ... fucking ... fuck ... fucking
fucking ... fucking ... mother fucking ... fucking ... piece of shit ...
motherfucking ... fucking ... fucking ... big asshole ... masturbation ...
Fucking morons ... fucking stupid ... fuckhead coders ... fuckheads ...
you fucking asses.

paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours.

Can we paypal you a hundred dollars to leave us alone? I'll pledge $10.
Are there another nine people here who'll do the same?

Why don't we pay him $100 to re-write the PERL docs?

Metta,
Ivan
----------------------------------------------
Ivan Van Laningham
God N Locomotive Works
http://www.andi-holmes.com/
http://www.foretec.com/python/worksh...oceedings.html
Army Signal Corps: Cu Chi, Class of '70
Author: Teach Yourself Python in 24 Hours

[Richard Gration]

On Tue, 12 Apr 2005 04:02:20 -0700, Joe Smith wrote:

Xah Lee wrote:

of motherf***ing irrevalent drivel?

I am greatly amused.
A troll impersonating Xah Lee has made xah look like a total moron. LOL

"The fucking doc cannot be possibly fucking worsely written."

This is very Xahish though, even if it's not him.

It's right up there with "AND, the writting as usuall is fantastic
incompetent."

[Peter Hansen]

Joe Smith wrote:

Xah Lee wrote:

of motherf***ing irrevalent drivel?

I am greatly amused.
A troll impersonating Xah Lee has made xah look like a total moron.
LOL

Sorry, Joe, but why do you think this wasn't Xah?
Every detail of the post is consistent with his
recent postings.

And a secondary, but purely rhetorical, question:
how could the post have made him look like a moron
when he already looked like one?

[Fredrik Lundh]

Peter Hansen wrote:

Joe Smith wrote:

Xah Lee wrote:

of motherf***ing irrevalent drivel?

I am greatly amused.
A troll impersonating Xah Lee has made xah look like a total moron.
LOL

Sorry, Joe, but why do you think this wasn't Xah?

why do you think "Joe" and "Xah" are two different persons? ;-)

</F>

[Peter Hansen]

Fredrik Lundh wrote:

Peter Hansen wrote:

Joe Smith wrote:

Xah Lee wrote:

of motherf***ing irrevalent drivel?

I am greatly amused.
A troll impersonating Xah Lee has made xah look like a total moron.
LOL

Sorry, Joe, but why do you think this wasn't Xah?

why do you think "Joe" and "Xah" are two different persons? ;-)

Because Joe writes properly, and concisely. ;-)

[Gerrit Holl]

Ivan Van Laningham wrote:

Richie Hindle wrote:

[Xah]

motherfucking ... fucking ... fucking ... fucking ... fuck ... fucking
fucking ... fucking ... mother fucking ... fucking ... piece of shit ...
motherfucking ... fucking ... fucking ... big asshole ... masturbation ...
Fucking morons ... fucking stupid ... fuckhead coders ... fuckheads ...
you fucking asses.

paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours.

Can we paypal you a hundred dollars to leave us alone? I'll pledge $10.
Are there another nine people here who'll do the same?

Why don't we pay him $100 to re-write the PERL docs?

Interestingly, Richard Hindle's message was classified as ham by my
spambayes, whereas your message was unsure. Could it be the
second-to-last word doing it? (-;

Gerrit.

--
Weather in Twenthe, Netherlands 12/04 19:55:
13.0°C wind 2.2 m/s NNW (57 m above NAP)
--
In the councils of government, we must guard against the acquisition of
unwarranted influence, whether sought or unsought, by the
military-industrial complex. The potential for the disastrous rise of
misplaced power exists and will persist.
-Dwight David Eisenhower, January 17, 1961

[runes]

> why cannot this piece of shit writing give a single example of usage?
Actually, I can understand your frustration even if you should enhance
your vocabulary slightly. I often struggle with the Python
documnetation myself and I can't understand why a couple of examples
are so hard to give. When I laernt PHP I used the resources at php.net
exclusively, and that's because of the plenty of examples and the
newbie friendlyness. Recently I struggled with the regex module and
found the the documentation being close to worthless. I'm not a CS guy,
I may have a harder fight grasping concepts. The re documentation, like
much Python documentation seems to be written with other people than my
kind in mind. Luckily I found this regex howto:
http://www.amk.ca/python/howto/regex/ and that helped a lot. In
addition, Mr. Magnus Lie Hetland coincidentally posted a question on
this list that got answers that helped me out.
(http://groups-beta.google.com/group/...4c56ca66231d7f)

[John Machin]

On Tue, 12 Apr 2005 13:06:36 +0200, Roman Neuhauser
<ne******************************@sigpipe.cz> wrote:

Unfortunately, the python community seems to bathe in the
misorganized half-documentation, see e. g.
http://marc.theaimsgroup.com/?l=pyth...3919606261&w=2
especially the reply that (as I read it) suggested reverse
engineering as a viable alternative to documentation.

As I read the reply, it was a smart-arse attempt at humour, a *PUN* on
the word "list" (mailing list versus Python list). What I would call
"introspection" (not "reverse engineering") was then suggested.

Moreover, both of the concepts mentioned in the quoted thread
(sequence.index() and the "in" operator) are IMESHO adequately
documented.

Do you have any examples of what you regard as "misorganized
half-documentation"?

Here's a puzzle for you: Where does this list appear? What's missing?

"..., Mullender, Nagata, Ng, Oner, Oppelstrup, ..."

[John Machin]

On 12 Apr 2005 15:06:30 -0700, "runes" <ru*********@gmail.com> wrote:

Luckily I found this regex howto:
http://www.amk.ca/python/howto/regex/ and that helped a lot.
Luckily??? AMK's howto is pointed to by the 3rd paragraph of Section
4.2.1 of the documentation that you are dissing:

"""
A brief explanation of the format of regular expressions follows. For
further information and a gentler presentation, consult the Regular
Expression HOWTO, accessible from http://www.python.org/doc/howto/.
"""
In
addition, Mr. Magnus Lie Hetland coincidentally posted a question on
this list that got answers that helped me out.
(http://groups-beta.google.com/group/...4c56ca66231d7f)

The answers (paraphrased) were "read the [Xah-Lee-word]ing manual".
I'm glad that you RTFMed, and that it helped you. You should do so
more often.

[runes]

Thank you for being so friendly!

I found the Howto through Google. Somehow I didn't see that link in the
documentation.

And please do not make any assumptions about my reading of manuals.

[axel]

In comp.lang.perl.misc Xah Lee <xa*@xahlee.org> wrote:

The answer to the questions are resounding yeses, you fucking asses. paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours. Fuck you the standard IT morons. Excuse me for i didn't have time to
write a more coherent and detailed analysis of the stupidities of the
re doc.

Don't worry! Very soon, some nice men in white coats will show you
a comfortable room with soft walls in which you can write such
documentation to your hearts content.

Axel

[peufeu]

I sympathize with you and also think there should be an "add comment" in
the Python documentation website, so that users could post their code
snippets in the relevant places.

I found the Howto through Google. Somehow I didn't see that link in the
documentation.

And please do not make any assumptions about my reading of manuals.

[Steve Holden]

Xah Lee wrote:
[mountains of irrelevant drivel which normal people would boil down to
"I don't understand the doicumentation]. Even then, I'd still be on the
side of the documentation.

The answer to the questions are resounding yeses, you fucking asses.

paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours.
I will personally pay you a hundred dollars if you can find enough time
between now and this time next week - you should be able to find "a few
hours" in 168 without unduly conveniencing yourself.

The condition for winning the prize is that at least five regular
posters to c.l.py have to mail me and saythey think your version is better.

If no such document gets produced, we must assume you are too busy?
Fuck you the standard IT morons. Excuse me for i didn't have time to
write a more coherent and detailed analysis of the stupidities of the
re doc.

I have learned not to expect coherent and detailed analysis, so I have
managed to contain my disappointment.

non-standard-moronical-ly y'rs - steve
--
Steve Holden [phone] [phone]
Holden Web LLC http://www.holdenweb.com/
Python Web Programming http://pydish.holdenweb.com/

[bruno modulix]

Ivan Van Laningham wrote:

Hi All--

Richie Hindle wrote:

[Xah]

motherfucking ... fucking ... fucking ... fucking ... fuck ... fucking
fucking ... fucking ... mother fucking ... fucking ... piece of shit ...
motherfucking ... fucking ... fucking ... big asshole ... masturbation ...
Fucking morons ... fucking stupid ... fuckhead coders ... fuckheads ...
you fucking asses.

paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours.

Can we paypal you a hundred dollars to leave us alone? I'll pledge $10.
Are there another nine people here who'll do the same?

Why don't we pay him $100 to re-write the PERL docs?

+1 !

--
bruno desthuilliers
python -c "print '@'.join(['.'.join([w[::-1] for w in p.split('.')]) for
p in 'o****@xiludom.gro'.split('@')])"

[Fredrik Lundh]

"runes" <ru*********@gmail.com> wrote:

I found the Howto through Google. Somehow I didn't see that link in the
documentation.

And please do not make any assumptions about my reading of manuals.

if you were unable to find a link in the documentation you were reading, can you
perhaps suggest a better place to put that link?

</F>

[runes]

Seems like criticising the manual is som kind of heresy. So be it.

You know, the Re documentation contains many pages. Ufortunately I
didn't dwell with the first introductory paragraph, I was trying to
solve a particular problem. I'm not that used to looking for links to
external sources in the manual either. Unable? I wasn't looking for a
Howto in the manual. And frankly, 'python regex howto" in Google is
quicker way.

Of course I cannot suggest a better place for the link.

Writing technical documents always trigger the question: Who is the
audience. I accept that I may not be the primary audience. If I should
suggest anything, it would be that the examples section is expanded.

Generally: I have got my experiences with the Python Manual over the
the last 30 months Python beeing my preferred language. One of them is
that I have to look elsewhere.

[Steve Holden]

runes wrote:

Seems like criticising the manual is som kind of heresy. So be it.
Don't think so, but this being open source I suspect that Fredrik was
trying to get them improved.
You know, the Re documentation contains many pages. Ufortunately I
didn't dwell with the first introductory paragraph, I was trying to
solve a particular problem. I'm not that used to looking for links to
external sources in the manual either. Unable? I wasn't looking for a
Howto in the manual. And frankly, 'python regex howto" in Google is
quicker way.
Right, so you found what you needed, you just think it should be
referenced from the main docs. I think this is a good idea.
Of course I cannot suggest a better place for the link.
Come on, of course you can. All you need to say is whereabouts in the re
documentation it should mention the How-To.
Writing technical documents always trigger the question: Who is the
audience. I accept that I may not be the primary audience. If I should
suggest anything, it would be that the examples section is expanded.
Again, you would be a good candidate to suggest changes, since you've
just been learning that part of Python.
Generally: I have got my experiences with the Python Manual over the
the last 30 months Python beeing my preferred language. One of them is
that I have to look elsewhere.

But anyone is allowed to suggest improvements. Please don't be deterred
because you think people were trying to put you off. The documentation
contains links for suggesting improvements. That is a working channel
for criticism and suggestion (and it's how many others first got their
names in the python documentation, including myself). See

http://docs.python.org/doc/doc.html
http://docs.python.org/doc/about.html

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC http://www.holdenweb.com/
Python Web Programming http://pydish.holdenweb.com/

[Sibylle Koczian]

Pokerface schrieb:

Gotta say, is we let this man write the docs for us, they'll sure as
sugar be more colorful than the ones we presently have, even if he
doesn't manage to make them better.

"The [insert relation]****ing Python interpreter is usually installed
as /usr/local/bin/python on those g*dd*mn machines where it is
available; putting /usr/local/bin in your ****ing Unix shell's search
path makes it possible to start it by typing the command python to the
shell. F***er."

Please think of people with other native languages who can possibly read
the existing documentation without a dictionary but would certainly need
one for this.

Koczian

[rbt]

runes wrote:

Generally: I have got my experiences with the Python Manual over the
the last 30 months Python beeing my preferred language. One of them is
that I have to look elsewhere.

I've gotten great help from this newsgroup. By following these steps:

1. Read the docs at http://docs.python.org/modindex.html
2. Trail & Error testing.
3. If 2 doesn't work or if I don't fully understand how it's working, I
post a message here asking for help and clarification.

I've never been disappointed with the help I've received here. There
will always be a few wise guys who like to make snide remarks and give
arrogant answers, but it has been my experience that 95% of the people
who answer do so with a very helpful, encouraging attitude.

[John W. Kennedy]

Xah Lee wrote:

http://python.org/doc/2.4.1/lib/module-re.html
http://python.org/doc/2.4.1/lib/node114.html

---------
QUOTE
The module defines several functions, constants, and an exception. Some
of the functions are simplified versions of the full featured methods
for compiled regular expressions. Most non-trivial applications always
use the compiled form
UNQUOTE
What does a programer who wants to use regex gets out from this piece
of motherfucking irrevalent drivel?

Until now, I have regarded you as a mildly amusing moron.

But now I find you're simply illiterate.

Buh-bye.

--
John W. Kennedy
A proud member of the reality-based community.

[runes]

Steve, thank you for givig me those links. I'll go there if I manage to
structure an improvement suggestion.

And about the link to the Howto: I suppose many people don't read the
manual from a to z but with a particular problem in mind. Hence the
link could ble locateded several places, perhaps referencing to an
exact and relevant section of the Howto.

Rune

[Steve Holden]

runes wrote:

Steve, thank you for givig me those links. I'll go there if I manage to
structure an improvement suggestion.
RTFM :-) [The links came from the documentation]
And about the link to the Howto: I suppose many people don't read the
manual from a to z but with a particular problem in mind. Hence the
link could ble locateded several places, perhaps referencing to an
exact and relevant section of the Howto.

Rune

That's great. There are any number of folk on this list that will help
you provide something of lasting value to the community, and Fred Drake
is always busy enough to appreciate help! These days you can overlay
your own "virtual index" on the Internet content, simply referring to
the published pages as hypertext resources.

I have my own concerns about the documentation, but happily nothing that
stops me from finding it useful on a daily basis. [Having been a reader
for five years doesn't hurt, but by no means exhausts the learning
potential of these documents].

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC http://www.holdenweb.com/
Python Web Programming http://pydish.holdenweb.com/

[Roman Neuhauser]

# sj******@lexicon.net / 2005-04-13 08:07:06 +1000:

On Tue, 12 Apr 2005 13:06:36 +0200, Roman Neuhauser
<ne******************************@sigpipe.cz> wrote:

Unfortunately, the python community seems to bathe in the
misorganized half-documentation, see e. g.
http://marc.theaimsgroup.com/?l=pyth...3919606261&w=2
especially the reply that (as I read it) suggested reverse
engineering as a viable alternative to documentation.
As I read the reply, it was a smart-arse attempt at humour, a *PUN* on
the word "list" (mailing list versus Python list). What I would call
"introspection" (not "reverse engineering") was then suggested.

Moreover, both of the concepts mentioned in the quoted thread
(sequence.index() and the "in" operator) are IMESHO adequately
documented.

Do you have any examples of what you regard as "misorganized
half-documentation"?

Description of classes:

* What's with "Programmer's Note", is the other paragraph of the
description aimed at salesmen?

* Why isn't there a link to a description of "new-style classes"
(presumably to the "New-style Classes" essay since, as
http://www.python.org/doc/newstyle.html says, NSC aren't
integrated into the standard documentation.

* Aren't class objects instances of a builtin type? What should
I read into "<class __main__.foo at 0x81c050c>"?

distutils:

* sections 10.26 through 10.45 are completely empty

* http://docs.python.org/dist/listing-packages.html:
"when you say packages = ['foo'] in your setup script" couldn't
be any more vague I guess. Does the statement belong in the
global scope?

* http://docs.python.org/dist/listing-packages.html:
"Then you would put package_dir = {'': 'lib'} in your setup
script.": does that statement belong in the global scope, or
is it a keyword argument for setup(), which would mean that the
listing at http://docs.python.org/dist/module-distutils.core.html
cannot be trusted as complete?

lists: this is a matter of taste, but I find the split of list
description between http://docs.python.org/lib/typesseq.html and
http://docs.python.org/lib/typesseq-mutable.html (without pointers
from typesseq.html to typesseq-mutable.html where I would expect
them, such as mentioning append()) confusing.

The above applies to other mutable sequential types as well, of
course.

In general, various parts of the documentation often refer the
reader to other parts without using html anchors, what should be
concise, accurate, and complete description is a meandering essay
with vague formulations (see quotes from the distutils manual
above), etc.

There's also this thing with easy access to individual nodes:
I often miss being able to type something like
http://docs.python.org/os.path.expanduser and be redirected to
http://docs.python.org/lib/module-os.path.html#l2h-1731

Mebbe it's just me, but I've been trying python on and off for
several years now, and it's always been precisely its documentation
that has made me back out. I know I'll get to know the language
quite well some time, but it'll be through scars, and I'll have many
f*cks behind me.
Here's a puzzle for you: Where does this list appear? What's missing?

"..., Mullender, Nagata, Ng, Oner, Oppelstrup, ..."

Sorry, I don't have time for puzzles.

--
How many Vietnam vets does it take to screw in a light bulb?
You don't know, man. You don't KNOW.
Cause you weren't THERE. http://bash.org/?255991

[Fredrik Lundh]

Roman Neuhauser wrote:

Here's a puzzle for you: Where does this list appear? What's missing?

"..., Mullender, Nagata, Ng, Oner, Oppelstrup, ..."

Sorry, I don't have time for puzzles.

nor for contributing, it seems. otherwise, your name would be on that list.

</F>

[Xah Lee]

i have rewrote the Python's re module documentation.
See it here for table of content page:
http://xahlee.org/perl-python/python...module-re.html

The doc is broken into 4 sections:
* regex functions (node111.html)
* regex OOP (re-objects.html)
* matched objects (match-objects.html)
* regex syntax (re-syntax.html)

the regex syntax page i haven't edited, except the introductory first
paragraph. The other pages are completely rewritten for about 80%.

There are a couple fine points or 3 places in the original doc i can't
understand. They are noted as NOTE DOC WRITERS or NEED EXAMPLE HERE.

Xah
xa*@xahlee.org
∑ http://xahlee.org/

[Jeff Epler]

On Mon, Apr 18, 2005 at 01:40:43PM -0700, Xah Lee wrote:

i have rewrote the Python's re module documentation.
See it here for table of content page:
http://xahlee.org/perl-python/python...module-re.html

For those who have long ago consigned Mr. Lee to a killfile, it looks
like he's making an honest attempt to improve Python's documentation
here.

Mr Lee, I hope you will submit your documentation changes to python's
patch tracker on sourceforge.net. I don't fully agree with some of what
you've written (e.g., you give top billing to the use of functions like
re.search while I would encourage use of the search method on compiled
RE objetcts, and I like examples to be given as though from interactive
sessions, complete with ">>>" and "..."), but nits can always be picked
and I'm not the gatekeeper to Python's documentation.

Jeff

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.6 (GNU/Linux)

iD8DBQFCZEvDJd01MZaTXX0RAvIfAKCLytQYPG8ouo1IY5oRyz Z3V9v4TACfbvFP
abSS1nTwDly5VvtiPQ8R7gQ=
=88Em
-----END PGP SIGNATURE-----

[Xah Lee]

send your feedbacks to Steve Holden. (http://www.holdenweb.com/)
If he deem it proper, he will paypal me $100 bucks, and you can thank
him for the instigation and betterment of the Python doc.

Meanwhile, feel free to incorporate my edits into python doc.

Xah
xa*@xahlee.org
∑ http://xahlee.org/
Xah Lee wrote:

i have rewrote the Python's re module documentation.
See it here for table of content page:
http://xahlee.org/perl-python/python...module-re.html

The doc is broken into 4 sections:
* regex functions (node111.html)
* regex OOP (re-objects.html)
* matched objects (match-objects.html)
* regex syntax (re-syntax.html)

the regex syntax page i haven't edited, except the introductory first
paragraph. The other pages are completely rewritten for about 80%.

There are a couple fine points or 3 places in the original doc i can't understand. They are noted as NOTE DOC WRITERS or NEED EXAMPLE HERE.

Xah
xa*@xahlee.org
∑ http://xahlee.org/

[Bill Mill]

On 4/18/05, Jeff Epler <je****@unpythonic.net> wrote:

On Mon, Apr 18, 2005 at 01:40:43PM -0700, Xah Lee wrote:

i have rewrote the Python's re module documentation.
See it here for table of content page:
http://xahlee.org/perl-python/python...module-re.html
For those who have long ago consigned Mr. Lee to a killfile, it looks
like he's making an honest attempt to improve Python's documentation
here.

Alright, I feel like I'm feeding the trolls just by posting in this
thread. Just so that nobody else has to read the "revised" docs, no it
doesn't:

1) He didn't really change anything besides the intro page and
deleting the matching vs. searching page and the examples page. He
also put a couple of <hr> breaks into the doc.

2) notes like "NOTE TO DOC WRITERS: The doc sayz: ..." followed by the
same drum he's been beating for a while, instead of actually editing
the section to be correct.

3) adding "MAY NEED AN EXAMPLE HERE" instead of actually putting one in

Mr Lee, I hope you will submit your documentation changes to python's
patch tracker on sourceforge.net. I don't fully agree with some of what
you've written (e.g., you give top billing to the use of functions like
re.search while I would encourage use of the search method on compiled
RE objetcts, and I like examples to be given as though from interactive
sessions, complete with ">>>" and "..."), but nits can always be picked
and I'm not the gatekeeper to Python's documentation.

I'd suggest that he actually make an effort at improving the docs
before submitting them.

Peace
Bill Mill
bill.mill at gmail.com

[marco]

Re: http://xahlee.org/perl-python/python...module-re.html

Bill Mill <bi*******@gmail.com> writes:

Alright, I feel like I'm feeding the trolls just by posting in this
thread. Just so that nobody else has to read the "revised" docs, no it
doesn't:
I find that Lee's version complements the official docs quite nicely.
1) He didn't really change anything besides the intro page and
deleting the matching vs. searching page and the examples page. He
also put a couple of <hr> breaks into the doc.
Official doc:

findall(pattern, string[, flags])

Return a list of all non-overlapping matches of pattern in string. If
one or more groups are present in the pattern, return a list of groups;
this will be a list of tuples if the pattern has more than one
group. Empty matches are included in the result unless they touch the
beginning of another match. New in version 1.5.2. Changed in version
2.4: Added the optional flags argument.

Revised doc:

findall(pattern, string[, flags])

Return a list of all non-overlapping matches of pattern in string. For
example:

re.findall(r'@+', 'what @@@do @@you @think')
# returns ['@@@', '@@', '@']

If one or more groups are present in the pattern, return a list of
groups; this will be a list of tuples if the pattern has more than one
group. For example:

re.findall(r'( +)(@+)', 'what @@@do @@you @think')
# returns [(' ', '@@@'), (' ', '@@'), (' ', '@')]

Empty matches are included in the result unless they touch the
beginning of another match. For example:

re.findall(r'\b', 'what @@@do @@you @think')
# returns ['', '', '', '', '', '', '', '']

need another example here showing what is meant by "unless they touch the
beginning of another match."
Personally I find the latter much clearer (even in its incomplete state).
3) adding "MAY NEED AN EXAMPLE HERE" instead of actually putting one in

Well, you could suggest one to him.

Cheers,

--
ma***@reimeika.ca
Gunnm: Broken Angel http://amv.reimeika.ca
http://reimeika.ca/ http://photo.reimeika.ca

[Xah Lee]

I have produced my doc.
( http://xahlee.org/perl-python/python...module-re.html )

isn't there a hundred dollars due to me?

Xah
xa*@xahlee.org
∑ http://xahlee.org/PageTwo_dir/more.html
Steve Holden wrote:

Xah Lee wrote:
[mountains of irrelevant drivel which normal people would boil down to "I don't understand the doicumentation]. Even then, I'd still be on the side of the documentation.

The answer to the questions are resounding yeses, you fucking asses.
paypal me a hundred dollars and i'll rewrite the whole re doc in a few hours.
I will personally pay you a hundred dollars if you can find enough

time between now and this time next week - you should be able to find "a few hours" in 168 without unduly conveniencing yourself.

The condition for winning the prize is that at least five regular
posters to c.l.py have to mail me and saythey think your version is better.
If no such document gets produced, we must assume you are too busy?

Fuck you the standard IT morons. Excuse me for i didn't have time to write a more coherent and detailed analysis of the stupidities of the re doc.
I have learned not to expect coherent and detailed analysis, so I

have managed to contain my disappointment.

non-standard-moronical-ly y'rs - steve
--
Steve Holden [phone] [phone]
Holden Web LLC http://www.holdenweb.com/
Python Web Programming http://pydish.holdenweb.com/

[James Stroud]

On Monday 25 April 2005 11:48 am, so sayeth Xah Lee:

I have produced my doc.
( http://xahlee.org/perl-python/python...module-re.html )

isn't there a hundred dollars due to me?

Yes, we have put it in an envelop that is sitting between the dumpster and the
Dairy Queen in Dalhart, Texas.

James
--
James Stroud
UCLA-DOE Institute for Genomics and Proteomics
Box 951570
Los Angeles, CA 90095

http://www.jamesstroud.com/

[Robert Kern]

Xah Lee wrote:

I have produced my doc.
( http://xahlee.org/perl-python/python...module-re.html )

isn't there a hundred dollars due to me?

No.

[Steve Holden]

The condition for winning the prize is that at least five regular
posters to c.l.py have to mail me and saythey think your version is
better.

--
Robert Kern
rk***@ucsd.edu

"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter

[Steve Holden]

Robert Kern wrote:

Xah Lee wrote:

I have produced my doc.
( http://xahlee.org/perl-python/python...module-re.html )

isn't there a hundred dollars due to me?

No.

[Steve Holden]

The condition for winning the prize is that at least five regular
posters to c.l.py have to mail me and saythey think your version is
better.

.... and I haven't received a single email yet. I should also point out
that you originally said
paypal me a hundred dollars and i'll rewrite the whole re doc in a few
hours.

To which I replied
I will personally pay you a hundred dollars if you can find enough
time between now and this time next week - you should be able to find
"a few hours" in 168 without unduly conveniencing yourself.

That offer was made on 4/12, and it's 4/25 today, so you're six days
late. Since I don't want to be thought of as a welsher, however, the
offer still stands despite the delay. I await five emails from regular
c.l.py posters confirming that they think your version is better than
the one in the documentation.

Having read it I'm not sure *why* you believe your version is better,
but I am nevertheless impressed that you did get around to it.

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC http://www.holdenweb.com/
Python Web Programming http://pydish.holdenweb.com/

[Xah Lee]

Dear Steve Holden,

the rewrite of the regex doc is instigated by your offer.

it is published and announced here on April 18th. If you deem it
proper, paypal me. It will be to your credit and easier to incorporate
into the main doc.

Xah
xa*@xahlee.org
∑ http://xahlee.org/

[Steve Holden]

Xah Lee wrote:

Dear Steve Holden,

the rewrite of the regex doc is instigated by your offer.

it is published and announced here on April 18th.
I'll have to take your word for that.

If you deem it proper, paypal me. It will be to your credit and easier to incorporate
into the main doc.

I still await the specified five emails preferring your version to the
current documentation.

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC http://www.holdenweb.com/
Python Web Programming http://pydish.holdenweb.com/

[Claudio Grondi]

Conclusion:
---------------
I agree with Bill Mill saying
"I'd suggest that he [Xah Lee] actually make
an effort at improving the docs before
submitting them."
so I am still waiting for the final version
before deciding which docu is
better, believing, that if Xah Lee puts
more work and serious efforts into his
attempt it could result in a docu clear
superior to the existing one.
Argumentation:
---------------------
Both documentations are different approaches
and it is currently hard for me to tell which one
is really better (the proposed is better structured,
the existing provides information missing
in the proposed).
In both, the existing and the proposed
documentation I am still missing a good
introductory part showing what regular
expressions are good for and
what are the limitations, i.e. when is it better
to use self-written code instead of regexs
(including examples of both, very simple
and more complex real-world problems).
I would also miss some of the information
removed from the docs in the proposed
documentation.
From my point of view both, the existing and
the proposed documentation assume some
knowledge about regular expressions as
such, so doesn't really explain, beeing
limited to showing the syntax of usage.
In other words, I am missing the "Pythonic
approach" here.

Claudio
P.S. sorry for not including details in my comment,
but to show what I mean would require rewriting
the docs ...

"Xah Lee" <xa*@xahlee.org> schrieb im Newsbeitrag
news:11**********************@z14g2000cwz.googlegr oups.com...
Dear Steve Holden,

the rewrite of the regex doc is instigated by your offer.

it is published and announced here on April 18th. If you deem it
proper, paypal me. It will be to your credit and easier to incorporate
into the main doc.

Xah
xa*@xahlee.org
? http://xahlee.org/

[Richie Hindle]

[Xah]

I have produced my doc.
( http://xahlee.org/perl-python/python...module-re.html )

isn't there a hundred dollars due to me?
I don't have the time to write a full review of your version, but for the
record I've compared it with the original and I don't think it's a
significant improvement (apart from the title - "String Pattern Matching"
is a better title than "Regular expression operations"). (And no, I'm not
sure I could do any better, but that's not the question.)

[Xah] it is published and announced here on April 18th.
[Steve] I'll have to take your word for that.

Xah is right - I have a copy here of his message of 18th April, saying "i
have rewrote the Python's re module documentation.".

--
Richie Hindle
ri****@entrian.com

[Mike Meyer]

"Claudio Grondi" <cl************@freenet.de> writes:

From my point of view both, the existing and
the proposed documentation assume some
knowledge about regular expressions as
such, so doesn't really explain, beeing
limited to showing the syntax of usage.
It's not clear that this belongs in the Python documentation. The
smtplib documentation doesn't explain what an smtp server is, and why
you'd want to contact one. It just tells you how to go about doing
those things - in other words, the syntax of usage.

Possibly a link to a number of resources like <URL:
http://dmoz.org/Computers/Programmin...r_Expressions/ >
should be added to the documentation?
In other words, I am missing the "Pythonic
approach" here.

I don't think there's an agreed-upon "Pythonic approach" to regular
expressions. Some people swear by them. Other swear at them.

<mike
--
Mike Meyer <mw*@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.

[Brian Quinlan]

I think that there are some nice ideas in the new version e.g. "Regex
functions" is a nicer title than "Module contents", examples, caveats.

But there are some organizational problems and the actual writting is a
bit weak.

Cheers,
Brian

[Peter Hansen]

Steve Holden wrote:

I still await the specified five emails preferring your version to the
current documentation.

So, for the record Steve, how many of those emails have you
received to date? (And how many from *anyone*, not just
regulars, proclaiming Xah's version better?)

-Peter

[Ivan Van Laningham]

Hi All--

Richie Hindle wrote:

Xah is right - I have a copy here of his message of 18th April, saying "i
have rewrote the Python's re module documentation.".

Which announcement alone I take as evidence sufficient unto itself. I
shall not be reading the "rewrote" documentation.

Metta,
Ivan
----------------------------------------------
Ivan Van Laningham
God N Locomotive Works
http://www.andi-holmes.com/
http://www.foretec.com/python/worksh...oceedings.html
Army Signal Corps: Cu Chi, Class of '70
Author: Teach Yourself Python in 24 Hours

[Steve Holden]

Peter Hansen wrote:

Steve Holden wrote:

I still await the specified five emails preferring your version to the
current documentation.

So, for the record Steve, how many of those emails have you
received to date? (And how many from *anyone*, not just
regulars, proclaiming Xah's version better?)

-Peter

That would be none, Peter, as of right now.

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC http://www.holdenweb.com/
Python Web Programming http://pydish.holdenweb.com/