On Tue, Mar 8, 2011 at 1:18 PM, Eric Firing <efir...@hawaii.edu> wrote:
> On 03/08/2011 08:08 AM, Benjamin Root wrote:
> > Hello all,
> >
> > I have a free day today, so I am going through some of the documentation
> > and giving it a good polish. I came across one particular part that is
> > sorely outdated:
> >
> > http://matplotlib.sourceforge.net/faq/howto_faq.html#use-show
> >
> > This is in regards to the show() function and tells users that it can
> > only be used once in a script. By and large, this is no longer true,
> > but I want to make sure that I don't give bad information here. Is
> > there someplace else in the docs where this information is current that
> > I can use for revising this section?
>
> Not that I know of.
>
> Because readers of the docs online may be running any of a range of mpl
> versions, you will need note how show() usage and behavior have evolved.
> The advantage of the old faq, outdated though it is, is that it won't
> mislead users of old mpl versions, and following its advice will still
> work for users of the current version.
>
>
Good point. I hadn't thought of that.
> New behavior, or at last the target: show() starts a GUI mainloop if it
> is not already running, and draws everything. If mpl is in
> non-interactive mode, it then blocks until the newly opened windows have
> been closed; if it is in interactive mode, it does not block. (The
> macosx backend does not have a non-interactive mode.) In either case,
> when things are working right, there is no restriction on multiple calls
> within a script or a shell session.
>
> Note: Michiel deHoon is working on changes to master (code and docs) so
> that mpl will come up in interactive mode by default, instead of the
> present non-interactive default. The code change is trivial; the larger
> challenge is how to explain everything in the docs, while not confusing
> users of older versions.
>
The whole gui situation, with all the possible combinations of
> environment (ipython in its different versions, idle, etc.), mpl
> backend, other packages that might be used in conjunction with mpl (e.g.
> mayavi) and platform, is still unsettled. The big change was from the
> 0.9x series to 1.x series; some problems were sorted out between 1.0 and
> 1.0.1. More work in this area will be needed now and then.
>
> All of this raises a question: can we move to clear versioning of the
> online docs, as with python itself, so that a user of 0.99.x won't be
> frustrated by an example or explanation that applies only to 1.0.x? Or
> can we be sufficiently careful to keep explanations of version
> differences in the evolving docs? These are not mutually exclusive, and
> the latter is particularly useful. For example, when using python 2.6
> it is nice to be able to look at the docs and see that a feature was
> introduced in that version, so it won't be available on one's machines
> running 2.5. I think we now need to follow that practice in the mpl
> docs, or at least try to do so.
>
>
I have personally had to field several questions from users of older mpl who
tried the new way of creating 3d axes on their systems. Unfortunately, when
I created the documentation, I completely removed all traces of the old
method, forgetting that some users will have difficulty with those
instructions.
Today, my goal is mostly polishing work. I will try and see if I could make
some explanations more version-agnostic or to specifically point out
differences in versions.
I personally see a lot of value in providing multiple versions of the docs
(maybe supported - 1 releases back?).
> And on the topic of the docs, if anyone has time for a bigger project:
> it would be nice if the gallery could be *organized* in some systematic
> way, so that a user could more easily use it to find a needed feature.
> And as always, it would be nice to have the gallery examples cleaned up
> with respect to code and comment style, and edited to remove things that
> really are no longer of interest and to more clearly demonstrate features.
>
>
I can see about doing some of this tomorrow if it turns out I have another
free day...
Ben Root
------------------------------------------------------------------------------
What You Don't Know About Data Connectivity CAN Hurt You
This paper provides an overview of data connectivity, details
its effect on application quality, and explores various alternative
solutions. http://p.sf.net/sfu/progress-d2d
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
