[docs] IDLE documentation for Unix obsolete/incorrect (issue 5066)

[zachary.ware at gmail.com]

Several nitpicks and a few vague ramblings (on my part) that I hope
convey some of my thoughts on improving the overall quality of the
patch.

Overall, though, this looks like a solid update to the IDLE docs :)


http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst
File Doc/library/idle.rst (right):

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode19
Doc/library/idle.rst:19: * cross-platform: works on Windows, Unix, and
OS X
"Mac OS X" is what's most used elsewhere in the Python docs.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode22
Doc/library/idle.rst:22: features, e.g. smart indent and call tips
End this with "... and many other features".  The two features tacked on
to the end can be moved to the left side of that phrase and drop the
'e.g.'

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode32
Doc/library/idle.rst:32: IDLE has two window types the Shell window and
the Editor window. It is
There should be a colon or a comma after 'types'.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode139
Doc/library/idle.rst:139: Format menu (only in Editor window)
I think each case of '(only in (Editor|Shell) window)' would look better
as '((Editor|Shell) window only)'.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode159
Doc/library/idle.rst:159: Turn *all* tabs into the right number of
spaces
'right' should probably be changed to 'correct'.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode166
Doc/library/idle.rst:166: Open a dialog to switch between indenting with
spaces and tabs. The
Is this right? 'New Indent Width' opens the same dialog as 'Toggle
tabs'?

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode188
Doc/library/idle.rst:188: Checks the syntax of the current module which
is the code loaded in the
Perhaps 'Check the syntax of the module currently open in the Editor
window.'?

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode194
Doc/library/idle.rst:194: clean then executes the current file in the
__main__ namespace.
Wrong tense, I believe.  Better would be "Restart the shell to clean the
environment, then execute the currently open module."  Also, consistent
use of 'module' or 'file' would be good (between 'Check module' and 'Run
module', for instance).  And doesn't 'Run module' prompt for a save as
well?

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode200
Doc/library/idle.rst:200: Scrolls the shell window to the last Shell
restart
Change the tense: 'Scroll', not 'Scrolls'

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode203
Doc/library/idle.rst:203: Restarts the Python interpreter with a fresh
environment
See above comment.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode213
Doc/library/idle.rst:213: Debugger (toggle) (not complete consider it
experimental)
The 'not complete' note would be better in the description.  Better
still, the debugger's usage (and limitations) could be documented in its
own section.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode220
Doc/library/idle.rst:220: Toggle automatically opening the stack viewer
on a traceback
If I'm not mistaking the purpose of the feature, perhaps 'a traceback'
should be 'unhandled exception'?

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode237
Doc/library/idle.rst:237: is not present in the Shell window only the
Editor window.
Only need one note about which window has this option; I'm not too picky
about where it is other than to be consistent with other cases like
this.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode270
Doc/library/idle.rst:270: * Right-click in Editor window (Control-click
on OS X)
I'm not sure whether this line is still necessary.  Don't the majority
of people know what a context menu is these days?

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode323
Doc/library/idle.rst:323: * :kbd:`C-LeftArrow` and :kbd:`C-RightArrow`
moves by words in a strange but
'strange but useful' isn't very descriptive...

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode330
Doc/library/idle.rst:330: * Some useful :program:`Emacs` bindings are
inherited from TCL/Tk:
Tcl isn't all caps.  There's another instance of this a bit further
down.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode351
Doc/library/idle.rst:351: Standard Window's bindings (like :kbd:`C-c` to
copy and :kbd:`C-v` to paste)
Why the apostrophe in Windows?  And I may be wrong, but aren't these
pretty standard everywhere these days?  Maybe make it just 'Standard
keybindings (like...' instead?

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode377
Doc/library/idle.rst:377: the ACW will open immediately if a possible
continuation is found.
This paragraph switches between second and third person ("you type", "is
typed").  There are a couple other instances of second person
perspective.  I'm not sure if it's official policy, but it seems to me
that the library reference is best kept in third person and stick with
only the facts of what the code does.  Second person would be more
suited to a HOWTO. In fact, a good portion of this section would do well
as part of a separate "Using and customizing IDLE" HOWTO.

On the other hand, IDLE is pretty unique in the standard library. 
Ideally, IDLE should be documented separately (as a HOWTO, for example)
and idlelib documented within the library reference.  But that's an
entirely different issue.  Since this page is really more of a 'How to
use IDLE' page anyway, we may have more leeway with the style.  The real
point here is to pick a style and stick with it throughout the page,
whichever it be.

http://bugs.python.org/review/5066/diff/6697/Doc/library/idle.rst#newcode400
Doc/library/idle.rst:400: Completions and the 'Expand Word' facility can
save a lot of typing!
This one is an example of not sticking to just laying out what the code
does, as mentioned in the previous comment.

http://bugs.python.org/review/5066/diff/6697/Lib/idlelib/help.txt
File Lib/idlelib/help.txt (right):

http://bugs.python.org/review/5066/diff/6697/Lib/idlelib/help.txt#newcode11
Lib/idlelib/help.txt:11: -debugger (not complete, but yes can set
breakpoints, view and step)
s/yes/you/

http://bugs.python.org/review/5066/diff/6697/Lib/idlelib/help.txt#newcode177
Lib/idlelib/help.txt:177: Go to file/line  -- Same as in Debug menu
Everything above this point should pretty much be lifted verbatim from
Doc/library/idle.rst.  As such, any comments on it apply here.

http://bugs.python.org/review/5066/diff/6697/Lib/idlelib/help.txt#newcode191
Lib/idlelib/help.txt:191: browse for its path on your machine using the
Browse button.
Is this paragraph still current?

http://bugs.python.org/review/5066/