[issue25523] Correct "a" article to "an" article
New submission from Martin Panter: This patch generally changes “a” to “an” where appropriate in the main documentation, doc strings, source code comments, and a couple error messages in the test suite. Since it touches so many files, I thought it would be good to get a quick review. ---------- assignee: docs@python components: Documentation files: a-an.patch keywords: patch messages: 253784 nosy: docs@python, martin.panter priority: normal severity: normal stage: patch review status: open title: Correct "a" article to "an" article versions: Python 3.4, Python 3.5, Python 3.6 Added file: http://bugs.python.org/file40909/a-an.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: Removed file: http://bugs.python.org/file40909/a-an.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Martin Panter added the comment: Rebased so it should be reviewable ---------- Added file: http://bugs.python.org/file40910/a-an.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Serhiy Storchaka added the comment: I suppose that changes was generated by a script. But some changes looks not satisfying a simple rule. In Doc/library/multiprocessing.rst, Doc/library/socket.rst, Doc/whatsnew/3.2.rst, Misc/HISTORY, Modules/_hashopenssl.c "a" is just deleted. Is it deliberately? In Doc/library/smtplib.rst "a" is replaced to "an" before a word starting with consonant: SMTP. Is it correct? Aren't files in Lib/test/decimaltestdata/ imported from external source? Then we shouldn't change them. The rest of changes LGTM, but I'm not sure about mentioned above. ---------- nosy: +r.david.murray, serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Emanuel Barry added the comment:
In Doc/library/smtplib.rst "a" is replaced to "an" before a word starting with consonant: SMTP. Is it correct?
One of the peculiriarities of the English language is that, in front of acronyms, you have two different ways to decided which to use between "a" and "an" - first (and probably what you thought), is to think of what the acronym means (or which letter it begins with). The other way, which Martin probably used, is to use what would sound be if it was said out loud, and "An ess-emm-tee-pee" sounds better overall. In other words, both work, and it's down to personal preference. However, if we decide to use "an" here for this reason, it should (IMO) remain consistent across all of the documentation. I've only briefly looked over the patch as I have to head out soon, but I wanted to make this point anyway. ---------- nosy: +ebarry _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
R. David Murray added the comment: Yes, those deletions are intentional, they make the English read better (to me as a native speaker, at least :) As Emanuel said, the SMTP thing comes from reading it as an acronym, which is how I generally do it, and I suppose most people do. Given how thorough Martin has been here, I'm guessing this was the one place that an wasn't used :) This all looks good to me, except that I would rewrite and an isfile and isdir check on it as and isfile and isdir checks on it Agree with Serhiy's caveat about decimaltestdata. Adding Mark to nosy to double check, but I don't think that file should be changed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Changes by R. David Murray <rdmurray@bitdance.com>: ---------- nosy: +mark.dickinson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Mark Dickinson added the comment: Yes, the Lib/test/decimaltestdata files do come from an external source. I don't see the harm in including them in the changes, but those changes will be overwritten when the files are next updated. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Mark Dickinson added the comment: I should have said what that source is: it's http://speleotrove.com/decimal/ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Martin Panter added the comment: Thanks everyone for the comments. Serhiy’s points: I did this by using “grep” and then manually editing all of the appropriate lines. So they were not generated by a script, but because it is a fairly mindless process I could have made human mistakes. In multiprocessing.rst, socket.rst, I removed “a” because I thought it matched the surrounding text, e.g. it already says nearby “If . . . then OSError is raised”, rather than “an OSError is raised”. I find the documentation uses both forms in many places, so I just try to keep things consistent with the nearby text. In 3.2.rst, I thought it should be plural: “total_ordering() will use existing equality and inequality methods”. I could reword it to something like “will use an existing equality and inequality method” if you prefer. Either way seems valid to me. In HISTORY, I removed “a” from “. . . is passed ill-formed input” because it seemed better (similar to “is passed hot water”). But “an ill-formed input” should also be fine if people prefer. _hashopenssl.c: “have a its own definition” is nonsense, hence I removed “a”. “An SMTP”: See Emanuel and David. The rest of the page uses “an SMTP”, while I only found two instances of “a SMTP”, which I made consistent. Externally-supplied decimaltestdata: I did wonder about this. Looking at the history, I saw other local changes, but now I notice most are in a special “extra.decTest” file. Anyway, as Mark says it is okay I will let my changes go ahead for the time being. David: I have incorporated your suggestion for test_discovery.py into my local patch. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Serhiy Storchaka added the comment: I had pointed to some of changes not because they look wrong to me, but for the case if there are human mistakes. After your acknowledgement all LGTM. ---------- stage: patch review -> commit review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Roundup Robot added the comment: New changeset d8ff13414deb by Martin Panter in branch '3.4': Issue #25523: Correct "a" article to "an" article https://hg.python.org/cpython/rev/d8ff13414deb New changeset e279ab6753fd by Martin Panter in branch '3.5': Issue #25523: Merge "a" to "an" fixes from 3.4 into 3.5 https://hg.python.org/cpython/rev/e279ab6753fd New changeset 2347271172b3 by Martin Panter in branch '3.5': Issue #25523: Further a-to-an corrections new in 3.5 https://hg.python.org/cpython/rev/2347271172b3 New changeset 96e61bb7f6e9 by Martin Panter in branch 'default': Issue #25523: Merge a-to-an corrections from 3.5 https://hg.python.org/cpython/rev/96e61bb7f6e9 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- resolution: -> fixed stage: commit review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Serhiy Storchaka added the comment: Here is a patch with additional changes. ---------- resolution: fixed -> stage: resolved -> patch review status: closed -> open Added file: http://bugs.python.org/file40925/a-an_2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Martin Panter added the comment: Thanks Serhiy. My pass over the files missed most cases where there was a line break involved, and certain punctuation and markup, which you picked up on. I skipped the /Lib/msilib/schema.py file in my patch because it was part of the data rather than a comment, and I wasn’t sure what it is for. It seems to be a generated file from some Windows source. But I see other people have made similar corrections, so it might be okay. I left a couple of comments. Apart from those, the rest look good to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Roundup Robot added the comment: New changeset 75df8b0a2cd1 by Serhiy Storchaka in branch '3.4': Issue #25523: Further a-to-an corrections. https://hg.python.org/cpython/rev/75df8b0a2cd1 New changeset 68edc7baeef7 by Serhiy Storchaka in branch '3.5': Issue #25523: Merge a-to-an corrections from 3.4. https://hg.python.org/cpython/rev/68edc7baeef7 New changeset a0d0f968b020 by Serhiy Storchaka in branch '3.5': Issue #25523: Further a-to-an corrections new in 3.5. https://hg.python.org/cpython/rev/a0d0f968b020 New changeset 72cca30f4707 by Serhiy Storchaka in branch 'default': Issue #25523: Merge a-to-an corrections from 3.5. https://hg.python.org/cpython/rev/72cca30f4707 New changeset e8f3c011e2b4 by Serhiy Storchaka in branch '2.7': Issue #25523: Backported a-to-an corrections. https://hg.python.org/cpython/rev/e8f3c011e2b4 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Serhiy Storchaka added the comment: Thank you Martin for your review. ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Roundup Robot added the comment: New changeset 651f7addf4a8 by Martin Panter in branch '2.7': Issue #25523: Correct "a" article to "an" article https://hg.python.org/cpython/rev/651f7addf4a8 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- versions: +Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25523> _______________________________________
participants (6)
-
Emanuel Barry -
Mark Dickinson
-
Martin Panter
-
R. David Murray
-
Roundup Robot
-
Serhiy Storchaka