Exact semantics of ion()??

Benjamin_Root · June 7, 2011, 11:36pm

I think my main issue is that the FAQ is not really an FAQ anymore.
There are only a few remaining questions as section headers, and some
of the "answers" are much too involved. I would think we would be
best served by a real FAQ and then separate topic-based docs that the
answers can link to (as well as having them accessible from the main
toc).

Ben Root

···

On Tuesday, June 7, 2011, Eric Firing <efiring@...202...> wrote:

On 06/07/2011 11:46 AM, Benjamin Root wrote:

On Saturday, June 4, 2011, Eric Firing<efiring@...202...> wrote:

https://github.com/efiring/matplotlib/blob/faq_show_draw/doc/faq/usage_faq.rst

Eric, Ben,

See if the section "What is interactive mode" makes sense to you. I have just added it to a feature branch (which includes some other faq madifications, mainly moving the backend section from installation to usage), but have not yet generated a pull request. It doesn't go into every detail, or into the underlying machinery. It is intended to provide just enough understanding to clear up user-level confusion about interactive mode, show, and draw, and let most relatively new users get on with their work.

Eric

Eric,

I see where you are going with this, and this is valuable information
to include in the docs. However, the interactive mode and backend info
doesn't seem to fit properly with everything else on the page. I am

I don't see why not. A FAQ is a place for answers to questions, and
this is the usage section of the FAQ, so I don't see any inherent reason
why information about backends and interactive mode, both of which
involve mpl usage, can't go there. There may be better places, to which
the FAQ could refer, but I think the FAQ is better than nothing. I
moved the backend piece from the installation part of the FAQ, where it
*really* didn't belong. (And the remaining installation part is also an
out-of-date worm jar.)

not sure where to put them yet, but I will see if I can take a deeper
look tomorrow. I also already noticed some other wording issues in
some other parts of that page.

Ben Root

What you will also find is that the section users/shell.rst, which threw
Eric L for a loop in the first place, badly needs updating, and overlaps
with what I was trying to do in the FAQ. As Eric also points out, a
section with more detail would probably be good somewhere; I was
thinking of putting that in the FAQ also, at least as a first step.

My github branch now includes a changeset with augmented docstrings for
show and draw.

Eric

_Eric_O_LEBIGOT_EOL · June 8, 2011, 8:18am

efiring wrote:

My github branch now includes a changeset with augmented docstrings for
show and draw.

Your new docstrings are a great improvement. They answer many of the
questions I have been having for years.

As for where the interactive mode/non-interactive mode discussion should be,
I think that while the mere existence of this discussion is an improvement.
I vote for moving it to a more prominent place than the FAQ, as it is about
an important, practical subject that users should be aware of quite early
when they learn Matplotlib.

Anyway, many thanks to you and Ben for devoting time to this.

···

--
View this message in context: http://old.nabble.com/Exact-semantics-of-ion()---tp31728909p31798588.html
Sent from the matplotlib - users mailing list archive at Nabble.com.

Benjamin_Root · June 9, 2011, 7:45pm

I am looking at doc/faq/installing_faq.rst on your branch, and I can’t tell what is out-of-date (although the Mac part might be, I don’t know). If you are referring to doc/users/installing.rst, that should have been removed in the big set of commits I made recently when I merged from v1.0.x-maint to master (the INSTALL file is now used in master for the installation docs).

The problem I do see with installation_faq.rst is that the section titles are not questions, but that is a minor issue here.

Ben Root

···

On Tue, Jun 7, 2011 at 5:01 PM, Eric Firing <efiring@…2015…02…> wrote:

On 06/07/2011 11:46 AM, Benjamin Root wrote:

On Saturday, June 4, 2011, Eric Firing<efiring@…202…> wrote:

https://github.com/efiring/matplotlib/blob/faq_show_draw/doc/faq/usage_faq.rst

Eric, Ben,

See if the section “What is interactive mode” makes sense to you. I have just added it to a feature branch (which includes some other faq madifications, mainly moving the backend section from installation to usage), but have not yet generated a pull request. It doesn’t go into every detail, or into the underlying machinery. It is intended to provide just enough understanding to clear up user-level confusion about interactive mode, show, and draw, and let most relatively new users get on with their work.

