[issue21439] Numerous minor issues in Language Reference

[Zachary Ware]

Zachary Ware added the comment:

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 at 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 tracker <report at bugs.python.org>
<http://bugs.python.org/issue21439>
_______________________________________