[Python-Dev] [Python-checkins] r88032 - in python/branches/py3k/Doc: c-api/code.rst howto/logging-cookbook.rst howto/logging.rst library/2to3.rst library/importlib.rst library/stdtypes.rst library/sys.rst reference/expressions.rst reference/simple_stmts.rst whatsnew/2.0.rst whatsnew/2.1.rst whatsnew/2.2.rst whatsnew/2.4.rst whatsnew/3.0.rst

[Georg Brandl]

Am 15.01.2011 19:58, schrieb Terry Reedy:
> On 1/15/2011 12:03 PM, georg.brandl wrote:
> 
>> Fix a few doc errors, mostly undefined keywords.
> 
> I am not sure what you mean by 'undefined keyword', but
> 
>> -        integer. If there is no source code, return :keyword:`None`. If the
>> +        integer. If there is no source code, return ``None``. If the
> [etc]
> 
> you have seem to have systematically removed the :keyword: role from 
> None, False, and True. Since Language Reference 2.3.1 Keywords defines 
> them as keywords, the entry
> 
> keyword
> The name of a keyword in Python.
> 
> in 4.5. Inline markup, Additional Markup Constructs, should specify 
> "except for None, False, or True, which should just be marked as code 
> literal ``None``, etc.".  Or perhaps "The name of a statement keyword 
> (other than None, False, or True) in Python."

This section of "Documenting Python" should probably be rephrased.

> If your rule is even more nuanced (only sometimes make an exception), 
> please elucidate.

The rule is simple: :keyword:`...` generates a link.  There is no corresponding
link target, and therefore Sphinx generates a warning (which is new in 1.0.7,
which fixed that bug.)

As for why there is no link target: I think any Python programmer knows what
None, True or False are.  There is absolutely no need to create a link every
time one of them is mentioned, which is pretty often, especially in the case of
None.  In contrast, take for example "the :keyword:`with` statement": this one
is pretty new and many programmers might not be entirely certain what it was
about; the link goes to the description of that statement.

cheers,
Georg