[Doc-SIG] Tutorial nits

Paul Prescod paul@prescod.net
Wed, 19 May 1999 07:28:21 -0500


Exhibit 1:
> Like in C, the equal sign (‘=’) is used to assign a value to a 
> variable. The value of an assignment is not written:
> >>> width = 20
> >>> height = 5*9
> >>> width * height
> 900

Exhibit 2:
> This is a rather long string containing\n\
> several lines of text just as you would do in C.\n\

Exhibit 3:
> Strings can be subscripted (indexed); like in C, the first 
> character of a string has subscript (index) 0.

I think that these references to C is probably not appropriate now that
Python's target user base has expanded beyond C programmers. The tutorial
rather implies that you really should know C before attempting Python.

Exhibit 4:
> Like in Icon, substrings can be specified with the
> slice notation: two indices separated by a colon.

Not enough people know Icon to risk the same "am I supposed to know that"
reaction.

How about "As in many languages, ..."

For the same reasons I would like to change these two paragraphs:

"If you ever wrote a large shell script, you probably know this feeling:
you’d love to add yet another feature, but it’s already so slow, and so
big, and so complicated; or the feature involves a system call or other
function that is only accessible from C . . . Usually the problem at hand
isn’t serious enough to warrant rewriting the script in C; perhaps the
problem requires variable-length strings or other data types (like sorted
lists of file names) that are easy in the shell but lots of work to
implement in C, or perhaps you’re not sufficiently familiar with C."

"Another situation: perhaps you have to work with several C libraries, and
the usual C write/compile/test/re-compile cycle is too slow. You need to
develop software more quickly. Possibly perhaps you’ve written a program
that could use an extension language, and you don’t want to design a
language, write and debug an interpreter for it, then tie it into your
application."

Actually, at this point in history we probably don't need to justify the
concept of a scripting language so we could probably just cut them out. It
would be more appropriate, today, to address the Perl
refugee^H^H^H^H^H^H^H programmer.

I presume that whoever maintains the tutorial is as busy as anyone else.
How would I go about helping make changes to it? Should I submit diffs or
suggest changes for discussion and then submit diffs? Or just submit
textual suggestions?

-- 
 Paul Prescod  - ISOGEN Consulting Engineer speaking for only himself
 http://itrc.uwaterloo.ca/~papresco

"It's only a movie. People should get a life." 
 - George Lucas (http://www.nypost.com/news/9025.htm)