Numeric operator predecence confusing

[fossilet]

BPO	16438
Nosy	@jcea, @ezio-melotti, @meadori, @JulienPalard, @Mariatta, @miss-islington, @eedmunds
PRs	bpo-16438: confusing text regarding numeric precedence corrected #10521 [3.8] bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521) #15904 [3.7] bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521) #15905
Files	16438.patch

^{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 = None
closed_at = <Date 2019-09-11.10:41:52.726>
created_at = <Date 2012-11-08.14:19:31.262>
labels = ['easy', 'type-feature', 'docs']
title = 'Numeric operator predecence confusing'
updated_at = <Date 2019-09-11.10:41:52.726>
user = 'https://bugs.python.org/fossilet'

bugs.python.org fields:

activity = <Date 2019-09-11.10:41:52.726>
actor = 'mdk'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-11.10:41:52.726>
closer = 'mdk'
components = ['Documentation']
creation = <Date 2012-11-08.14:19:31.262>
creator = 'fossilet'
dependencies = []
files = ['28075']
hgrepos = []
issue_num = 16438
keywords = ['patch', 'easy']
message_count = 16.0
messages = ['175163', '175168', '175172', '175178', '176088', '176099', '176126', '176500', '176502', '222408', '324561', '325900', '329874', '351790', '351804', '351806']
nosy_count = 11.0
nosy_names = ['jcea', 'fossilet', 'ezio.melotti', 'meador.inge', 'docs@python', 'ktt3ja', 'mdk', 'Mariatta', 'miss-islington', 'edmundselliot@gmail.com', 'ronron']
pr_nums = ['10521', '15904', '15905']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16438'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[fossilet]

http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex

"All numeric types (except complex) support the following operations, sorted by ascending priority."

It list '-' after '+', '/' after '*'. That is to mean '-' has higher precedence than '+'. That is wrong, and is contradicting with here:

http://docs.python.org/3/reference/expressions.html#summary

This should be made clear.

[jcea]

Precedence ordered per row. Same row, same precedence. I don't see any problem. It is natural math precedence. Closed as invalid.

[fossilet]

I mean the text at the first link need fix. '+' and '-' are not on the same row. And the doc says: "sorted by ascending priority", that means they have ascending priority.

The table in the reference is just right.

[jcea]

You are right, Yongzhi Pan. Reopening. Not sure how to solve it. Delegating to docs@python.

[ktt3ja]

I was trying to fix this, but I ran into a couple questions.

1. Once I put, say, "x + y" and "x - y" into the same table cell, what would a good format be? My preferred format is to have them on separate lines in the cell, but after a lot of googling on the syntax of reST (and trials and errors), I'm still unable to figure out how to do it. Using bullet points would mean I have to align elements in the "Notes" column with the ones in the "Operation" column somehow. Alternatively, I can separate them by comma, but the table would look a bit cluttered.

2. Should the functions abs, int, etc., belong in the same table that's meant to list operators by precedence?

[fossilet]

One possible solution:

We do not list priorities of the operations, instead link to the precedence table in the language reference.

[ktt3ja]

Good idea.

[ezio-melotti]

I'm still unable to figure out how to do it

You could look at Doc/library/unittest.rst, there are some tables that span multiple lines. If you want a newline in the output too I think you have to add a blank line in the cell.

[ktt3ja]

That document actually doesn't have any table that spans multiple lines. Here's the html page: http://docs.python.org/dev/library/unittest.html

Actually, I already know how to make a table span multiple lines from this stackoverflow page: http://stackoverflow.com/questions/13504595/multi-line-table-cell-in-restructuredtext

However, the problem is having the items in different columns match, as it depends on the width of the table, which is not fixed. For example, notice how the table is formatted nicely here: http://imgur.com/y1hLg
But if I shrink the width, the formatting just goes wrong: http://imgur.com/Oct9m

This is particularly problematic because some elements in the table have long lines.

[BreamoreBoy]

I find the numeric operator predecence simply wrong, not confusing, so +1 from me for applying the attached patch from ktt3ja. It's as simple as possible but no simpler :)

[ronron]

Any progress on this?

[eedmunds]

I agree that linking to the precedence table is probably the best solution.

A different option would be to add an extra column listing the "priority" and rank the priorities of the different operations.

[Mariatta]

I'm actually thinking perhaps the "see :ref:`operator-summary`" clause should be separate and under Notes below the table, as opposed to current PR:

All numeric types (except complex) support the following operations (for priorities of
the operations, see :ref:`operator-summary`)

reads oddly to me.

[JulienPalard]

New changeset 4576b54 by Julien Palard (Anjali) in branch 'master':
bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521)
4576b54

[miss-islington]

New changeset 80db4b4 by Miss Islington (bot) in branch '3.8':
bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521)
80db4b4

[miss-islington]

New changeset 9210b58 by Miss Islington (bot) in branch '3.7':
bpo-16438: Doc: confusing text regarding numeric precedence corrected (GH-10521)
9210b58