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.

Rebased so it should be reviewable

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.

> 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.

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.

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.

I should have said what that source is: it's http://speleotrove.com/decimal/

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.

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.

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

Here is a patch with additional changes.

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.

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

Thank you Martin for your review.

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