[docs] Python Language Reference

[Christopher Howard]

Hi. (I'm not subscribed to this mailing list, so you will need to CC me
any replies that you wish me to receive.) I recently started working
through the The Python Language Reference (3.2). I don't know whether or
not the language reference is something that can be edited, but if so I
had two suggestions:

1. The language reference indicates that it is intentionally less formal
than typical language references; nevertheless, there should be a
section towards the beginning of the reference dealing with language
regarding mandatory vs. implementation-dependent requirements. ("Must
vs. "should", and such like.) E.g., in section 2.1.5, a paragraph states:

"When embedding Python, source code strings should be passed to Python
APIs using the standard C conventions for newline characters (the \n
character, representing ASCII LF, is the line terminator)."

Most people who have read, say, a C standards document will immediately
wonder whether "should" means "must" or "is recommended".

2. The is an example given (also in section 2.1.5) illustrating the use
of the backslash character for explicit line joining:


if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
        return 1

However, everyone knows that not all months have 31 days. To avoid
making the language reference look silly, it might be better to
substitute this with a different example.

Anyway, there are my two cents.

-- 
frigidcode.com
theologia.indicium.us

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 554 bytes
Desc: OpenPGP digital signature
URL: <http://mail.python.org/pipermail/docs/attachments/20120113/c3fe045f/attachment.pgp>