classification
Title: IDLE documentation for Unix obsolete/incorrect
Type: behavior Stage: resolved
Components: Documentation, IDLE Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Todd.Rovito, ajaksu2, asvetlov, docs@python, eric.araujo, ezio.melotti, georg.brandl, gpolo, jesstess, orsenthil, python-dev, ramiroluz, roger.serwy, steven.daprano, terry.reedy, zach.ware
Priority: normal Keywords: easy, patch

Created on 2009-01-26 03:56 by steven.daprano, last changed 2013-01-14 17:28 by asvetlov. This issue is now closed.

Files
File name Uploaded Description Edit
issue5066.patch jesstess, 2010-11-08 00:19 update IDLE menu option descriptions review
5066IDLEocumentationforUnixObsoleteIncorrect.patch Todd.Rovito, 2012-11-27 05:11 review
5066IDLEocumentationforUnixObsoleteIncorrectVersion2.patch Todd.Rovito, 2012-11-28 01:14 review
5066IDLEocumentationforUnixObsoleteIncorrectVersion3.patch Todd.Rovito, 2013-01-08 05:06 review
5066IDLEocumentationforUnixObsoleteIncorrectVersion4.patch Todd.Rovito, 2013-01-09 05:29 review
Messages (30)
msg80562 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2009-01-26 03:56
Documentation for IDLE states:

    Starting IDLE on UNIX 
    On Unix, just type "idle" at a command prompt. This should bring
    up a Window similar to the one above. (If it doesn't, look for
    the "idle" script in the Tools/idle directory in the Python source
    distribution.)

http://www.python.org/idle/doc/idlemain.html

I believe that is obsolete, I cannot see a Tools/idle directory in 
either 2.5 or 2.6. Perhaps better instructions might be:

    (If it doesn't, run "python LOC/idlelib/idle.py" where LOC 
    is the location of your Python source distribution, usually 
    /usr/lib/python*.)

or similar.
msg80595 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2009-01-26 21:41
LOL. That doc was apparently last revised in 2000 for the IDLE released
with 1.5.2 (see screenshot).  Other needed updates I see are: 'Shell'
and 'Options' have been added to the menu line; we now have unicode
text; screenshots look different (and nicer) on newer Tk on WinXP and
could/should be redone.

If it were decided to update this and add it to the doc package, I would
help in some way.
msg81200 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-02-05 10:57
Well, having nice full docs for IDLE would be nice, but I won't do
anything on this matter except committing a full patch :)
msg81227 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2009-02-05 20:29
Is there an HTML to acceptable RST converter?
msg81268 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-02-06 13:50
I don't know any. But since rst is so lightweight, it is usually not too
much of a pain to just copy the text from the browser and reintroduce
formatting because you're likely to have to go over and edit the whole
content anyway.
msg86622 - (view) Author: Daniel Diniz (ajaksu2) Date: 2009-04-26 22:18
This looks like a perfect match for GHOP.
msg120698 - (view) Author: Jessica McKellar (jesstess) * Date: 2010-11-08 00:19
Attached is a patch updating the IDLE web documentation as well as the help file displayed when you click the Help -> Idle Help menu item in IDLE. It looks like the IDLE web documentation was lifted directly from the help file at some point and they have gotten out of sync.

The section of the document describing starting IDLE was updated in March of 2009, so I've left that alone. I've updated the Menu option descriptions in both files, including: adding missing items, making the help file and web document descriptions the same, and using a consistent format.

The patch is against release27-maint.
msg121743 - (view) Author: Ramiro Batista da Luz (ramiroluz) Date: 2010-11-20 19:53
I reviewed the texts, applied the patches, ran idle, edited Demo/classes/Dates.py run module inside Idle. Generated the docs inside Doc, with make html and reviewed the IDLE doc in ~/python/py3k/Doc/build/html/library/idle.html?highlight=idle

Only in the 3.2 tree.
msg176326 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-11-25 01:09
This is a good patch but it is rather out of date and won't apply.  I will patch the patch and maybe somebody can apply it this time.  Expect a new patch by 11/26/2012.
msg176462 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-11-27 05:11
This patch is an extensive refactoring of help.txt and idle.rst. The first thing I did was merge issue5066.patch from jesstess into the current idle.rst file, because the original patch from jesstess was so old it had to be merged by hand into the 3.4 source code.  Then I compared what the merge document said with the actual menus of IDLE and made several corrections because of missing menu options.  Finally I refactored the help.txt based on idle.rst and created the resulting patch. Several capitalization's were fixed along with many inconsistencies between the two files.  

