classification
Title: Numerous minor issues in Language Reference
Type: enhancement Stage: commit review
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, eric.araujo, python-dev, rhettinger, terry.reedy, zach.ware
Priority: low Keywords: easy

Created on 2014-05-05 14:34 by zach.ware, last changed 2014-06-03 14:35 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
PythonRefmanual_3_4_0_Errata.rtf zach.ware, 2014-05-05 14:34
PythonRefmanual_3_4_0_Errata.txt eric.araujo, 2014-05-09 17:31
Messages (9)
msg217926 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-05-05 14:34
Reported by Feliks Kluzniak on docs@:

"""
Hello!

I have been reading the Language Reference Manual in order to teach myself Python 3.  I noticed several minor errors, and a much larger number of linguistic or editorial infelicities.  I have listed them all in the enclosed document: I hope it will be useful.

Sincerely,
— Feliks Kluzniak

P.S. My apologies for not having the time to weed out those remarks which might already have been entered into the list of „documentation bugs”.
"""
msg218185 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-05-09 17:31
Attaching plain text version.
msg218186 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-05-09 17:36
BTW my opinion of the proposed changes is that many of them are good (obvious typos, reports of things unclear to a beginner, etc) but I don’t agree with some typographic changes, I find that some grammar changes are pedantic, and there are even a few misunderstandings of Python.
msg218209 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-05-10 01:14
I suggest at least a patch per chapter (3.x.y, 4.x.y, 6.x.y, ...).
msg218237 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-05-10 20:28
I also don't agree with most of the typographic changes and, like Éric find some of the grammar changes to be pedantic.

The OP refers to his own changes as "editorial infelicities".  This should have been a warning sign.

The OP further warns, "I have been reading the Language Reference Manual in order to teach myself Python 3" which explains why Éric has found " a few misunderstandings of Python".

If the OP cares enough to prepare a chapter by chapter patch (as suggested by Terry), I would be happy to review them one by one, applying any that are actual readability improvements.
msg219201 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-05-27 05:21
New changeset 053ba3c2c190 by Raymond Hettinger in branch '3.4':
Issue 21439:  Minor issues in the reference manual.
http://hg.python.org/cpython/rev/053ba3c2c190
msg219202 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-05-27 05:22
Most of the comments ended-up being useful and we applied.
msg219231 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-05-27 17:11
A few comments on the committed patch.  The quoted diff is trimmed to just the hunks I have comments on.

On Tue, May 27, 2014 at 12:21 AM, raymond.hettinger <python-checkins@python.org> wrote:
> diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
> --- a/Doc/reference/compound_stmts.rst
> +++ b/Doc/reference/compound_stmts.rst
> @@ -170,17 +170,25 @@
>  A :keyword:`break` statement executed in the first suite terminates the loop
>  without executing the :keyword:`else` clause's suite.  A :keyword:`continue`
>  statement executed in the first suite skips the rest of the suite and continues
> -with the next item, or with the :keyword:`else` clause if there was no next
> +with the next item, or with the :keyword:`else` clause if there is no next
>  item.
>
> -The suite may assign to the variable(s) in the target list; this does not affect
> -the next item assigned to it.
> +The for-loop makes assignments to the variables(s) in the target list.
> +This overwrites all previous assignments to those variables including
> +those made in the suite of the for-loop::
> +
> +   for i in range(10):
> +       print(i)
> +       i = 5             # this will not affect the for-loop
> +                         # be i will be overwritten with the next

Typo here, looks like an unfinished thought. "because" rather than "be"?

> +                         # index in the range
> +
>
>  .. index::
>     builtin: range
>
>  Names in the target list are not deleted when the loop is finished, but if the
> -sequence is empty, it will not have been assigned to at all by the loop.  Hint:
> +sequence is empty, they will not have been assigned to at all by the loop.  Hint:
>  the built-in function :func:`range` returns an iterator of integers suitable to
>  emulate the effect of Pascal's ``for i := a to b do``; e.g., ``list(range(3))``
>  returns the list ``[0, 1, 2]``.

> diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
> --- a/Doc/reference/expressions.rst
> +++ b/Doc/reference/expressions.rst
> @@ -520,11 +521,11 @@
>
>  The primary must evaluate to an object of a type that supports attribute
>  references, which most objects do.  This object is then asked to produce the
> -attribute whose name is the identifier (which can be customized by overriding
> -the :meth:`__getattr__` method).  If this attribute is not available, the
> -exception :exc:`AttributeError` is raised.  Otherwise, the type and value of the
> -object produced is determined by the object.  Multiple evaluations of the same
> -attribute reference may yield different objects.
> +attribute whose name is the identifier.  This production can be customized by
> +overriding the :meth:`__getattr__` method).  If this attribute is not available,

