Questions about LISP and Python.

[Ian Kelly]

On Tue, Dec 6, 2011 at 6:13 AM, Rick Johnson
<rantingrickjohnson at gmail.com> wrote:
> I would say Mr. Lee does in fact find some usefulness of Python (as do
> i) HOWEVER he also laments the asinities that plague the language, the
> documentation, and especially, this community.
>
> Anyone who would take the time to write *articulate* suggestions for
> grave deficiencies in the Python documentation must care. Mr. Lee, has
> documented many of the atrocities of the doc in his fine website. I
> just recently finished reading a few more of his fine suggestions and
> I especially enjoyed the "os.path.split" rant. PRICELESS!

I would be much more impressed if instead of simply whining about the
documentation, Xah Lee would come off his high horse and actually
submit a patch to fix it.  That would be the mark of somebody who
actually cares about the quality of the documentation.  He seems to be
suggesting that the problems he points out are just examples of
systemic problems that make the whole incomprehensible, yet most of
what he specifically identifies seems to be just copy editing for
conciseness.

What I find hilarious, though, is that Xah Lee has written his own
Python documentation, and it's equally bad, if not worse.  Just for
example, I'll critique an arbitrary section.  Let's talk about for
loops.

http://xahlee.org/perl-python/for_statement.html

"""This is a example of “for” statement..

a = range(1,51) # creates a list
for x in a:
    if x % 2 == 0:
        print x, 'even'
"""

What is a "for" statement?  What does it do?  If I'm new to
programming, I have no idea, and the above hasn't even attempted to
introduce the concept, so that example is meaningless to me.
Fortunately, he starts to explain it.

"""In the above, the percent “%” symbol calculates the remainder of
division. The range(m,n) function gives a list from m to n-1"""

Wait, I thought this section was about "for" statements.  Why is the
author suddenly (and poorly) explaining modulo division and the range
function?  These things belong in their own section.

"""Note that in this example, “for” goes over a list."""

Oh, okay, the author finally is telling us what "for" does.  It is
used to "go over" lists, apparently so that we can get to the other
side.  Note that this documentation still has not said anything at all
about "looping" or "repeating" or "iterating" that might help me
understand what that means.  Instead we have "goes over".  If I did
not already understand what a "for" statement does, this would not
make it any clearer.  It reminds me of when I was 6 or so and I asked
my mother what division was, and she told me that it's how many times
a number "goes into" another number.  Even though I was mathematically
inclined, I didn't understand that all, because I had no idea what it
meant for one number to enter another.

"""Each time making “x” the value of the element."""

Okay, apparently there's an element involved, and "x" is going to be
its value.  I really don't think I need to say anything more about
this "sentence".

"""Python also supports “break” and “continue” to exit the loop.
“break” will exit the loop. “continue” will skip code and start the
next iteration."""

Finally the author breaks down and uses the words "loop" and
"iteration", so if the reader actually makes it this far, then they
might actually start to piece together everything that came before
this.

I also want to highlight his introduction of list comprehensions:

http://xahlee.org/perl-python/list_comprehension.html

"""This construct uses a irregular syntax (called “list
comprehension”) to generate a expression normally built by nested
loops. This construct has acquired a incomprehensible name “list
comprehension” in computing industry and academia.
...
Remember, this jargonized “list comprehension” is nothing more than a
irregular syntax for building a list from loops. Its purpose is purely
of syntactical convenience. Advanced languages such as functional
languages often have this power without the syntax irregularity. (For
example, Mathematica's Table function.)
"""

What was that again about "author masturbation" polluting the
documentation, Xah?

On Tue, Dec 6, 2011 at 6:13 AM, Rick Johnson
<rantingrickjohnson at gmail.com> wrote:
> Listen, python is a great language, but not a perfect one. You people
> seem to get all upset at even the slightest suggestion that Python is
> not perfect. The haughty arrogance i see day after day around me just
> makes me sick. Grow up! You are not perfect and neither is Python...
> or Guido for that matter.

I don't think Python, Guido, or myself are perfect.  I think that most
people here don't think that either.

Python has its warts.  For example, I don't like generator syntax.  To
be a generator, a function only has to have a "yield" statement
somewhere in its body.  This is not good self-documenting code.  A
generator should be clearly marked as such somewhere at the top of the
definition.  I also think that tacking coroutines onto generators was
an ugly hack.  Generators and coroutines are conceptually very
different; let's keep them that way.  And I strongly dislike super();
you may have seen me posting previously on the subject.

You need to understand that people don't reject your suggestions
because they're resistant to change.  They reject your suggestions
because you make sweeping pronouncements about the way things should
be and then expect that everybody will automatically agree with you
because you're so obviously right.  In this, you seem to think that
people should regard you in the way that you imagine they already
regard Guido.  In the end, you come across as a clown and an
egomaniac.