Re: how to write a tutorial

[A.M. Kuchling]

On Wed, 2 Feb 2005 12:22:24 -0500, 
Dan Perl <[EMAIL PROTECTED]> quoted:
> "Xah Lee" <[EMAIL PROTECTED]> wrote in message 
>> I suggest it be dropped in both places. The mentioning of this book in
>> the Perl/Python community is mostly a fawning behavior and confession
>> that the author is among "in the know". This book and its mentioning is
>> a cultish behavior among OpenSource morons.

Not to mention that the reference to the book in the regex howto is hardly 
"fawning":

  The most complete book on regular expressions is almost certainly
  Jeffrey Friedl's Mastering Regular Expressions, published by
  O'Reilly. Unfortunately, it exclusively concentrates on Perl and
  Java's flavours of regular expressions, and doesn't contain any
  Python material at all, so it won't be useful as a reference for
  programming in Python. (The first edition covered Python's
  now-obsolete regex module, which won't help you much.) Consider
  checking it out from your library.

(I like how Lee extols Python, but also says its documentation was written 
by "opensource morons".  Honestly, you couldn't pay for this much
entertainment.)

--amk


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Dan Perl]

"Xah Lee" <[EMAIL PROTECTED]> wrote in message 
news:[EMAIL PROTECTED]
> i've noticed that in Python official doc
> http://python.org/doc/lib/module-re.html
> and also How-To doc
> http://www.amk.ca/python/howto/regex/
>
> both mentions the book "Mastering Regular Expressions" by Jeffrey
> Friedl.
>
> I suggest it be dropped in both places. The mentioning of this book in
> the Perl/Python community is mostly a fawning behavior and confession
> that the author is among "in the know". This book and its mentioning is
> a cultish behavior among OpenSource morons.
>
> Most of the time, its mentioning as a reference is irrelevant. 99% uses
> of regex are the simplest uses. Spending time to read this book of
> specialization, from economy perspective, is a waste of time.
> Xah

We should drop the olympics too.  99% of  people don't practice any of those 
sports at a competitive level.  Who the hell does pole vaulting or throws a 
javelin?

Sorry, maybe I should have posted this in the "next Xah Lee post contest" 
thread.

Dan 


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Xah Lee]

i've noticed that in Python official doc
http://python.org/doc/lib/module-re.html
and also How-To doc
http://www.amk.ca/python/howto/regex/

both mentions the book "Mastering Regular Expressions" by Jeffrey
Friedl.

I suggest it be dropped in both places. The mentioning of this book in
the Perl/Python community is mostly a fawning behavior and confession
that the author is among "in the know". This book and its mentioning is
a cultish behavior among OpenSource morons.

Most of the time, its mentioning as a reference is irrelevant. 99% uses
of regex are the simplest uses. Spending time to read this book of
specialization, from economy perspective, is a waste of time.
Xah
 [EMAIL PROTECTED]
 http://xahlee.org/PageTwo_dir/more.html

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Xah Lee]

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';
fromAddr='[EMAIL PROTECTED]';
toAddr='[EMAIL PROTECTED]';
text='''Subject: test test

Hi ...
'''

server = smtplib.SMTP(smtpServer)
server.set_debuglevel(1)
server.sendmail(fromAddr, toAddr, text)
server.quit()
Xah
 [EMAIL PROTECTED]
 http://xahlee.org/PageTwo_dir/more.html

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[axel]

In comp.lang.perl.misc Xah Lee <[EMAIL PROTECTED]> 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

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Craig Ringer]

On Wed, 2005-01-26 at 09:35 +, Keith Thompson wrote:
> "Xah Lee" <[EMAIL PROTECTED]> 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.

Going by the general reaction on c.l.py, I think it'd be more accurate
if you left that at "Please stop posting".

Sorry for the cross-post, and for this "perl-python" moron who appears
to have nothing to do with either, or any knowledge of them.

--
Craig Ringer

-- 
http://mail.python.org/mailman/listinfo/python-list

when self-absorbed narcissists discover usenet [ was: how to write a tutorial ]

[Jeremy Jones]

Brian van den Broek wrote:
Terry Reedy said unto the world upon 2005-01-26 14:08:
Xah the arrogant wrote, among other things,


