)savesystem , again

[oldk1331]

See previous discussion here:
https://groups.google.com/d/msg/fricas-devel/rgwdpoPQHEA/ZCwDQIEtn5MJ

The objections discussed in previous thread that
)savesystem should be removed is:
1. ECL doesn't support it.
2. problems with frames.

But I find a really useful use case for )savesystem:
Supporting incremental development, aka avoiding
recompiling files that you modified locally.
Saving variables is one thing, saving modified algebra
is another.

For example, I have several modified spad files,
compiling all of them takes around 10s. With )savesystem,
I can save the work I've done, and continue from the
saved system directly.

What do you think?

[Waldek Hebisch]

1) ')savesystem' is not that fast and too buggy.
2) ')lib' should be fast enough. For multiple files I create
a little .input script with all needed ')lib' commands.

--
Waldek Hebisch

[oldk1331]

One reason I didn't think of )library is that
)help didn't show it, fricas 1.1.3 shows:

====================================================================
Other help topics
====================================================================
Available help topics are:

abbreviations assignment blocks     browse     boot       cd
clear         clef       close      collection compile    display
edit          fin        for        frame      help       history
if            iterate    leave      library    lisp       load
ltrace        parallel   pquit      quit       read       repeat
savesystem    set        show       spool      suchthat   synonym
system        syntax     trace      undo       what       while

Available algebra help topics are:


But now )help doesn't show it.  I don't know
which commit removes it.  Should we add it back in?

[Waldek Hebisch]

Currently help files are generated from .htex file describing
system commands. This lead to the change. I am not sure if
putting list of commands at the end of help text for "help"
is a good idea. Probably it would be better to print this
text when nothing is given as an argument. Or maybe when
invalid name is given.

--
Waldek Hebisch

[oldk1331]

> Probably it would be better to print this
> text when nothing is given as an argument.  Or maybe when
> invalid name is given.

That's a good idea.

So ")help" gives the command list, and ")help help" gives current
help message.

Who will make this change?  I can if you are busy.

[oldk1331]

Another question related with the help system:

How to generate DOM/CAT/PKG help files under
$AXIOM/share/spadhelp/ ?

They are not generated in a fresh build from trunk,
and seems to be bundled in release tarballs without
change for a long time.

I search "spadhelp" in mail archives, seems that
because of possible duplication, the spadhelp/
dir is not included in FriCAS source tree.  But also
we still don't have a way to generate them.
Am I summing it up correctly?

What's the status of spadhelp, and what's the right
thing to do with it?

[Waldek Hebisch]

Currently help files for system commands are generated
from .htex file describing system command. Algebra
help files were created mostly manually by Tim Daly.
Currently algebra help files are essentially unmaintained:
trying to maintain them would mean duplicating work
done on .htex files. There is source tarball
IIRC present in 1.0.8 version.

Let me add that it is important that there is one
"authoritative" version of documentation -- currently
it is contained in .htex files (plus ++ docstrings
and a few .ht files). Other formats should be
generated from this one.

Concerning what to do: I consider spadhelp files as
extra nicety, but not essential. Namely, main
source of information is HyperDoc and in principle
we can generate nice .pdf file from HyperDoc.
In other words, users can find information
in other places and spadhelp files add little
value.

Spadhelp files are pure ASCII which limits what
can be expressed. HyperDoc format is also
deliberatly limited, so in principle translating most
of HyperDoc to ASCII is possible (there are problems
caused by images and interactive features).
But to the moment nobody set up process to
genrate them.

--
Waldek Hebisch

[oldk1331]

> Let me add that it is important that there is one
> "authoritative" version of documentation -- currently
> it is contained in .htex files (plus ++ docstrings
> and a few .ht files).  Other formats should be
> generated from this one.

I didn't dig the help system much, so I'll just ask:
is there duplication between ++ docstrings and
.htex files?  The ++ docstrings are meant to
generate .htex files, right?

(I'll fix this )help soon.)

[Ralf Hemmecke]

On 06/30/2016 03:44 PM, oldk1331 wrote:
> I didn't dig the help system much, so I'll just ask:
> is there duplication between ++ docstrings and
> .htex files? The ++ docstrings are meant to
> generate .htex files, right?

No.

That's a bit more difficult. In fact, I don't know, how the ++
docstrings get into hyperdoc, but they definitely undergo some massage,
i.e. in ++ docstrings you can use certain LaTeX-like looking commands
like \spadtype, \spad, \spadfun, etc.

When I generate the http://fricas.github.io/api site, I get the
docstrings via api.spad. So you find the LaTeX commands here.

https://github.com/hemmecke/fricas/blob/mathjax/src/doc/api.spad#L1015

In fact that .htex Format is more or less pure LaTeX (the special
commands are handled by fricas.sty). That way .htex can be used to
generate the pdf form of the book.

For HyperDoc, the .htex files are translated into .ht files. The .ht
Format is what some program (I don't know which) needs to generate the
internal HyperDoc objects that can be shown.
Additionally, there are original .ht file that are not generated from
.htex (see https://github.com/hemmecke/fricas/tree/mathjax/src/doc/ht).

Basically, I haven't touched them, because I think that HyperDoc should
die. The only interesting things in HyperDoc that are interesting for me
are:

1) Finding out which domain implements a certain function
2) The ++ docstrings of user compiled domain/category/package show
up immediately in HyperDoc browse after ")compile SomeDomain".

I also did not care to generate the helpfiles (ASCII) from the .htex
sources (although this could probably be done), but with the
availability of http://fricas.github.io/api (which one can even have
generated to work on localhost) makes the ascii help of (except for the
system commands) superfluous for my taste. Everyone has an html-browser
nowadays. And one can read the API side with Lynx, i.e. in ASCII.

Ralf