[IPython-dev] [IPython-user] On Eggs and the striping of docs & examples

[Fernando Perez]

Ville Vainio wrote:
> On 1/25/06, Fernando Perez <Fernando.Perez at colorado.edu> wrote:
> 
> 
>>Actually, if we were more systematic in making sure that all magics had a true
>>one-line description (I think most do, but not all), the quickref could
>>summarize these.  Kind of what 'magic' does, but just printing the first line.
>>  That would be useful.
> 
> 
> Yeah, that compounded with quick runover of prefix characters; sounds
> like a plan.

Good.

> I've also thought of hiding/undocumenting some magics (pdoc, psource)
> etc.; ? notation is probably what people will use anyway.

No, don't.  There are users of this stuff out there.  These folks

http://casa.nrao.edu/demo1.shtml

have gone as far as documenting it in their tutorials.

The stable branch should live up to its name: let's not break backwards 
compatibility unless there is a _strong, compelling_ reason to do so. 
Convenience, cleanup, tidyness, are NOT strong and compelling.

That's the price of having established users, I'm afraid: IPython has a 
reasonably large user base, and there are various institutions which have 
built their interactive control environments using ipython as the engine. 
This is _exactly_ what I'd always wanted, but for such users any kind of 
gratuitous breakage with new versions is likely to be very unwelcome.  Let's 
not do it unless it's _really_ necessary.

The other things you've been doing, like adding new features, or exposing old 
crufty internals with a cleaner interface (the ipapi stuff) are all very 
welcome even by such users, as it gives them new ways of doing things better. 
  But at this point, we really need to avoid any break in backwards 
compatibility as much as possible.

Cheers,

f