RE: [Axiom-developer] point-sets and help systems

[Page, Bill]

On Wednesday, June 29, 2005 4:32 AM Bob McElrath wrote:

> How do I generate a point-set from a graph?
>
> e.g. draw(sin(x), x=0..6.28)
> but I want a point-set instead of the graphics interface.

For more technical information take a look at

 axom--main--1/src/graph/fileformats.pamphlet

\author{The Axiom Team} (aka. Tim Daly, the optimist :) has
made a good start at describing the "point set" data that is
passed from Axiom to the graphics processor.

> How can I find this out for myself, aside from poring through
> the code/axiom book?
>
> For comparison, it took about 5 minutes to construct this
> in maxima:
>
>    makelist(float([x*%pi/100,sin(x*%pi/100)]),x,0,200);
>

What part of the maxima user interface contributed to making it
possible for you to find the necessary information? Your view
as a *user* is very important. So often the people who develop
complex systems devote almost no effort to making the system
easy to use - after all they know exactly how to use it. But
somebody new walking up to the system for the first time will
see something entirely different. It is very useful to harness
their energy and bottle it for others, e.g. that's why so many
open source software projects are waiting and hoping that new
users will actually produce documentation in return for free
access to the software. The web site wiki interface was supposed
to enable this - and it has worked in a few cases.

Unfortunately it seems that most people who came to work on Axiom
for the first time were often already caught up in intricate details
of heir own complex project or PhD thesis or whatever and didn't
have much time to devote to user interface.

Of course as you point out below, the Axiom hyperdoc project
was an early attempt to solve this problem.

> After 3 hours I finally figured out how to do it in axiom. 
> (I don't give up that easily...)
>
>    [[sin(i*%pi/100)$Float, i*%pi/100] for i in 1..200]
>

You should get an "A" for that solution, but I'll give you an "B"
(: You'll get the rest of your mark when you add a paragraph to
the wiki site explaining how it works. See something near:

http://page.axiom-developer.org/zope/mathaction/Streams

Email doesn't really count since someone else (some day, if ever)
will have to mine the list of useful tid-bits like this. You
are done once a quick search with a couple of likely keywords
returns your example and explanation.

> And the moral of the story is...hyperdoc is where the documentation
> is. This should be made obvious from the command line.

Hmmm, well if I type

  axiom

from the Linux shell I do get hyperdoc right up front. You mean
you also need a reminder from the Axiom command line?

> Virtually any attempt at getting help from the command line
> sends me on a wild goose chase of ')what op' ')display op'
> ')help' etc.

Actually you are right. As I consider myself a more experienced
(and impatient) user I almost never start Axiom with hyperdoc and
I have to remind myself that it is available for questions like
these. I would be nice if typing

  )help

actually launched hyperdoc, instead of the other way around.

> Would it be possible to hide all that and not present it to
> the user as if it was a working help system?  The 3-hour wild
> goose chase I just went on will deter 99% of users right off
> the bat.

I agree with this. In fact I think this is one reason why the
AxiomUI project should have such a high priority. Hyperdoc is
not available for the Windows users of Axiom - where a lot of
these sort of questions are most like to be asked - and even
on Linux the old hyperdoc browser (useful though it is!) looks
old, unapproachable and basically just ugly by today's standards.

One thing that I always wanted to do but never found time was
to extract just the HTML-able and LaTeX-able parts of the hyperdoc
pages and make them available as essential static pages on the
Axiom web site. As documentation this would be great even though
it would be missing most of the dynamic browser features that
depend on the Axiom database to define the relationships between
algebra components. Of course it would be possible to load the
Axiom database itself in some from accessible to a web site. This
would also be a major part of the new stand alone AxiomUI browser,
so efforts to convert the hyperdoc pages (using one of the
tex-to-html tools) could serve two purposes: stand alone and
online Axiom web site support. Mostly what we have to decide
is how to implement the navigation in an HTML friendly manner.

BTW, when you were spending your 3 hours learning this lesson,
did you happen to think of doing a search on MathAction?

Regards,
Bill Page.