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

[Page, Bill]

On Wednesday, June 29, 2005 4:34 PM Bob McElrath wrote:

> ...
> Bill Page wrote: 
>> What part of the maxima user interface contributed to making
>> it possible for you to find the necessary information? 
>
> 'describe(makelist)'.  In particular, there is no equivalent in
> axiom to answer the question "what does this function/class/domain
> *do*"?

Yes, you are right. I would have thought that at least the
command

  )display op ...

would include the ++ documentation lines from the SPAD files.
Maybe these are even in the database (daase) files? 

> However the user is presented with several opportunities which
> might seem to lead to an answer by the right combination of
> )what op, )display op, etc. that are totally opaque.

Well, I would agree with "marginally useful" maybe. :)

> Can someone replace the default help page for the next release?
> How about:

    There are no library operations named $input.

    For help start the hyperdoc browser with )hyperdoc, read the axiom
    book at /usr/share/axiom-doc/book.pdf or visit the mathaction wiki
    http://page.axiom-developer.org/zope/mathaction/

---

    You have specified incorrect arguments to the function $input.
    Possible alternatives are:
        ... list ...

    For help start the hyperdoc browser with )hyperdoc, read the axiom
    book at /usr/share/axiom-doc/book.pdf or visit the mathaction wiki
    http://page.axiom-developer.org/zope/mathaction/

---

That sounds very good to me. Can you send Tim a patch file?

> Do not tell the user that )what op (etc) even exist, as they are
> not helpful to new users.  Advanced users will find them.

Agreed.

>> ... See something near:
>> 
>> http://page.axiom-developer.org/zope/mathaction/Streams
>
>It's not a stream...I replaced AxiomGraphics instead.
>

You are right. Thanks.

> However the code in chapter 7 of the axiom book also fails...
> 'makeGraphImage' fails with an odd error claiming that the
> function doesn't exist!

The book neglected to tell you that you could first make the
GRIMAGE domain available by

  )expose GraphImage

> When it is coerced to a GRIMAGE (why must 'makeGraphImage' be
> coerced to a 'GraphImage'?!?) it fails with "index out of range".

In the example on page 306:

  g := makeGraphImage(llp,lpc,lc,lsize)$GRIMAGE

$GRIMAGE is not a "coercion" ( :: ) it is a "direct package call"
( $ ). This says specifically to call the function named
makeGraphImage defined in the domain GraphImage (abbrev GRIMAGE)

The error message "index out of range" was caused by a different
problem. In your original example one of the lists contained
21 elements (0..20) while the others contained 20 ( 1..20).
I have changed them all to just 10 points for brevity.

> Also I seem to have triggered some output parsing bug on mathaction
> too:
>    http://page.axiom-developer.org/zope/mathaction/AxiomGraphics

Yes, there seemed to be some problem with the insertion of
images, perhaps because you had two identical images on the
same page. I vaguely recall see that that causes an error in
the version of LatexWiki we are using. I change "dark blue()"
to "light blue" for the line segments just so the output would
be slightly different. That caused the problem to disappear.
You might also have run across a problem trying to LaTeX rather
large expressions. Sometimes (rarely) that causes an incomplete
png image to be generated and they are hard to get rid of except
by deleting the file the hard way.

> ...
>> It would be nice if typing
>> 
>>   )help
>> 
>> actually launched hyperdoc, instead of the other way around.
>
> It does not seem possible to launch hyperdoc from the command
> line, right?  I could not find how.

Tim's the guy to ask. I think that it is possible. But normally
all of the Axiom components include graphics, hyperdoc and Axiom
itself are launched by a master process called 'sman'. You could
try

  )sys axiom -ht -nogr

(or something similar to that) from the Axiom command line.

> ...
>> 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.
>
> I was under the impression Kai was going to attempt this as
> part of his AxiomUI project?

Yes, I think so although it is a separable part of the project.

> I think the contents of input/ could be imported to the
> mathaction wiki with trivial transformation.  e.g. wrap text
> in \begin{axiom} and make -- a wiki paragraph.  This, at least,
> would provide a searchable database of working examples.

Yes, when I looked at this quickly I thought it should be possible
and then went on to other things ... :)

> (though they are poorly commented)  My lisp is poor but I could
> do it in perl or python in an hour.

If you would care to tackle this I (and a lot of other people)
would be eternally grateful to you! For one thing it would make
all of that documentation immediately available to the large
number of windows users.

> The relevant info seems to be in browse.daase.

Yes. Do you think you can extract it in a form that would
be navigable?

> Also the hypertex format seems to be relatively simple.  It
> shouldn't be too much work to convert it to a wiki format so
> that it can be dumped on mathaction.  (or into a tiddlywiki ;)

Yes. Excellent!

> Rather than lauching hyperdoc we could launch a web browser...

Yes. That's what I have been saying all along. :) :) :)

>> BTW, when you were spending your 3 hours learning this lesson,
>> did you happen to think of doing a search on MathAction?
>
> Of course, but there are multiple resources:
>    )commands
>    pamphlet documentation
>    axiom book
>    mathaction
> which I tried in that order.  For a self-described "literate"
> system, finding the answers to my questions in the first
> 2 resources (e.g. the "literate" part) is woefully difficult.
> We've got to fix that.

I agree. Perhaps there might be some tool that would make it
possible to search through all the multitude of dvi files,
i.e. to index them for searching? I know there is a way to do
that using Acrobat (the commercial package).

But really, in my opinion the more of this material that
we can get on the web site, the better.

Regards,
Bill Page.