Numerous minor issues in Language Reference

[zware]

BPO	21439
Nosy	@rhettinger, @terryjreedy, @merwok, @zware
Files	PythonRefmanual_3_4_0_Errata.rtf PythonRefmanual_3_4_0_Errata.txt

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2014-05-27.05:22:37.530>
created_at = <Date 2014-05-05.14:34:11.889>
labels = ['easy', 'type-feature', 'docs']
title = 'Numerous minor issues in Language Reference'
updated_at = <Date 2014-06-03.14:35:01.535>
user = 'https://github.com/zware'

bugs.python.org fields:

activity = <Date 2014-06-03.14:35:01.535>
actor = 'python-dev'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2014-05-27.05:22:37.530>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2014-05-05.14:34:11.889>
creator = 'zach.ware'
dependencies = []
files = ['35153', '35201']
hgrepos = []
issue_num = 21439
keywords = ['easy']
message_count = 9.0
messages = ['217926', '218185', '218186', '218209', '218237', '219201', '219202', '219231', '219692']
nosy_count = 6.0
nosy_names = ['rhettinger', 'terry.reedy', 'eric.araujo', 'docs@python', 'python-dev', 'zach.ware']
pr_nums = []
priority = 'low'
resolution = 'fixed'
stage = 'commit review'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21439'
versions = ['Python 3.4', 'Python 3.5']

[zware]

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”.
"""

[merwok]

Attaching plain text version.

[merwok]

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.

[terryjreedy]

I suggest at least a patch per chapter (3.x.y, 4.x.y, 6.x.y, ...).

[rhettinger]

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.

[python-dev]

New changeset 053ba3c2c190 by Raymond Hettinger in branch '3.4':
bpo-21439: Minor issues in the reference manual.
http://hg.python.org/cpython/rev/053ba3c2c190

[rhettinger]

Most of the comments ended-up being useful and we applied.

[zware]

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:

[python-dev]

New changeset be8492101251 by Zachary Ware in branch '3.4':
Issue bpo-21439: Fix a couple of typos.
http://hg.python.org/cpython/rev/be8492101251

New changeset 99b469758f49 by Zachary Ware in branch 'default':
Issue bpo-21439: Merge with 3.4
http://hg.python.org/cpython/rev/99b469758f49