Arthur Milchior <arthur@milchior.fr> added the comment: https://docs.python.org/3/reference/expressions.html#grammar-token-python-gr... is wrong This line state: `expression ::= conditional_expression | lambda_expr` and it is a problem because, by the way sphinx understand reference, this mean that any people who use the token `expression` will be linked to this particular line. For example in https://docs.python.org/3/reference/expressions.html#grammar-token-python-gr... `key_datum ::= expression ":" expression | "**" or_expr` while clearly a key_datum is not expecting only a conditional expression or a lambda expression. Admittedly, you can derive, from expression: * conditional_expression * or_test * and_test * not_test * comparison * or_expr * xor_expr * and_expr * shift_expr * a_expr * m_expr * u_expr * power * primary * atom in this order, so in practice you can probably derive most of the expressions. However, I doubt that this is what the documentation meant here, and clearly not practical. ---------- title: The documentation wrongly uses or_expr for star expresion in displays -> "expression" is erroneous in the doc _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue45646> _______________________________________

Arthur Milchior <arthur@milchior.fr> added the comment: Message 405188 was supposed to be another bug report. My bad. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue45646> _______________________________________

Dennis Sweeney <sweeney.dennis650@gmail.com> added the comment: Hi Arthur, I agree that the line about "name ::= othername" could be more helpful. I think an affirmative example would be better than a warning against depending on variable names, because the top of the page mentions that BNF is being used and IMHO the variable names are consistent with how BNF is typically used, so negative/warning language might be more confusing. I'm also not sure a note saying "read the documentation" in the documentation will help people read the documentation ;) Maybe an example could be something like: --------- In this and the following chapters, extended BNF notation will be used to describe syntax (but not tokenization/lexical analysis). Extended BNF uses syntax rules like the following: a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr This rule indicates that an a_expr ("a" is for addition, but subtraction has the same precedence) is one of the following: * Just an m_expr (the "m" is for multiplication-like operations) * A smaller a_expr, followed by a "+" sign, followed by an m_expr * A smaller a_expr, followed by a "-" sign, followed by an m_expr For concreteness, given that `x * y`, `x / y`, `a[i]` and `foo.bar` are instances of `m_expr`, the rule implies that `x * y`, `x / y + a[i]`, and (recursively) `foo.bar + x * y - a[i]` are all instances of `a_expr`. --------------- Maybe there could be a link to a more-detailed BNF tutorial/reference. ---------- nosy: +Dennis Sweeney _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue45646> _______________________________________

Arthur Milchior <arthur@milchior.fr> added the comment: Thank you very much Dennis. For two reasons. First, because I like a lot what you wrote. I suspect that it would have saved me time and make things less confusing. That's not certain, because at the time I was reading the documentation of or_expr, I may have skipped or forgotten the part about BNF. A solution - that would require a bigger change - is that the various blocks containing rules have a small link back to the text you wrote, so that if a reader reads the rule directly, they can find out the meta information they need to know about rules. I guess that it's technically possible to do it with an extra sphinx rule, but may not be trivial to do, and it's not clear how such a link and text should look like in practice, as it must be noticeable the first time and easy to ignore next time. Thanks also because I'm happy, and slightly relieved, that my concerns are taken seriously. I admit that I feared that I would get as answer something such as:

actually, if you knew BNF, it should be clear that the actual meaning of or_expr is ....

And the fact that the answer I got tries to actually clarify the documentation for people wanting to learn or review Python without being expert in programming language theory is really great. Do you open a PR with your suggested test or do I update mine? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue45646> _______________________________________