Terry J. Reedy added the comment: Ned, Thank you for the turtledemo doc location. I opened #21971 to add it to the module and general indexes and update it with respect to the two_canvases demo.
Neither Idle nor idlelib are in the modules index. The main link for IDLE in the general index goes to the glossary entry. Could that entry have a link to the doc section? The x.y docs do not describe 'Idle x.y' because there is no 'Idle x.y'. There was, for instance, 'Idle 3.4.0', there is now 'Idle 3.4.1', and there will be 'Idle 3.4.2'. There may not have been any doc-worthy changes in 3.4.1, but I expect there will be in 3.4.2 (and 2.7.9). This reality is the basis of and the reason for this issue and #21621 (which I will come back to). What is the idle section of the repository and online doc supposed to document? To the best of my knowledge, this has not been discussed, nor any policy written. However, I think the repository doc should be synchronized with the repository code, which would mean documenting unreleased new features. As far as I know, the current version is an html version of idlelib/help.txt as of 1.5 or more years ago. I have not checked to see if it includes any details that have changed. The current doc does not have any version-added, or in Idle's case, release-added notes. Assuming that there is something new since 3.0.0 should it? I don't think so. If someone conditionally includes a 3.4 feature in 3.3 code, the problem might show up years later. If someone tries to use an Idle feature in a version that lacks it, they won't find it. I think a focused feature log such as proposed in this issue is a better place for release-added update notes. Having two sources copies of the Idle docs is a nuisance. I would not mind either getting rid of help.txt or replacing it with help.html captured on the release date, and included as a back up for people who do not have web access at a particular time and place. There is an issue for this already. As for the update notes. In #21621, I proposed copying the boilerplate announcement in the 2.7 What's New to 3.x. I got no feedback that this is acceptable. In the meanwhile, I have realized that people need the sort of re-written update notes for the rest of the stdlib that currently comprise What's New. I would be happy to put them in What's New itself, as part of patches that add the feature and update the manual. I would then add an option to Help to access the online section of What's New. Nick, is updating the Idle section of What's New during the maintenance cycle, with per release notes, OK with you? #17506 was partly about the fact that Idle NEWS items sometimes (always since 3.4.1) do not merge forward properly. That is a separate issue from this one. ---------- nosy: +ncoghlan _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue21961> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
