[Idle-dev] Documentation on Unix/Linux / A different view

[Stephen M. Gava]

Bruce,
I've rolled my two cents worth on two of your messages into one reply here.

Bruce Sherwood wrote:
> 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.

One way you could probably help this a lot would be with a couple af simple 
step by step instruction sets or FAQ's  to guide less experienced users on 
how to set up their python environment on each linux or other *nix 
environment you care about so that it will work properly with vpython.  Or 
else look at how to integrate vpython into the python installations of the 
platforms you care about  (you could try asking people who've set up vpython 
satisfactorily on those platforms how they did it).  

I don't know that you're going to acheive the total homogeniety you desire in 
your setups for vpython on platforms different from windows without some 
work on your part to adapt your setup to varying conditions on different 
platforms.

The way python is set up on many of these platforms isn't really under the 
control of the python team themselves (the way it mostly is with windows, 
with the one big installer they release that does everything for a base 
system, even Tk), as I've tried to point out previously. In the case of Linux 
or the BSD's (Free, Open, Net)  for instance, the person who maintains the 
python packages for that platform will actually be compiling each python 
release from source with the right switches and set up in such a way that it 
will install sensibly and seamlessly into their system with its particular 
set of system libraries and locations for shared libraries etc. etc..  

The person who maintains or packages other python components (all the various 
3rd party modules, tools and libraries for instance, like numeric, or various 
database bindings or possibly vpython itself for that matter)  may not even 
be the same person who maintains the core python packages, but they would in 
each case be working to a core set of guidelines or rules or agreements on 
how these packages should all hang together with python core in on that 
platform.  What you really need to do is get in touch with the people 
packaging or porting python for each platform you have an interest in and 
find out from them how to bundle vpython so that it will fit in properly with 
the rest of python (*including the python documentation packages that are 
already available on each platform*) on that platform .

As many of these platforms have the similarity of a general "unixness" under 
the skin  (even the mac now with OSX!)  this won't be anywhere near as 
daunting as it might sound since there will be a lot of simillarities and 
variations within a relitaively low number of themes for how things are layed 
out.  It will just be a matter of exchanging a bit of email, maybe reading a 
bit of documentation or floating some questions on some mailing lists, and 
then you should be able to come up with a good set of notes and resources of 
your own on how to accomodate the platforms you are interested in.

> 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.

The best way to make things as simple as possible for the user in this case 
may be to arrange to have your vpython setup packaged (either by yourselves 
or somone else interested in supporting vpython on your target platfroms) in 
a way that is native to the packaging and software installation system used 
on that platform. For example, a correctly set up redhat .rpm for redhat 
linux (or a mandrake or suse .rpm for those rpm based distro's) a .deb 
package for debian, a port and binary package for FreeBSD, etc. etc.   That 
way the user will be installing, updating and maintaining vpython on their 
platform in just the same way they install, update and maintain the rest of 
python, and all the rest of the software on their system.  This would surely 
be the simplest solution from the users point of view as they wouldn't have 
to do anything different or non standard for vpython, just treat it the same 
as any other software they install on their system, but then this solution 
might require a little extra work on the vpython end.

> This includes packaging together
> everything the user needs to get started, which definitely includes
> documentation for Python and for VPython. 

Vpython docs sure, but why package and distribute the python documentation 
again when it's already available packaged for all the platforms python is 
packaged for, and in the same way python is on those platforms?

> 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.

Well I wouldn't actually qualify changing and entry in an .ini file as 
'hacking'.  In my discussions with Guido on idle's configuration system one 
of the reasons the 'site default' configuration is available as text based 
.ini style files is just for this purpose: so that a simple change can be 
made to the default setup to adapt to any local requirements or special or 
un-thought-of requirements.  If this wasn't a useful function that we 
expected users (meaning here administrators, or people setting up packages or 
working environments, etc.  in a standard way for others)  to actually make 
use of then it would be simpler and safer to store the default configuration 
within the program. 

> And I do see some virture in looking for local documentation, then
> reverting to the Web address if there is no local docs, 

I think this would be a good thing for idle to do on more than just windows 
too, it would just need to look in a range of the likely local places and 
then drop back to the web if it doesn't seem to be in any of them.   If it's 
somewhere non standard (say if the user just downloaded the doc tarball from 
the python site and unpacked it in a directory of their choice) then the user 
should be able to enter or overrride the location as a configuration option 
as well.  With that final fallback  *every* eventuality should be covered.

> because it will
> encourage people to make installers that include documentation.

If you're talking about the python documentation here, every packaged version 
of python also has packaged docs available.  The user may have to ask their 
install  program to install the docs as well as to install python core, but 
the python docs are always available to be installed just as easily as python 
itself was. But then I can't really think of a case where it would make sense 
for anyone to package or distribute software they expect or want others to 
use, without documentation.

On Sun, 14 Oct 2001 12:15:pm, Bruce Sherwood wrote:
> A different colleague tells me this:
> > Um, /usr/doc may not exist, and only /usr/share/doc may be present.
> > That's the way Debian is, and RH may do the same (I believe this is what
> > the FHS suggests).
>
> I'm getting conflicting signals as to whether /usr/doc or /usr/share/doc
> would be the natural/expected place to put Python-related
> documentation.....

Debian used to use /usr/doc but is moving toward /usr/share/doc as mandated 
by the FHS. If you look in /usr/doc on a recent debian system you will find 
that all the entries there are just symlinks to the actual files that exist 
in /usr/share/doc .   The FHS should result in a little more  similarity in 
the places where things are stored on linux systems over time, but it depends 
on how much the FHS is embraced or implemented by the various distros... it's 
not like there are any 'Linux Police' who are going to be making folks follow 
it.  More importantly though, as I mentionned above, because of the general  
'unixishness' of Linux there are really only a small number of ways for 
things to be sensibly set up anyway.   Don't forget though that platforms 
like the various 'libre' bds's  and other *nixes are not linux systems (and 
certainly don't want to be!)  so the FHS is completely irrelevant there 
anyway, but, the important thing is that those "unixish" similarities are 
still there in the range of possible places particular things can or should 
be on the system.

The last thing that comes to mind on the topic of 'packaging stuff for linux' 
 (*I hear you sighing with relief*)  is please don't overlook debian.  I know 
that a lot of universities and colleges (here in australia at least) set up 
debian linux by deafualt or encourage its use by their students (for a lot of 
reasons including it being the main fully non-commercial linux and therefore 
free in ALL senses [you just need an internet connection], and a darn fine 
distribution besides).  I know that they are even currently debating and 
about to put in place their new policy on python packaging on the python 
developers list there ( debian-python@lists.debian.org  ,  you can subscribe 
at  http://www.debian.org/MailingLists/subscribe  )  so that might be a good 
place to start asking quastions on how to provide a debian friendly vpython! 

Hmm, reading back over this I'm wondering if the discussion is starting to 
stray a little far from idle development...  if anyone feels it is  (and if 
you could be bothered reading this far  *L*) ,  say so and Bruce and I can 
continue the discussion in private email if he wishes.

Stephen.
-- 
Stephen M. Gava  <elguavas@users.sourceforge.net>
IDLEfork ( http://idlefork.sourceforge.net )  " just like IDLE, only crunchy "