[docs] Python Language Reference

Christopher Howard christopher.howard at frigidcode.com
Sat Jan 14 13:05:35 CET 2012


On 01/14/2012 02:49 AM, Senthil Kumaran wrote:
> 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

Yeah, just forget that I ever sent that e-mail. When I initially
approached this document, I thought it was trying to function as a
language standard. After getting into it (I'm about half way through
now) I see that you would have to rewrite about half the document to
approach the precision of a language standard. The terminology is very
loose, and distinctions between language and implementation are
frequently blurred.

-- 
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/20120114/fa2bc4bd/attachment.pgp>


More information about the docs mailing list