However, there are several errors in the above that would mislead a 
Python learner.  I advise any such to ignore Xah's writings.

Terry J. Reedy

Hi all,
here's a thought:
There isn't any doubt that these 'tutorials' are generally unwelcome 
and unhelpful. Numerous people have kindly taken the time to flag some 
of the problems. So much so that any competent google of the archives 
would quickly reveal the group consensus on their instructional merit.

I submit that continued corrections and advice of this sort are 
counter-productive. I understand the good intentions behind the 
corrections. (Indeed, my own level of Python-fu is such that it is 
possible that I might have been mislead the 'tutorials' without these 
corrections; I thus appreciate the correctors' efforts.) But, such 
corrections are troll-food and make it unlikely that the 'game' of 
posting such tutorials will soon loose its magical power to amuse the 
OP. They all but ensure that there will be more such 'tutorials' to 
correct.

I couldn't agree with you more.  *However*, when the person posting is 
self-absorbed to the extent that he doesn't realize that others exist 
and don't give a crap about their wishes or discomforts, it puts you in 
a "damned if you do, damned if you don't" situation.  I honestly think 
that we're stuck with the inane ramblings of Xah Lee regardless of 
whether we feed his trolling or ignore him.  But I do think that 
responding to him in order to preach some sense into him is futile.  He 
is right about everything and can't be swayed by the likes of us mere 
mortals.  So, ignore him, post responses for the benefit of others out 
there, entertain yourself by pointing out to yourself and others his 
folly, but don't waste your time replying back to him and trying to talk 
sense.  Like I said, we're stuck with him.

Jeremy
--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Brian van den Broek]

Terry Reedy said unto the world upon 2005-01-26 14:08:
Xah the arrogant wrote, among other things,

However, there are several errors in the above that would mislead a Python 
learner.  I advise any such to ignore Xah's writings.

Terry J. Reedy
Hi all,
here's a thought:
There isn't any doubt that these 'tutorials' are generally unwelcome 
and unhelpful. Numerous people have kindly taken the time to flag some 
of the problems. So much so that any competent google of the archives 
would quickly reveal the group consensus on their instructional merit.

I submit that continued corrections and advice of this sort are 
counter-productive. I understand the good intentions behind the 
corrections. (Indeed, my own level of Python-fu is such that it is 
possible that I might have been mislead the 'tutorials' without these 
corrections; I thus appreciate the correctors' efforts.) But, such 
corrections are troll-food and make it unlikely that the 'game' of 
posting such tutorials will soon loose its magical power to amuse the 
OP. They all but ensure that there will be more such 'tutorials' to 
correct.

Could we try to ignore them in the hopes that without the light of 
attention they will wither, meanwhile trusting the many extant reviews 
and google to do their work?

(In case it isn't obvious: none of this is intended as a criticism of 
Terry or any of the others who have been 'fighting the good fight'; I 
just think a change of strategy might be in order.)

Best to all
Brian vdB
--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Terry Reedy]

Xah the arrogant wrote, among other things,

# one can change data inside the class
x.i = 400

# one can also add new data to the class
x.j=4
print x.j

# or even override a method
x.square = 333
# (the following line will no longer work)
# print "3 squared is:", x.square(3)

# in Python, one must be careful not to
# overwrite data or methods defined in a
# class.
--

However, there are several errors in the above that would mislead a Python 
learner.  I advise any such to ignore Xah's writings.

Terry J. Reedy



-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Charlton Wilbur]

> "XL" == Xah Lee <[EMAIL PROTECTED]> 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
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Keith Thompson]

"Xah Lee" <[EMAIL PROTECTED]> 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) [EMAIL PROTECTED]  
San Diego Supercomputer Center <*>  
We must do something.  This is something.  Therefore, we must do this.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Xah Lee]

in my previous two messages, i've criticized the inanity of vast
majority of language documentations and tutorials in the industry. I've
used the Python tutorial's chapter on class as an example. I've
indicated that proper tutorial should be simple, covering just common
cases, be self-contained, and be example based. Documenting or covering
the language's functionalities manifest as it is. An exemplary case of
this style i've indicated is Stephen Wolfram Mathematica documentation.

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.

