[Idle-dev] Documentation on Unix/Linux

[Bruce Sherwood]

Very interesting comments, Stephen, including your comments about OSX. We 
really do need good competition in operating systems!

In the VPython user community I asked where people put documentation and 
was told that on Debian systems documentation is in /usr/doc, and that 
/usr/share/doc is more oriented to user-generated documentation. It appears 
that normally there is no /usr/doc on RedHat, but it would seem to make 
sense to have such a directory (I'm prepared to learn that I'm just 
ignorant on this, though!).

Currently EditorWindow.py sets help_url = 
"http://www.python.org/doc/current/", then if on Windows it checks for 
local documentation at ../../Doc/index.html and resets help_url to the 
local address. If the local documentation is not available, help_url still 
points to the Web.

I'd like to semi-propose similar code for Linux and Mac. For example, if on 
Linux, look for /usr/doc/Python21/index.html. That would encourage people 
to create Linux packages that include documentation, with easy access from 
Idle.

I offer this semi-proposal for discussion in the following context. 
Although I commented that Linux users are sophisticated and typically 
can/do put together their own customized set of resources, in the VPython 
community we've met a number of users who are relatively new to Linux, 
typically RedHat (because it is the best advertised), and they have 
significant difficulties putting together a workable VPython environment. 
This includes some of our own college freshmen. Over the last year we've 
learned a lot, experimentally, about what makes an installer for Windows 
robust against novice user actions and expectations. We'd like to exploit 
this to make a robust installer for Linux. This includes packaging together 
everything the user needs to get started, which definitely includes 
documentation for Python and for VPython. (It also means that asking for 
help in Idle should offer a small list: help on Idle, help on Python, help 
on VPython.)

It is of course true that we can hack EditorWindow.py (or some 
configuration file) for our own installer, but the fewer hacks the better. 
And I do see some virture in looking for local documentation, then 
reverting to the Web address if there is no local docs, because it will 
encourage people to make installers that include documentation.

This is a small point, so I don't want to push it too far. Perhaps more 
important are the experimental data that we do encounter Linux users who 
are not enormously facile with Linux (yet), and would benefit from more 
inclusive installers.

Bruce Sherwood