i've started to read python tutorial recently.
http://python.org/doc/2.3.4/tut/tut.html
Here are some quick critique:
quick example:
If the input string is too long, they don't truncate it, but return it
unchanged; this will mess up your column lay-out but that's usually
better than the alternative, which would be lying about a value. (If
you really want truncation you can always add a slice operation, as in
"x.ljust( n)[:n]".
better:
If the input string is too long, they don't truncate it, but return it
unchanged;
-----------------
delete: Reverse quotes (``) are equivalent to repr(), but their use is
discouraged.
-----------------
similarly, many places mentioning uncritical info such as warning or
reference to other languages should be deleted.
the tutorial should be simple, concise, to the point, stand along.
Perhaps 1/5th length of the tutorial should be deleted for better.
Follow the above principles.
at places often a whole paragraph on some so called computer science
jargons should be deleted. They are there more to showcase inane
technicality than do help the reader. (related, many passages with
jargons should be rewritten sans inane jargon. e.g. mutable object.)
one easy way to understand these principles is to compare perl's
documentation or unix man pages to Python's. The formers are often
irrelevant, rambling on, not stand-along (it is written such that it
unnecessarily requires the reader to be knowledgable of lots of other
things). Python docs are much better, but like many computer language
manuals, also suffers from verbiage of tech jargons. (these jargons or
passages about them are usually there to please the authors
themselves).
A exemplary writing in this direction is the Mathematica manual by
Stephen Wolfram. Any intelligent layman sans computer science degree
can read it straightforwardly, and learn unhindered a language that is
tantamount to features of lisp languages. Such documentation is not
difficult to write at all. (contrary to the lot of "computer
scientists" or IT pundits morons.) All it take is some simple
principles outlined above.
Xah
···@xahlee.org
http://xahlee.org/PageTwo_dir/more.html
Xah Lee wrote:
> i've started to read python tutorial recently.
> http://python.org/doc/2.3.4/tut/tut.html
What does this have to do with Perl, Lisp, Scheme, or C?
-- MJF
Xah Lee wrote:
> i've started to read python tutorial recently.
> http://python.org/doc/2.3.4/tut/tut.html
Finally! It was about time...
> Here are some quick critique:
Given that you seem to be totally inert to critique yourself - e.g. your
continued posting of useless language comparison, and the plethorea of
posts requesting to stop that and limit yourself to your mailing list - I
doubt you'll get much attention for that.
--
Regards,
Diez B. Roggisch
You should not be giving such advice! (and the crosspost ... WTF?).
I've been trying to follow along with your perl/python yahoo group, but
your posts are terrible.
Perhaps you should provide the output of the code you post. Then i'd
actually know what i'm trying to achieve. As it is i have to cut/paste
your code into an interpreter just to figure out what it does.
What does this have to do with Lisp? (i'm in c.l.l).
drewc
Xah Lee wrote:
> i've started to read python tutorial recently.
> http://python.org/doc/2.3.4/tut/tut.html
>
> Here are some quick critique:
>
> quick example:
> If the input string is too long, they don't truncate it, but return it
> unchanged; this will mess up your column lay-out but that's usually
> better than the alternative, which would be lying about a value. (If
> you really want truncation you can always add a slice operation, as in
> "x.ljust( n)[:n]".
>
> better:
> If the input string is too long, they don't truncate it, but return it
> unchanged;
> -----------------
> delete: Reverse quotes (``) are equivalent to repr(), but their use is
> discouraged.
> -----------------
> similarly, many places mentioning uncritical info such as warning or
> reference to other languages should be deleted.
>
> the tutorial should be simple, concise, to the point, stand along.
> Perhaps 1/5th length of the tutorial should be deleted for better.
> Follow the above principles.
>
> at places often a whole paragraph on some so called computer science
> jargons should be deleted. They are there more to showcase inane
> technicality than do help the reader. (related, many passages with
> jargons should be rewritten sans inane jargon. e.g. mutable object.)
>
> one easy way to understand these principles is to compare perl's
> documentation or unix man pages to Python's. The formers are often
> irrelevant, rambling on, not stand-along (it is written such that it
> unnecessarily requires the reader to be knowledgable of lots of other
> things). Python docs are much better, but like many computer language
> manuals, also suffers from verbiage of tech jargons. (these jargons or
> passages about them are usually there to please the authors
> themselves).
>
> A exemplary writing in this direction is the Mathematica manual by
> Stephen Wolfram. Any intelligent layman sans computer science degree
> can read it straightforwardly, and learn unhindered a language that is
> tantamount to features of lisp languages. Such documentation is not
> difficult to write at all. (contrary to the lot of "computer
> scientists" or IT pundits morons.) All it take is some simple
> principles outlined above.
> Xah
> ···@xahlee.org
> http://xahlee.org/PageTwo_dir/more.html
>
drewc <·····@rift.com> wrote:
> What does this have to do with Lisp? (i'm in c.l.l).
he is a troll, but one who confess this fact:
http://www.xahlee.org/Netiquette_dir/troll.html
--
Frank Bu�, ··@frank-buss.de
http://www.frank-buss.de, http://www.it4-systems.de
Xah Lee wrote:
>
> i've started to read python tutorial recently.
> http://python.org/doc/2.3.4/tut/tut.html
>
> Here are some quick critique:
This has absolutely nothing to do with c.l.c, nor most of the
cross-posted groups. F'ups set. Why did you do such a foul
cross-posting in the first place.
--
"If you want to post a followup via groups.google.com, don't use
the broken "Reply" link at the bottom of the article. Click on
"show options" at the top of the article, then click on the
"Reply" at the bottom of the article headers." - Keith Thompson
On Fri, 21 Jan 2005 03:08:50 -0800, Xah Lee wrote:
> i've started to read python tutorial recently.
> http://python.org/doc/2.3.4/tut/tut.html
>
(snip rest of misleading filler)
>
> http://xahlee.org/PageTwo_dir/more.html
The first line is solipsistic (..like..'so what?'). But I think its all
misleading. The real purpose of his cross-post is to get people to visit
his website, ooh-and-ahh at his unique and daring Bush-bashing at the top,
and finally admire (along with Xah himself) the pictures he takes of
himself.
Vanity, vanity, all is vanity...
The only remaining question is 'why does he restrict his cross-posting to
this particular collection of groups?' I don't have an answer to that one.
[incidentally, I'm still cracking up over k.t. and the soldier...]
--Jeff
adding to my previosu comment...
In the Python tutorial:
http://python.org/doc/2.3.4/tut/node11.html
the beginning two paragraphs should be deleted. Nobody gives a shit
except a few smug academicians where the author wrote it for pleasing
himself. For 99% of readers, it is incomprehensible and irrelevant.
the first paragraph of 9.1 "A Word About Terminology" is epitome of
masturbation. The entire 9.1 is not necessary.
Large part of 9.2 "Python Scopes and Name Spaces" is again
masturbatory.
--
Most texts in computing are written by authors to defend and showcase
their existence against their peers. In a tutorial, nobody cares how
the language compared to x y and z, or what technicality is it all
about, or some humorous snippet of history only funny to the author
himself.
Particularly for texts in a tutorial context, you want to write it as
simple as possible covering the most useful basic functionalities and
concepts, and self-contained. Not showcasing your knowledge of history
of languages or your linguistic lineage byways.
For example this chapter 9 on Objects, it is not difficult to write it
without making a show of lingoes. One simply write what is of Python,
without thinking about relation to xyz languages or the "computer
science" establishment and their ways of thinkings of namespaces and
scopes and dynamic and statics and inheritances ... fucking bags of
shit.
Also, in the computing industry, documentations and tutorials often
lacks examples. Especially important in tutorials. Be fewer in words,
more in examples. (for example, unix man pages are full of arcane
abstract syntax specifications and inner-working technicalities while
most don't contain a single example of usage that is much needed.)
also, this does not mean beginning to write for dummies as the highly
successful series of "xyz for Dummies" books. These are successful
because the corpus of textbook writers are all inclined and habituated
to chalk up to jargons and intellectualization on the accounts of their
own esteem and careers. Dummy books are moronic because they assumed
the general readers are morons.
PS Another illustrative case is the official Java Tutorial. Python
tutorial is to the point on the whole. The Java Tutorial is completely
asinine. Chalking up to rocket sciences every chance with unhelpful and
misleading drivel.
Xah
···@xahlee.org
http://xahlee.org/PageTwo_dir/more.html
"Xah Lee" <···@xahlee.org> wrote in message
····························@c13g2000cwb.googlegroups.com...
> the beginning two paragraphs should be deleted. Nobody gives a shit
> except a few smug academicians where the author wrote it for pleasing
> himself. For 99% of readers, it is incomprehensible and irrelevant.
>
> the first paragraph of 9.1 "A Word About Terminology" is epitome of
> masturbation. The entire 9.1 is not necessary.
>
> Large part of 9.2 "Python Scopes and Name Spaces" is again
> masturbatory.
This is a perfect description for your own postings. Why don't you follow
your own advice?
Xah Lee wrote:
>
... snip ...
>
> the first paragraph of 9.1 "A Word About Terminology" is epitome
> of masturbation. The entire 9.1 is not necessary.
>
> Large part of 9.2 "Python Scopes and Name Spaces" is again
> masturbatory.
PLONK for excessive OT crossposting and trolling.
--
"If you want to post a followup via groups.google.com, don't use
the broken "Reply" link at the bottom of the article. Click on
"show options" at the top of the article, then click on the
"Reply" at the bottom of the article headers." - Keith Thompson
> the first paragraph of 9.1 "A Word About Terminology" is
> epitome of masturbation.
I'm tempted to concede this point to you given the sheer overwhelming
testament to onanism that is your website but this is just nonsense.
Defining terms is *always* necessary, it ensures that participants in
whatever dialogue are at least partially using the terms with the same
intent
> For 99% of readers, it is incomprehensible and irrelevant.
You're not 99% of the readers, so I find that remark difficult to
swallow. Having read your comments on women, the whole idea that you
have a superior insight into would-be python coders is just obscenely
ludicrous.
- alex23
alex23 wrote:
> Having read your comments on women,
I hadn't looked at that part of his site until now. I can only say:
gah. Haven't seen something like that since Dave Sim's infamous
"Tangent" essay.
--
Christopher Mattern
"Which one you figure tracked us?"
"The ugly one, sir."
"...Could you be more specific?"
"Xah Lee" <···@xahlee.org> writes:
[snip]
> Following is a tutorial on Python's classes.
[snip]
Please stop posting this to comp.lang.c. I'm sure the folks in most
of the other newsgroup aren't interested either -- or if they are,
they can find it in comp.lang.python.
Followups redirected.
--
Keith Thompson (The_Other_Keith) ·····@mib.org <http://www.ghoti.net/~kst>
San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
We must do something. This is something. Therefore, we must do this.
>>>>> "XL" == Xah Lee <···@xahlee.org> writes:
XL> I've used the Python tutorial's chapter on class as
XL> an example. I've indicated that proper tutorial should be
XL> simple, covering just common cases, be self-contained, and be
XL> example based.
"Correct" is not in your list of criteria. Big surprise, that.
Followups set appropriately.
Charlton
--
cwilbur at chromatico dot net
cwilbur at mac dot com
In comp.lang.perl.misc Xah Lee <···@xahlee.org> wrote:
> Following is a tutorial on Python's classes. It is part of a
> a-Python-a-day mailing list. As an example, it shows what i mean by
> covering the language's functionalities as is, without needing to chalk
> up to rocket sciences. If expanded slightly and edited, it can supplant
> sections 9.0 to 9.4 of the Python tutorial. Languages Tutorials should
> follow this style.
It is crap, not a tutorial, but just an aide-memoire for someone who
presumably knows the stuff anyway.
And keep it where it belongs please.
Axel
in the doc for re module
http://python.org/doc/lib/module-re.html
4.2.2 on Matching vs Searching
http://python.org/doc/lib/matching-searching.html
Its mentioning of Perl is irrelevant, since the majority reading that
page will not have expertise with Perl regex. The whole section should
be deleted, because it only adds confusion. (later section 4.2.3 on
search and match methods plainly indicated their difference.)
(the mentioning of perl there is a combination of author masterbation,
ass kissing, and Python fanaticism. All together innocently done as
ignorance of standard authors.)
A detailed explanation of their difference or the mentioning of Perl
should be in FAQ or such material.
in section 4.2.6 Examples, there needs to be more and simple examples.
(e.g. http://xahlee.org/perl-python/regex.html.) The beginning large
section about some scaf() should be deleted for the same reason as the
Perl above.
-------------------------
in section 11.12.2 SMTP Examples
http://python.org/doc/lib/SMTP-example.html
the example given is turgid.
In a tutorial or documentation, you want to give example as short and
to the point as possible. In this case, it is illustrating how to use
smtplib, not how to preamble with nice command line interface. A better
example would be like:
import smtplib
smtpServer='smtp.yourdomain.com';
·············@xahlee.org';
···········@xahlee.org';
text='''Subject: test test
Hi ...
'''
server = smtplib.SMTP(smtpServer)
server.set_debuglevel(1)
server.sendmail(fromAddr, toAddr, text)
server.quit()
Xah
···@xahlee.org
http://xahlee.org/PageTwo_dir/more.html