[perl-python] Python documentation moronicities (continued)

[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?

**** 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

 

[bruno modulix]

Hi All--

[Xah]

motherfucking ... fucking ... fucking ... fucking ... **** ... 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 !

 

[Fredrik Lundh]

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]

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

 

[Sibylle Koczian]

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]

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]

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.

 

[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]

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

 

[Roman Neuhauser]

# (e-mail address removed) / 2005-04-13 08:07:06 +1000:

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.

 

[Fredrik Lundh]

Roman Neuhauser wrote:

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_re-write/lib/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
(e-mail address removed)
∑ http://xahlee.org/

 

[Jeff Epler]

i have rewrote the Python's re module documentation.
See it here for table of content page:
http://xahlee.org/perl-python/python_re-write/lib/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)

iD8DBQFCZEvDJd01MZaTXX0RAvIfAKCLytQYPG8ouo1IY5oRyzZ3V9v4TACfbvFP
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
(e-mail address removed)
∑ http://xahlee.org/

 

[Bill Mill]

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_re-write/lib/module-re.html

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,

 

[Xah Lee]

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

isn't there a hundred dollars due to me?

Xah
(e-mail address removed)
∑ http://xahlee.org/PageTwo_dir/more.html

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?

**** 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

 

[James Stroud]

I have produced my doc.
( http://xahlee.org/perl-python/python_re-write/lib/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]

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

isn't there a hundred dollars due to me?

No.

[Steve Holden]
--
Robert Kern
(e-mail address removed)

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