Eric

Eric,

I see where you are going with this, and this is valuable information

to include in the docs. However, the interactive mode and backend info

doesn’t seem to fit properly with everything else on the page. I am

I don’t see why not. A FAQ is a place for answers to questions, and

this is the usage section of the FAQ, so I don’t see any inherent reason

why information about backends and interactive mode, both of which

involve mpl usage, can’t go there. There may be better places, to which

the FAQ could refer, but I think the FAQ is better than nothing. I

moved the backend piece from the installation part of the FAQ, where it

really didn’t belong. (And the remaining installation part is also an

out-of-date worm jar.)

Eric_Firing1 · June 9, 2011, 9:20pm

     >>
    https://github.com/efiring/matplotlib/blob/faq_show_draw/doc/faq/usage_faq.rst
     >>
     >> Eric, Ben,
     >>
     >> See if the section "What is interactive mode" makes sense to
    you. I have just added it to a feature branch (which includes some
    other faq madifications, mainly moving the backend section from
    installation to usage), but have not yet generated a pull request.
      It doesn't go into every detail, or into the underlying machinery.
      It is intended to provide just enough understanding to clear up
    user-level confusion about interactive mode, show, and draw, and let
    most relatively new users get on with their work.
     >>
     >> Eric
     >>
     >
     > Eric,
     >
     > I see where you are going with this, and this is valuable information
     > to include in the docs. However, the interactive mode and backend
    info
     > doesn't seem to fit properly with everything else on the page. I am

    I don't see why not. A FAQ is a place for answers to questions, and
    this is the usage section of the FAQ, so I don't see any inherent reason
    why information about backends and interactive mode, both of which
    involve mpl usage, can't go there. There may be better places, to which
    the FAQ could refer, but I think the FAQ is better than nothing. I
    moved the backend piece from the installation part of the FAQ, where it
    *really* didn't belong. (And the remaining installation part is also an
    out-of-date worm jar.)

I am looking at doc/faq/installing_faq.rst on your branch, and I can't
tell what is out-of-date (although the Mac part might be, I don't
know). If you are referring to doc/users/installing.rst, that should
have been removed in the big set of commits I made recently when I
merged from v1.0.x-maint to master (the INSTALL file is now used in
master for the installation docs).

Ben,

I am referring to doc/faq/installing_faq.rst, and I am mainly concerned about the OS-X section. The version references are clearly out of date; as for the rest, I have no idea what actually works and should be recommended. Attempts have been made elsewhere in mpl to update and clarify the OS-X build and install situation, but I don't think any of that is reflected in this faq section, and I would not be surprised if there are other places in the overall mpl tree where OS-X confusion still lurks. Certainly the mailing list indicates that OS-X installation and building has been a frequent sore point. Although I have built and installed mpl on an OS-X machine, I don't normally use one, and I certainly don't understand all the arcane variables and variations.

In OS-X and elsewhere I would also raise the question: does easy-install have a high enough success rate with mpl that it should be included as a reasonable option? Or should its use for mpl be discouraged? I don't know the answer, and have never tried easy-install with mpl, but in general I don't trust it. Too much behind-the-scenes magic.

And the users/installing.rst has problems, too, in addition to the general problem of information about building and installing being scattered among the users section, the faq, INSTALL, make.osx, and setup*. Small example: installation requirements are listed under the heading "Build requirements".

Progress is going to have to be incremental; I doubt that anyone will have the time to go through the whole system and really clean everything up in one pass.

I suggest, if you don't mind, that I go ahead and merge my branch into maint (and from there, master), and then the next increment, whether by you, me, or someone else, can be in a new branch, and the process can be repeated.

Eric

···

On 06/09/2011 09:45 AM, Benjamin Root wrote:

On Tue, Jun 7, 2011 at 5:01 PM, Eric Firing <efiring@...202... > <mailto:efiring@…202…>> wrote:
On 06/07/2011 11:46 AM, Benjamin Root wrote:
> On Saturday, June 4, 2011, Eric Firing<efiring@...202... > <mailto:efiring@…202…>> wrote:

The problem I do see with installation_faq.rst is that the section
titles are not questions, but that is a minor issue here.

Ben Root