I have not tested on 2.7 only 3.4.  My plan is to test with 2.7 and create another patch by end of the week 12/2/2012.
msg176463 - (view) Author: Roger Serwy (roger.serwy) * (Python committer) Date: 2012-11-27 05:27
The original help.txt and the patched version still mixes tabs and spaces. This is a minor point, but perhaps all the tabs should be expanded.

Also, the section on running IDLE without a subprocess should not be removed until version 3.5. See #16123.
msg176503 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-11-28 01:14
Version 2 of the patch change include:
-help.txt removed all tabs and replaced with spaces, as suggested by Roger
-help.txt re-inserted the section on running IDLE without a subprocess as suggested by Roger
-Added a note on line 162 (idle.rst) about how the Python Community standard is to use spaces and not tabs as suggested by ezio
-Line 340 (idle.rst) where the Emacs bindings are rendered seemed to work fine on my computer without the spaces but I think ezio is correct spaces should be present so I added them
-Line 354 (idle.rst): are restricted to four spaces due to TCL/Tk issues.)s/issues/limitations/ so I replaced issues with limitations

Thanks for the feedback Roger and ezio!
msg176504 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-11-28 01:19
For version 2 of the patch 
-Line 340 (idle.rst) where the Emacs bindings are rendered seemed to work fine on my computer without the spaces but I think ezio is correct spaces should be present so I added them

******SHOULD BE******
-Line 340 (idle.rst) where the Emacs bindings are rendered seemed to work fine on my computer without the empty line between entries but I think ezio is correct empty lines should be present so I added empty lines just to be safe
msg179033 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-01-04 15:41
A "ping" on this bug since it has not had any forward movement.  Can somebody please review and or commit?  Thanks.
msg179059 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-01-04 18:07
Hi Todd, I can't commit, but I have a review in the works for you.
msg179072 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-01-04 19:36
Thanks much appreciated!

Sent from my iPhone

On Jan 4, 2013, at 1:07 PM, Zachary Ware <report@bugs.python.org> wrote:

> 
> Zachary Ware added the comment:
> 
> Hi Todd, I can't commit, but I have a review in the works for you.
> 
> ----------
> nosy: +zach.ware
> 
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue5066>
> _______________________________________
msg179266 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-01-07 14:41
I wonder, is there any really good reason to keep a separate Lib/idlelib/help.txt, or can Doc/library/idle.rst be used for its purpose (with or without a small amount of processing to, for instance, remove comments and extra backslashes)?  Both have most of the same information, and reST is designed to be readable anyway, so I don't see much point in keeping them separate.
msg179279 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-01-07 20:03
Zachary,
   I like your idea about joining idle.rst with help.txt but I think that should be covered under a separate bug issue.  The way I see it this bug is about fixing the current documentation.  So I suggest you open up a new issue and get people's take on it.  I think a parser could be run at installation to convert idle.rst to help.txt or maybe IDLE could be modified to simply render idle.rst correctly.  I am not sure what the best approach will be.

PS Thanks for the review I should have your suggested changes integrating into a new patch today.
msg179280 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-01-07 20:20
Right you are, Todd; I'll get another issue opened for that soon.
msg179312 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-01-08 05:06
Zachary,
   Thanks for your excellent review!!!!  Your feedback was very helpful for making the patch even better.
msg179313 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-01-08 05:08
Based on Zachary's comments I have uploaded a new version of the patch which is version 3.
msg179348 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-01-08 13:03
Idle needs to find its text help files at runtime, so they are installed as data alongside with the code.  The rst doc files however can be installed anywhere or not installed at all, so we can’t change Idle to look for them.

