Re: [PyX-user] remarks on usability

[Francisco B. <bo...@le...>]

Hello all,

sorry for the delayed answer (I've been away).

=BB On Fri, Dec 17, 2004 at 09:05AM +0100, Andre Wobst wrote:

> the same problem as well. My solution is to just keep old versions
> around to be able to recreate old figures instead of always porting

I keep the eps of everything I need and in principle I did rather port
it to the current version, but I guess for small changes that might be
useful.

> in mind. That's bad, actually. We'll also have to remove some examples
> in the future and clean up the rest make them a better value to the
> users.

I think a `showroom` like example page is very good, I've myself used
the example pages very much while talking about pyx to other people.

> > I would greatly appreciate if there were examples in the docs
> > themselves. You don't need to include a throughout example but just a
> > line or two showing how to use the particular class instance being
> > described.
>
> Well, we're trying to provide a reference manual, not a users manual.

Glad you mentioned it. I guess the problem was that by reading "Manual"
at the "/documentation.html" page, I expected a users manual ;-) I guess
that's where most of my problems came from.

I think it would be better to write down "Reference manual" in that
page, most people will hit "Manual" expecting a "Users manual".

> Sure we could start to add code snippets in class descriptions. But I
> think, showing that you can say "graph.style.line([color.rgb.red])"

Is there a place where one can check which are all the styles that apply
to lines (or symbols)? (color, width, ?)

Hitting [TAB] at the interpreter gives me things like:

"graph.style.line.changecircletwice".... I don't think it applies to
lines themselves (Right??).

Width and color are also represented in people's heads as "styles" but
are not listed anywhere near

class line(lineattrs=3D[])

which is the entry for "lines" in the "style" page. It might be the case
that all info is in the manual but its way too fragmented. There should
be exaustive listings of what may changed on symbols, lines etc:

"""
Lines can be changed regarding:

Width;
Color;
style (e.g. dashed, solid etc).
"""

It would help people to have a mental image of what may be changed
without having to go through the whole thing (and all small variants of
style).

> constructor is not that helpful, since those "examples" could be
> written all over the place. In the end it will not at all improve the
> situation.

IMHO an example of how to use change(circle|diamond|etc)twice or any of
the changeable symbol functions would help a lot people reading that
page.

> contribtions. What do you think about a hackish solution like in
> http://pydoc.amk.ca/frame.html? (I do know, that this does not work
> with all browsers ... in safari for example it does not work.) Should
> we do something like that?

That should definitely make it easier to give sugestions but this should
only have a real start once there is a real users documentation
section.

I would expect most users to have suggestions that, most of the time,
would mean turning the reference manual into a users manual. Perhaps
that's not what you want, I don't know.

          ----------------------------------

One thing I forgot to mention: the lack of doc strings in pyx.

Wouldn't it be better if all pertinent reference manual text could be
found as doc strings e.g.:

ipython: graph.style.line?[RET]

"""bla bla bla"""

and retrieved by a script to compose the reference manual?

[ On the other hand that would be annoying to change and would give you
a lot of trouble (making links in the text). ]

           ----------------------------------

peace,
--=20
Francisco Borges
Alfa Informatica - RuG