[issue16677] Hard to find operator precedence in Lang Ref.
New submission from rurpy: Python Language Reference, chapter 6 "Expressions". The last section (6.15) of this is titled, "Summary". That title is misleading -- it is not really a summary of the "Expressions" chapter but rather, as the first sentence makes clear, a table of operator precedences. It is not really even a "summary" of operator precedences since some of the preceeding operator sections don't mention their precedence. And adding to the confusion, none of preceding sections even use the word precedence, referring instead to "binding" or "priority". Operator precedences are something many users frequently look for frequently in a language reference and the lack of an Operator Precedence entry in the ToC makes this section hard to find. There are no index entries for "operators/precedence" or "expressions/order of evaluation". There is an index entry for "evaluation order" but that points to a different section. At a minimum, this section should have its title changed from "Summary" to "Operator Precedence" and get one or more index entries. In other languages operator precedence is often described and indexed under "order of evaluation", often as a subindex of "expressions". In the Python reference, there is a very short section called, 6.14, "Evaluation Order" that immediately preceeds the Operator Precedence section. That section and the Operator Precedence section could be effectively combined into a single section. ---------- assignee: docs@python components: Documentation messages: 177444 nosy: docs@python, rurpy2 priority: normal severity: normal status: open title: Hard to find operator precedence in Lang Ref. type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +chris.jerdonek, ezio.melotti stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Terry J. Reedy added the comment: I agree with index entries and that 6.14 Evaluation Order (7 lines) and 6.15 Summary (precedence table and notes) could be combined into 6.14 Evaluation Order and Precedence. I don't think the text necessarily needs revision. Just augment 6.14 and remove 6.15. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Roundup Robot added the comment: New changeset a0f6c68ea12f by Ezio Melotti in branch '2.7': #16677: rename section header and fix markup. http://hg.python.org/cpython/rev/a0f6c68ea12f New changeset 2eab4f7b7280 by Ezio Melotti in branch '3.2': #16677: rename section header and fix markup. http://hg.python.org/cpython/rev/2eab4f7b7280 New changeset 356af3fc6471 by Ezio Melotti in branch '3.3': #16677: merge with 3.2. http://hg.python.org/cpython/rev/356af3fc6471 New changeset 9a65501a71e6 by Ezio Melotti in branch 'default': #16677: merge with 3.3. http://hg.python.org/cpython/rev/9a65501a71e6 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Ezio Melotti added the comment: I think it's better to keep the two sections separate, so I just changed the title from "Summary" to "Operator precedence". While I was at it I also fixed the markup in a few places in the section and noticed a mistake in the "Evaluation order" (reported in #16777). Regarding the index entries I don't see anything wrong with the current ones, but I'm not sure how they are supposed to work and I generally find Google more reliable than the Sphinx search. ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Terry J. Reedy added the comment: Changing 'datum' to 'value' is a nice touch that I overlooked. It is definitely friendlier to people whose native language is not latin-infested. Thanks. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +chris.jerdonek, ezio.melotti stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Terry J. Reedy added the comment: I agree with index entries and that 6.14 Evaluation Order (7 lines) and 6.15 Summary (precedence table and notes) could be combined into 6.14 Evaluation Order and Precedence. I don't think the text necessarily needs revision. Just augment 6.14 and remove 6.15. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Roundup Robot added the comment: New changeset a0f6c68ea12f by Ezio Melotti in branch '2.7': #16677: rename section header and fix markup. http://hg.python.org/cpython/rev/a0f6c68ea12f New changeset 2eab4f7b7280 by Ezio Melotti in branch '3.2': #16677: rename section header and fix markup. http://hg.python.org/cpython/rev/2eab4f7b7280 New changeset 356af3fc6471 by Ezio Melotti in branch '3.3': #16677: merge with 3.2. http://hg.python.org/cpython/rev/356af3fc6471 New changeset 9a65501a71e6 by Ezio Melotti in branch 'default': #16677: merge with 3.3. http://hg.python.org/cpython/rev/9a65501a71e6 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Ezio Melotti added the comment: I think it's better to keep the two sections separate, so I just changed the title from "Summary" to "Operator precedence". While I was at it I also fixed the markup in a few places in the section and noticed a mistake in the "Evaluation order" (reported in #16777). Regarding the index entries I don't see anything wrong with the current ones, but I'm not sure how they are supposed to work and I generally find Google more reliable than the Sphinx search. ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
Terry J. Reedy added the comment: Changing 'datum' to 'value' is a nice touch that I overlooked. It is definitely friendlier to people whose native language is not latin-infested. Thanks. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16677> _______________________________________
participants (4)
-
Ezio Melotti -
Roundup Robot
-
rurpy
-
Terry J. Reedy