---
From: [EMAIL PROTECTED]
Subject:[perl-python] 20050124 classes and objects
Date:   January 24, 2005 6:44:14 AM PST
To:   [EMAIL PROTECTED]

# -*- coding: utf-8 -*-
# Python

# in Python, one can define a boxed set
# of data and functions, which are
# traditionally known as "class".

# in the following, we define a set of data
# and functions as a class, and name it xxx
©class xxx:
© "a class extempore! (^_^)"
© i=1 # i'm a piece of data
© def okaydokey(self): return "okaydokey"
© def square(self,a): return a**a

# in the following,
# we create an object, of the class xxx.
# also known as "instantiate a class".
x = xxx()

# data or functions defined in a class
# are called the class's attributes or
# methods.
# to use them, append a dot and
# their name after the object's name.
print 'value of attribute i is:', x.i
print "3 squared is:", x.square(3)
print "okaydokey called:", x.okaydokey()

# in the definition of function inside a
# class, the first parameter "self" is
# necessary. (you'll know why when you need to)

# the first line in the class definition
# is the class's documentation. It can
# be accessed thru the __doc__
# attribute.
print "xxx's doc string is:", x.__doc__

# one can change data inside the class
x.i = 400

# one can also add new data to the class
x.j=4
print x.j

# or even override a method
x.square = 333
# (the following line will no longer work)
# print "3 squared is:", x.square(3)

# in Python, one must be careful not to
# overwrite data or methods defined in a
# class.

#---

# for a obfuscated treatment with a few
# extra info, see
# http://python.org/doc/2.3.4/tut/node11.html

# in Python terminal, type help() then
# topic CLASSES to read about existing
# datatypes as classes, and classes in
# Python

# try to write a class with one data of
# integer and two functions, one
# increases it by 1, one decreases it by
# 1.  note: inside a class definition,
# to refer to data inside itself use
# self. e.g. self.i
Xah
  [EMAIL PROTECTED]
  http://xahlee.org/PageTwo_dir/more.html

--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[TZOTZIOY]

On Sun, 23 Jan 2005 12:28:12 -0500, rumours say that Hans Nowak
<[EMAIL PROTECTED]> might have written:

>Xah Lee wrote:
>> 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.
>
>So I can just take a copy of the tutorial to the bathroom next time. 
>Thanks for the tip, man!

The first day I (got) laid my eyes on the Python tutorial, I knew the
days of "Pyboy", "Pythouse" and "Python 10" were over.  I'm glad that
finally others, too, really grok the "joy of Python programming".

PS I just *love* the Classes chapter centerfold.  All-time classic.
-- 
TZOTZIOY, I speak England very best.
"Be strict when sending and tolerant when receiving." (from RFC1958)
I really should keep that in mind when talking with people, actually...
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Jonathan Burd]

Xah Lee wrote:
adding to my previosu comment...

*plonk*
--
"Women should come with documentation." - Dave
--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[alex23]

Daniel Bickett wrote:
> You guys are just begging for a YHBT ;-)

Point taken :) I've noticed very few people even acknowledge his posts
at all; I'll follow the group lead and do the same.

Cheers!

- alex23

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[alex23]

Daniel Bickett wrote:
> Chris Mattern wrote:
> > 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.
>
> It's painfully obvious that it is all for the sole purpose of
negative
> attention.
> You guys are just begging for a YHBT ;-)
> 
> Daniel Bickett

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Daniel Bickett]

Daniel Bickett wrote:
> [snip]
> You guys are just begging for a YHBT ;-)

I apologize, that should have been "we" -- I was criticizing him too.

no-one-wants-to-be-a-hypocrite-ly y'rs,
Daniel Bickett
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Daniel Bickett]

Chris Mattern wrote:
> 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.

It's painfully obvious that it is all for the sole purpose of negative
attention.
You guys are just begging for a YHBT ;-)

Daniel Bickett
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Chris Mattern]

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?"
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[alex23]

> 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

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Daniel Bickett]

Lucas Raab wrote:
> Daniel Bickett wrote:
> >>Most texts in computing are written by authors to defend and showcase
> >>their existence against their peers.
> >
> >
> > When you aren't busy `showcasing' your ignorance, this is *all* i see
> > in everything you write.
> 
> 
> 
> Um, maybe that was his point...

