[docs] Python Language Reference

[Senthil Kumaran]

On Fri, Jan 13, 2012 at 02:54:18AM -0900, Christopher Howard wrote:

> regarding mandatory vs. implementation-dependent requirements. ("Must
> vs. "should", and such like.) E.g., in section 2.1.5, a paragraph states:

I think, that would make it something like an RFC or standard. As you
noticed, enough foreword has been given as how to look at the language
reference.

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

If someone really wants to confuse then yes, but other wise, the
person would simply send \n. And I believe the person would look at
docs and libraries and would be a user of python before reading that
the reference documentation. In that case, would it still confuse?

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

Isn't this deviating from what the intention of the statement is?
If it were an example in datatime module document, then it would
probably may been a change request.

> 
> Anyway, there are my two cents.
> 

Thanks for the suggestions.  At the moment -1 from me. ( You could
refer to PEPs on voting details :)) 

Thanks,
Senthil