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. 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. 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. Eric > > Thanks, > 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
