Docs: Clarify BNF description in "introduction.rst" #14492
Conversation
In the following section "name: `lc_letter` (`lc_letter` | "_")*" the section states "a ``name`` is an ``lc_letter`` followed by a sequence of zero or more ``lc_letter``\ s and underscores" there is an issue with the usage of "and" in "``lc_letter``\ s and underscores". While this usage of "and" is not grammatically incorrect in English context, if interpreted by the reader literally in the context of the notation, "``lc_letter``\ s and underscores" would directly translate to (`lc_letter` & "_"), which would entirely change the meaning of that line. Therefore, I would suggest changing "``lc_letter``\ s and underscores" to "``lc_letter``\ s or underscores". Usually I would consider a change to a single word a very minor commit, but a single word can entirely change the meaning in this context.
|
Thanks for looking into this! "lc_letters or underscores" could also be potentially confusing, couldn't it? One might think that there must be only lc_letters or only underscores, but not a mix of both. Perhaps we should use "lc_letters and/or underscores" for maximum clarity and preciseness? |
|
@taleinat Thanks for the feedback, I was thinking primarily in the context of the logical operators rather than the English usage of "or". The usage of "and/or" would probably be the most accurate and clearly understandable way to satisfy both of the contexts. I'll add your suggestion to the PR. |
Improve the clarity by changing ``or`` to ``and/or``. This simultaneously satisfies the logical operation and English contexts.
|
@taleinat Would you mind reviewing this PR? I made the changes that you recommended. |
|
From the documentation section of the experts index, cc @ezio-melotti, @merwok, @JulienPalard, @willingc. |
|
@taleinat Since this PR still hasn't received any further core dev reviews a month after I pinged the documentation experts, could we go forward with an auto-merge label? According to the devguide the appropriate procedure is:
However, I think this PR might be a bit too minimal to justify creating a new thread on the ML. I don't at all blame anyone in particular for this issue, but in the current system, it can be very difficult to get minor documentation PRs approved which make improvements to existing sections. I've tried to assist with this issue myself by providing feedback on other documentation PRs, but that doesn't always solve the problem. Would it be possible to recruit a new core developer/committer specifically for reviewing and approving smaller documentation PRs? Carol is quite busy as a SC member and two of the other three listed documentation experts are only sporadically active or have not been recently active, see ezio-melotti, and merwork. As far as I can tell, Julian is more active but he does not seem to have much time to spend on PR reviews. |
IMO this is the important point.
Such a reader would read the BNF directly and not be confused by the plain text exegesis, no? 🙂 I’m -0, I don’t think there is a problem here (unlike (Sorry you have to wait and discuss so much for such a small thing! Good that you have other PRs merged for more substantive changes) |
|
@merwok
Good point, I may have been taking the "and" a bit more literally than most readers would. Also, I think at the time I made this PR, I might have been looking a bit too hard to find meaningful improvements. I've gained a decent amount of experience since then, and have found more impactful issues to work on. But, I've always had the mentality that it's far better to take the risk of making an unnecessary suggestion than it is to potentially miss out on a meaningful one.
No problem. So far from my experiences thus far in both submitting and reviewing PRs, there are far more PRs than there are people to review them. However, it does seem that this issue disproportionately affects PRs that exclusively involve documentation changes. I think there might be a significantly greater deficit of active documentation experts in comparison to other categories, especially when the volume of PRs involving documentation changes is taken into consideration. |
The text below describes the change proposal to the "Notation" section of "Doc/reference/introduction.rst".
In reference to the section describing the first line of BNF notation, "name: lc_letter (lc_letter | "_")*", the section states "a name is an lc_letter followed by a sequence of zero or more lc_letters and underscores" there is an issue with the usage of "and" in "lc_letters and underscores". While this usage of "and" is grammatically correct in English context, if the reader interprets it literally in the context of BNF notation or computer science, "lc_letters and underscores" would translate to (lc_letter & "_"), which would entirely change the meaning of that line.
Therefore, I would suggest changing "lc_letters and underscores" to "lc_letters or underscores". This ensures the reader clearly understands the logical disjunction operator is being utilized and does not misunderstand "and" to be the conjunction operator since the English word "and" can mean either of them, depending on the context.