Orphaned ')' on this line.

> +the exception :exc:`AttributeError` is raised.  Otherwise, the type and value of
> +the object produced is determined by the object.  Multiple evaluations of the
> +same attribute reference may yield different objects.
>
>
>  .. _subscriptions:
> @@ -1244,10 +1245,9 @@
>     lambda_expr: "lambda" [`parameter_list`]: `expression`
>     lambda_expr_nocond: "lambda" [`parameter_list`]: `expression_nocond`
>
> -Lambda expressions (sometimes called lambda forms) have the same syntactic position as
> -expressions.  They are a shorthand to create anonymous functions; the expression
> -``lambda arguments: expression`` yields a function object.  The unnamed object
> -behaves like a function object defined with ::
> +Lambda expressions (sometimes called lambda forms) are create anonymous

Unfinished thought here; "are create" -> "are used to create"?

> +functions. The expression ``lambda arguments: expression`` yields a function
> +object.  The unnamed object behaves like a function object defined with ::

While we're here, the object is in fact named, its name (__name__) is "<lambda>".  It's not a valid identifier, but it is its name.

>
>     def <lambda>(arguments):
>         return expression
> @@ -1310,13 +1310,15 @@
>
>  .. index:: pair: operator; precedence
>
> -The following table summarizes the operator precedences in Python, from lowest
> +The following table summarizes the operator precedence in Python, from lowest

This sentence still doesn't read correctly to me; the simplest fix that makes sense to my brain is to remove "the" ("... summarizes operator precedence ...").  I would welcome any other better wording.

>  precedence (least binding) to highest precedence (most binding).  Operators in
>  the same box have the same precedence.  Unless the syntax is explicitly given,
>  operators are binary.  Operators in the same box group left to right (except for
> -comparisons, including tests, which all have the same precedence and chain from
> -left to right --- see section :ref:`comparisons` --- and exponentiation, which
> -groups from right to left).
> +exponentiation, which groups from right to left).
> +
> +Note that comparisons, membership tests, and identity tests, all have the same
> +precedence and have a left-to-right chaining feature as described in the
> +:ref:`comparisons` section.
>
>
>  +-----------------------------------------------+-------------------------------------+
> diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
> --- a/Doc/reference/simple_stmts.rst
> +++ b/Doc/reference/simple_stmts.rst
> @@ -7,7 +7,7 @@
>
>  .. index:: pair: simple; statement
>
> -Simple statements are comprised within a single logical line. Several simple
> +A simple statement is comprised within a single logical line. Several simple

I agree with the OP that "comprised within" doesn't cut it.  Does his suggestion of "must fit" instead of "is comprised" work or is there a better wording?

>  statements may occur on a single line separated by semicolons.  The syntax for
>  simple statements is:
>
msg219692 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-06-03 14:35
New changeset be8492101251 by Zachary Ware in branch '3.4':
Issue #21439: Fix a couple of typos.
http://hg.python.org/cpython/rev/be8492101251

New changeset 99b469758f49 by Zachary Ware in branch 'default':
Issue #21439: Merge with 3.4
http://hg.python.org/cpython/rev/99b469758f49
History
Date User Action Args
2014-06-03 14:35:01python-devsetmessages: + msg219692
2014-05-27 17:11:39zach.waresetstage: test needed -> commit review
2014-05-27 17:11:26zach.waresetmessages: + msg219231
2014-05-27 05:22:37rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg219202

versions: + Python 3.4
2014-05-27 05:21:18python-devsetnosy: + python-dev
messages: + msg219201
2014-05-10 20:28:39rhettingersetpriority: normal -> low

nosy: + rhettinger
versions: - Python 3.4
messages: + msg218237

assignee: zach.ware -> rhettinger
2014-05-10 01:14:04terry.reedysetnosy: + terry.reedy
messages: + msg218209
2014-05-09 17:36:21eric.araujosetmessages: + msg218186
2014-05-09 17:31:42eric.araujosetfiles: + PythonRefmanual_3_4_0_Errata.txt
nosy: + eric.araujo
messages: + msg218185

2014-05-05 14:35:20zach.waresetnosy: + docs@python
2014-05-05 14:34:11zach.warecreate