Here's a patch that represents the result of grepping through the source 
for some of my favo(u)rite spelling errors.

Georg, I reali(z/s)e that most of these fixes are outside the Doc/ 
directory, but are you interested in taking a look at these?  Please 
unassign if not.

Two notes:

- I'm pretty sure that all of these are genuine errors.  The only one
that may be controversial is 'builtin -> built-in' (when used as an 
adjective).  The 'Apple Publications Style Guide' seems to use built-in in 
preference to builtin.  I also think I missed a few of these.

- My (American English) spell-checker complains about 'signalled', but it 
looks fine when I put my British English eyes in.  The docs contain  
instances of both 'signalled' *and* 'signaled'.  Is there any consensus on 
whether American English or British English should be used for Python's 
documentation?  (Should also check for 'signalling' versus 'signaling'.)

I reviewed the patch and found nothing wrong. (BTW, if you noticed the
almost-total lack of its<->it's errors, it's because I fixed all of them
some time ago :)

"built-in" is fine.

About AE/BE: I think we had a consensus somewhere that we have no fixed
variant, but if you write a larger chunk of text you may write in your
preferred spelling.  I guess that if you look for instances of "-or" vs
"-our" you might find lots of stuff too.  So I'd leave them alone.

Please do not change builtin to built-in.  In a python context, it reads
fine as one word.

Thanks, Georg.  And yes, I was indeed wondering why I found so few wayward 
apostrophes!

Applied in r69846, r69847.  I'm not sure whether it's worth backporting 
these to 2.6 and 3.0.

> Please do not change builtin to built-in.  In a python context, it reads
> fine as one word.

"built-in" seems to be the more common spelling within the documentation.
Personally, in the context of Python I find "builtin" acceptable as a noun 
("don't shadow builtins"), but it still looks wrong when used as an 
adjective ("the builtin function open").  Anyway, I'll refrain from making 
any more of these changes.

Short summary from a discussion on #python-dev:
- verb form: “This function is built in.”
- adjective form: “``str`` is a built-in function”
- noun form (not mainstream English, but usual in programming contexts):
“``repr`` is a builtin”, “prefer the builtins”.

Hello

I fixed a few remaining misuses of “builtin” in the source. There is some diff noise due to reformatting paragraphs where the addition of the hyphen caused the line to get over 80 characters.

Note that I didn’t check the use of “built-in”, for fear of having too much files to review.

I looked only in Doc. I’ve found misuses in other places, but reviewing the whole source would take more time than I had on my hands.

Please review.

Regards

Additional note to help reviewing: I changed occurrences of the form “builtin x” to “built-in function x” not because I think the noun “builtin” is incorrect, as you may guess from my first message in this thread, but because it seemed more readable for beginners. If core devs disagree for some reason I’ll back out these changes.

About the change from “the builtin set function” to “the built-in set class”: I stumbled about this occurrence and fixed it, but haven’t looked at the rest of the docs. Tell me if this belongs in a separate, more complete patch.

Thanks, committed as r78024, r78025, respectively.

I should have seen this when changing one use of “builtin”. Applies only to py3k, since the glossary for trunk does not mention the `next` function.

Thanks, applied as r78238.

Hello again

And now for something completely different: more builtin/built-in/built in fixes. I hope it’s okay to edit Misc/HISTORY and old Misc/NEWS entries.

Note that I fixed two unrelated typos that I noticed near “builtin” uses.

Some day I’ll do something more useful for Python.

Cheers

I grepped for “built-in” in Doc and found very few misuses. Patch attached.

Some lines needed rewrapping, I made another patch for this to ease reviewing.

Cheers

Here is the path that rewraps lines longer than 80 characters.

Note that it is possible than some lines were unnecessarily rewrapped; I’m not really sure whether my editor displays the characters count or the index of the next character. Sorry about that.

I’ve noticed that some parts were wrapped to 72 characters and other to 80. PEP 8 tells to wrap text to 72 characters in Python files; is there a similar guideline for the doc anywhere?

If anyone know of a tool that can report lines longer that a certain length (preferably encoding-aware, i.e. counting characters and not bytes), I’d be glad to hear of it.

Cheers

Georg can correct me if I'm wrong, but I believe we generally only rewrap lines when we change the text for some other reason.  My observation was that Georg re-wraps doc text to 79 chars, so that's what I've been doing.  PEP 8 really only applies to source files, the docs are (at least currently) Georg's demesne.

David is correct, rewrapping while editing is intrusive enough.

The docs should be wrapped at 79/80 characters.  The reason that most files have longer lines is that the latex to rest converter tool had a flaw in the wrapping code that I didn't notice until after the conversion.

Applied the two other patches in r78760.

> rewrap lines when we change the text for some other reason.
Doesn’t that make harder to review the real changes when they are mixed 
with rewrapping?

 > PEP 8 really only applies to source files, the docs are (at least
 > currently) Georg's demesne.
(domain?) I was only citing PEP 8 as a reference, since there are some 
indications about line length of text paragraphs.

Cheers

> > rewrap lines when we change the text for some other reason.
> Doesn’t that make harder to review the real changes when they are mixed 
> with rewrapping?

That's true. I wouldn't do it in patches I mean someone else to review. But many times it's the other way round: I apply doc changes from some patch, and then rewrap before committing.

No, I meant demense (I even looked up the spelling).  The word is related to domain, but has a somewhat more precise shading of meaning :)

     A lord's chief manor place, with that part of the lands
     belonging thereto which has not been granted out in tenancy;
     a house, and the land adjoining, kept for the proprietor's
     own use. [Written also {demain}.] --Wharton's Law Dict.

In other words, Georg is lord of this particular manor, unless he assigns a piece to someone else...it seemed in keeping with the Python tradition of having a BDFL.

Thanks for the new word. (I checked with my local dictd but not on the 
Intertubes, should have).

Having designated active maintainers for modules and areas is indeed great.

Cheers

Hello spelling and doc people

(I hope it’s okay to use this bug as umbrella instead of opening a myriad bugs for typos.)

Attached patch fixes small things in functools module and docs:
- Typos: “simplies” does not exist, “fills-in” needs no hyphen since it’s a verb;
- Unnecessary repetition of filename in docstring (doc tools are good enough to introspect it, see e.g. “pydoc functools”);
- Whitespace in keyword arguments;
- Use triple-quoted docstrings for consistency’s sake.

Regards

Hi

r79951 fixes “simplies” and add the typo “specifyication” <Muphry’s Law wink>. Updated my patch to remove that and add this.

Regards

I saw the author of functools on the chatroom and asked for feedback. Summary:

* Rewrapping, whitespace changes, quote changes and other minor PEP 8 stuff is not worth the trouble it creates (eats time without improving Python’s quality, and also disturbing use of $vcs blame);
* Doc changes have to apply to all four branches, not just trunk and py3k.

This leaves the two typos.  I’ll port the “built{-,}in” fixes to 2.6 and 3.1 later.

OK, fixed the two typos in r80067, r80068.  Please open a new issue for further fixes, this one gets a bit confusing :)

Raymond didn’t want the quote characters changed, sorry if I failed to channel him.

I’ll port the “builtin” typo fixes to the other branches and let this report closed. Thanks for the guidance.