It was a critical comment -- meant to be derogatory. I pointed out
that that is exactly what he does.

Daniel Bickett
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Lucas Raab]

Daniel Bickett wrote:
Most texts in computing are written by authors to defend and showcase
their existence against their peers.

When you aren't busy `showcasing' your ignorance, this is *all* i see
in everything you write.

Um, maybe that was his point...
--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Hans Nowak]

Xah Lee wrote:
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.
So I can just take a copy of the tutorial to the bathroom next time. 
Thanks for the tip, man!

--
Hans Nowak
http://zephyrfalcon.org/
--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Daniel Bickett]

> Most texts in computing are written by authors to defend and showcase
> their existence against their peers.

When you aren't busy `showcasing' your ignorance, this is *all* i see
in everything you write.

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

You couldn't be farther from the truth. To preface a document by
illustrating it's similarities to other languages is to better prepare
a reader who may have experience in those languages. As for the
snippet of history, few people desire to live life as cynical as you
do, and one would hope even fewer take their own opinion and assume it
applies to their peers, as you have just done.

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

You of all people are the least qualified to say this, as you are the
most guilty of such a crime.

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

Then please be so kind as to give us all a pleasant surprise, and take
the place of the productive reformer rather than the angsty
criticizer. Your vision as to the errors in the tutorial is *clearly*
less clouded than ours, so only *you* are in the position to write the
proper replacement.

Daniel Bickett
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Dan Perl]

"Xah Lee" <[EMAIL PROTECTED]> wrote in message 
news:[EMAIL PROTECTED]
> 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? 


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[CBFalconer]

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


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Xah Lee]

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
 [EMAIL PROTECTED]
 http://xahlee.org/PageTwo_dir/more.html

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Jeffrey Cunningham]

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
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Jeremy Bowers]

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
> 
> Here are some quick critique:

You don't have the respect points for anyone to give a damn. Step one
would be demonstrating that you understand the language enough to have a
valid opinion, which we're all still waiting on.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[M Jared Finder]

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
--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[CBFalconer]

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


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Frank Buss]

drewc <[EMAIL PROTECTED]> 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ß, [EMAIL PROTECTED]
http://www.frank-buss.de, http://www.it4-systems.de
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[John Hunter]

> "Xah" == Xah Lee <[EMAIL PROTECTED]> writes:

Xah> at places often a whole paragraph on some so called computer
Xah> science jargons should be deleted. They are there more to
Xah> showcase inane technicality than do help the
Xah> reader. (related, many passages with jargons should be
Xah> rewritten sans inane jargon. e.g. mutable object.)

The concept of mutable objects is extremely important in python, and
understanding is the key to answering two recurring newbie questions

  * Why can't lists or dictionaries be keys to dictionaries?

  * Why does using a list as a default value for a keyword argument in
a function definition often lead to unexpected results?

So it is definitely appropriate material in a tutorial.  

As for jargon, it is hard to argue that "object" is inane jargon in
python.  In fact, the base class for new-styled classes is indeed
"object", and if you want to write one of these classes yourself, you
need to do 'class MyClass(object)'.  So object is not inane jargon in
an object oriented programming language.  You still with me?

OK, now on to mutable.  mutable means changeable, albeit it's a little
more of an obscure word than changeable, but it does roll off the
tongue a bit more easily.  Perhaps 'changeable object' would be more
accessible to some readers, but it doesn't flow as well.  So the
python tutorial should perhaps define mutable when it introduces it.
Which it does somewhat implicitly; the first time mutable is mentioned in the
docs, in the context of strings

  Unlike strings, which are immutable, it is possible to change
  individual elements of a list:


And now for my last musing on a new topic "How to write a critique":
It is much more constructive to suggest new text for documentation
than to brand it inane.

JDH
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[drewc]

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
 [EMAIL PROTECTED]
 http://xahlee.org/PageTwo_dir/more.html
--
http://mail.python.org/mailman/listinfo/python-list

Re: how to write a tutorial

[Diez B. Roggisch]

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
-- 
http://mail.python.org/mailman/listinfo/python-list

how to write a tutorial

[Xah Lee]

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
 [EMAIL PROTECTED]
 http://xahlee.org/PageTwo_dir/more.html

-- 
http://mail.python.org/mailman/listinfo/python-list