Home Original page

how to write a tutorial

Xah Lee xah at xahlee.org
Wed Feb 2 09:29:00 EST 2005 
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='xah at xahlee.org';
toAddr='xah at xahlee.org';
text='''Subject: test test

Hi ...
'''

server = smtplib.SMTP(smtpServer)
server.set_debuglevel(1)
server.sendmail(fromAddr, toAddr, text)
server.quit()
Xah
 xah at xahlee.org
 http://xahlee.org/PageTwo_dir/more.html
More information about the Python-list mailing list