An alternate idea to avoid duplication could be to copy the rst file to the code directory at build time.
msg179359 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2013-01-08 15:51
Regardless of the topic of merge, the suggested improvements for both idle.rst and help.txt are great! Thanks for working the patch, Todd.
I am +1 with the changes. If no else has any comments, I can go ahead with committing this.
msg179360 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-01-08 16:12
I'd like to see Éric, Ezio, and my comments on v3 in Rietveld addressed, but after that I'm good with it :)
msg179363 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-01-08 16:45
Issue 16893 has been filed to deal with the idea of merging the files.
msg179406 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-01-09 02:30
Thanks Senthil but I don't deserve all the credit this issue is a team effort with lots of help from Zach, Éric, and Ezio.  All of which have improved the patch's quality a great deal.  Hopefully we can address the issues then let you make the commit soon.
msg179409 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-01-09 05:29
I took all the comments and created a new patch version 4 which should address all the issues.  Thanks for the excellent review and support from everybody.  I think this patch is a much higher quality now.
msg179446 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-01-09 14:45
Version 4 looks good to me!
msg179957 - (view) Author: Roundup Robot (python-dev) Date: 2013-01-14 17:27
New changeset d1ef91025d70 by Andrew Svetlov in branch 'default':
Issue #5066: Update IDLE docs
http://hg.python.org/cpython/rev/d1ef91025d70
msg179958 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2013-01-14 17:28
Pushed. Thanks.
History
Date User Action Args
2013-01-14 17:28:16asvetlovsetstatus: open -> closed
resolution: fixed
messages: + msg179958

stage: patch review -> resolved
2013-01-14 17:27:48python-devsetnosy: + python-dev
messages: + msg179957
2013-01-09 14:45:16zach.waresetmessages: + msg179446
2013-01-09 05:29:19Todd.Rovitosetfiles: + 5066IDLEocumentationforUnixObsoleteIncorrectVersion4.patch

messages: + msg179409
2013-01-09 02:30:50Todd.Rovitosetmessages: + msg179406
2013-01-08 16:45:35zach.waresetmessages: + msg179363
2013-01-08 16:12:23zach.waresetmessages: + msg179360
2013-01-08 15:51:20orsenthilsetnosy: + orsenthil
messages: + msg179359
2013-01-08 13:03:59eric.araujosetnosy: + eric.araujo
messages: + msg179348
2013-01-08 05:08:50Todd.Rovitosetmessages: + msg179313
2013-01-08 05:06:53Todd.Rovitosetfiles: + 5066IDLEocumentationforUnixObsoleteIncorrectVersion3.patch

messages: + msg179312
2013-01-07 20:20:07zach.waresetmessages: + msg179280
2013-01-07 20:03:09Todd.Rovitosetmessages: + msg179279
2013-01-07 14:41:54zach.waresetmessages: + msg179266
2013-01-04 19:36:31Todd.Rovitosetmessages: + msg179072
2013-01-04 18:07:45zach.waresetnosy: + zach.ware
messages: + msg179059
2013-01-04 15:41:27Todd.Rovitosetmessages: + msg179033
2012-11-28 01:19:10Todd.Rovitosetmessages: + msg176504
2012-11-28 01:15:00Todd.Rovitosetfiles: + 5066IDLEocumentationforUnixObsoleteIncorrectVersion2.patch

messages: + msg176503
2012-11-27 05:27:31roger.serwysetnosy: + roger.serwy
messages: + msg176463
2012-11-27 05:11:41Todd.Rovitosetfiles: + 5066IDLEocumentationforUnixObsoleteIncorrect.patch

messages: + msg176462
versions: + Python 3.4, - Python 2.7, Python 3.2, Python 3.3
2012-11-25 01:09:00Todd.Rovitosetmessages: + msg176326
2012-11-24 20:46:12Todd.Rovitosetnosy: + Todd.Rovito
2012-03-21 11:56:40asvetlovsetnosy: + asvetlov
2011-11-19 14:05:36ezio.melottisetnosy: + ezio.melotti
stage: needs patch -> patch review

versions: + Python 3.3, - Python 3.1
2010-11-20 19:53:06ramiroluzsetnosy: + ramiroluz
messages: + msg121743
2010-11-20 18:32:03eric.araujosetassignee: docs@python

nosy: + docs@python
2010-11-08 00:19:09jesstesssetfiles: + issue5066.patch
versions: + Python 2.7, Python 3.2, - Python 2.6, Python 3.0
nosy: + jesstess

messages: + msg120698

keywords: + patch
2009-04-26 22:18:18ajaksu2setpriority: normal

type: behavior
versions: + Python 2.6, Python 3.0, Python 3.1
keywords: + easy
nosy: + ajaksu2, gpolo

messages: + msg86622
stage: needs patch
2009-02-06 13:50:12georg.brandlsetmessages: + msg81268
2009-02-05 20:29:18terry.reedysetmessages: + msg81227
2009-02-05 10:57:55georg.brandlsetassignee: georg.brandl -> (no value)
messages: + msg81200
2009-01-26 21:41:15terry.reedysetnosy: + terry.reedy
messages: + msg80595
2009-01-26 03:56:57steven.dapranocreate