Author ned.deily
Recipients Todd.Rovito, asvetlov, docs@python, eric.araujo, georg.brandl, ned.deily, roger.serwy, terry.reedy, zach.ware
Date 2013-04-01.10:50:34
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1364813436.33.0.197236566515.issue16893@psf.upfronthosting.co.za>
In-reply-to
Content
Zach, thanks for addressing most of the comments. The Makefile does now work as intended and more information is retained in the help.txt.

But I'm still troubled by the plaintext rendering, particularly of the inline code markup.  With the `` marks from the reStructuredText directives appearing in the help.txt, the help file as displayed is, IMO, more cluttered and, more importantly, more confusing.  Using `` to delimit displayed plaintext in lieu of more sophisticated text styling is unconventional at best.  I think changing the help file to include such marks would be a step backward.  But that's just one of the more obvious drawbacks of trying to use a plaintext format for help.

Ironically, the Tk text widget is perfectly capable of rendering richer text styles.  But, AFAIK, there hasn't been a use case up to now to support some sort of rich text format (be it rtf or html or rst directly) from a file in IDLE.  My initial thought was to suggest adding some sort of Tk-friendly Sphinx/Docutils builder.  That might be more generally useful but that will probably take a fair amount of work to define and implement.  Then it struck me that having an html-format help file would be able to represent all the existing Sphinx styles and, with the doc changes in the patch, we already have an html file that contains all the help text!  So rather than trying to sync the help file with the IDLE doc in the library, why not just display the library IDLE doc in a browser window?  IDLE already has a menu item and code to launch a web browser for the whole Python documentation set.  It would be easy to adapt that to change the IDLE help menu item to launch a web browser window with the IDLE page and get rid of help.txt.

There are a few issues that would need to be resolved.  The python.org binary installers and most Unix-y distributions can optionally install local copies of the Python doc set to eliminate the need for network access to docs.python.org.  There is platform-specific code in EditorWindow.__init__ to search locally for the doc files, falling back to http://doc.python.org if a local copy is not found.  The simplest approach would be to do the same for IDLE help, however that would have the drawback of there being no help available if the local copy had not been installed and there was no internet access.  Of course, that is the case today for the Python documentation.  If that is not acceptable for the help text, the docs build process could make a copy of a version of the library/idle.html into idlelib or, less desirable, the proposed plain text file could be the fallback.  Also, on Windows, AFAIK, the doc set is usually installed as a chm file which normally opens to the top-level index page in the help viewer.  A question is how to open directly to the IDLE page.  By inspection in the help viewer on Windows 7, it seems that a web browser.open call to a URL that appends '::/library/idle.html' to the existing pythonxxx.chm URL will open a browser window to the right page.  But there may be a better way to do that.

From the user's perspective, ISTM that having the help in the rich format possible with the existing doc html would be a huge advantage over what can be provided with any plain text format.  Comments?
History
Date User Action Args
2013-04-01 10:50:36ned.deilysetrecipients: + ned.deily, georg.brandl, terry.reedy, roger.serwy, eric.araujo, asvetlov, docs@python, Todd.Rovito, zach.ware
2013-04-01 10:50:36ned.deilysetmessageid: <1364813436.33.0.197236566515.issue16893@psf.upfronthosting.co.za>
2013-04-01 10:50:36ned.deilylinkissue16893 messages
2013-04-01 10:50:34ned.deilycreate