This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author Arthur-Milchior
Recipients Arthur-Milchior, Dennis Sweeney, docs@python
Date 2021-11-03.00:37:10
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1635899830.81.0.737188598441.issue45646@roundup.psfhosted.org>
In-reply-to
Content
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?
History
Date User Action Args
2021-11-03 00:37:10Arthur-Milchiorsetrecipients: + Arthur-Milchior, docs@python, Dennis Sweeney
2021-11-03 00:37:10Arthur-Milchiorsetmessageid: <1635899830.81.0.737188598441.issue45646@roundup.psfhosted.org>
2021-11-03 00:37:10Arthur-Milchiorlinkissue45646 messages
2021-11-03 00:37:10Arthur-Milchiorcreate