[issue2761] Doc: built-in callables and map

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

To the best of my memory, the fact that
type(built_in_function_section_object) is sometimes 'type...' (soon to
be 'class...') rather than 'built-in function...' has been a point of
occasional confusion on c.l.p for years.  Such confusion was part of a
recent newbie post there.  I actually suggested, only half jokingly,
'Built-in callables' (and got at least one positive response) but
decided that that was both too general and maybe a bit obscure, even
though the Language Reference has a section on Callables.  Hence the
more specific suggestion.  Perhaps we need more newbie opinions as to
which they find clearer.

Even if the title is left alone, I urge the expansion of the first
sentence, though 'and callable classes' might be better.

The double use of 'function' is definitely an occasional point of
confusion in Python   I think the crux of our disagreement is alternate
parsings of 'built-in functions':
1) 'built-in' <instances of generic concept> 'function',
2) <instances of specific class> 'built-in function'.
Under 1) the current title is fine.  Under 2), it is not, and 'built-in
functions and classes', interpreted as parsing 2 of 'built-in functions
and [built-in] classes' is better.

The map doc issues are, of course, separate from the title and lead
sentence issue.

__________________________________
Tracker <report at bugs.python.org>
<http://bugs.python.org/issue2761>
__________________________________