[issue6570] Documentation Clarity

[Mark du Preez]

New submission from Mark du Preez <drunkard at thepub.co.za>:

Hi

In section 4.7.2 of the tutorial documentation, we suddenly find the
following paragraph:

"In general, an argument list must have any positional arguments
followed by any keyword arguments, where the keywords must be chosen
from the formal parameter names. It’s not important whether a formal
parameter has a default value or not. No argument may receive a value
more than once — formal parameter names corresponding to positional
arguments cannot be used as keywords in the same calls. Here’s an
example that fails due to this restriction:"

To a beginner who is reading a tutorial to learn how to use this
language for the first time, it is completely overwhelming. What is a
"positional argument" vs a "keyword argument" and what is a "formal
parameter name"?

None of these things have been explained up until this point and an
understanding of their meaning is required to make sense of this paragraph.

Please consider revising this section.

Thank you.

Mark

----------
assignee: georg.brandl
components: Documentation
messages: 90910
nosy: StMark, georg.brandl
severity: normal
status: open
title: Documentation Clarity
type: feature request
versions: Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue6570>
_______________________________________