[Texmacs-dev] Re: TeXmacs Powered CAS documentation

[Joris van der Hoeven]

Hi,

> I'm having a lot of free time in this vacation so I was plannig to
> work on something wich I call TeXmacs powered CAS documentation. The
> idea is to convert some info and HTML files of CAS (like Maxima,
> Yacas, etc) in TeXmacs documents. In this way, for example, when you
> invoke help in that systems inside TeXmacs you get an interactive
> document wich explains the use of the system, but the code of the CAS
> refered to some function or example is in fact a session of that CAS
> inside the TeXmacs powered doc. Something similar at the moment is
> present in Maxima session where you can invoke the Manual, but it is
> composed of HTML files, not  files, the idea is convert them to  to
> bring them interactivity (for me the most appealing feature of
> TeXmacs). The idea carries some questions, I hope you can help me:
>
> * May be will be necesary to change some part of the documentation to
> refer at the process inside TeXmacs, for example in the HTML version
> of the Maxima Manual you see that for calling Maxima you type maxima
> command at shell but you don't make this calling Maxima inside
> TeXmacs, so a cosmetic change is required here. So do you know what is
> the licence of the documentation for Maxima, Yacas, Octave, Scilab
> (and similar CAS)?

The License might be displayed by the startup banner.

> * May be we can create some kind of info2html script (or use the
> existing one) for showing info pages of CAS systems inside  in a new
> buffer. In that way we can have a nice hipertextual document output
> instead of the long plain text response that at this moment we get.
> Most of time after consulting this help we delete it because invoking
> help  is not the purpose of the document that we are writing with the
> CAS, so having the output of that help in a separate buffers makes a
> lot of sense to me. At the same time it gives the user a sense of
> consistency of the scientific writer, because if you want to browse
> help nicely you dont have to go to shell for that. (Is the same that
> when you have the posibility to browse help files inside the konqueror
> or nautilus file/internet browsers. The end user feels that is using a
> integrate comprensive solution).

Clearly, there are several possibilities here:
write a texinfo2texmacs converter, or customize the texinfo2html
converter such that the generated pages are a bit smaller.
What about searching the help files by the way?

> * Layers of document: At this moment we have some of this with the
> idea of folding and unfolding. If we are making TeXmacs powered docs
> may be we dont wish to show the code that produce a figure for
> example, but we only want to show that figure. May be we can put that
> code in a diferent layer and fold it and "above" that we can put the
> output. Most of CAS programs can produce is some way a postscript
> output of figures and TeXmacs can render postscript fine, will be nice
> to have a "macro" wich make this process more automatic (creating a
> figure from CAS commands and insert/link it to a TeXmacs document).
> The idea of Layers can be extended to put, for example, in a inferior
> layer the data of a stadistic problem and above the R session wich
> handles that data. The files can be inserted or linked (like with
> images files at the moment) so the user have the posibility to carry
> in a simple document all the info he need to make his work.

Yes, documentation may indeed be far more intelligent.
We might want to make it possible to include example sessions
inside the documentations, or scripts which produce examples.
I guess that this may require some changes to be made directly
in the documentation. Would texinfo support this?

It may also be nice to develop "demo modes" which would for instance
allow to run the standard demos for GNU R or Scilab inside TeXmacs.
Notice that it is already possible to send next suggested inputs
in computer algebra sessions (in a similar way as sending prompts).
In any case, this requires some changes in the interfaces.

> I want to make some contribution in this vacation to CAS comunity
> (specially using TeXmacs, the CAS glue ;-) ). I can help also with
> localization to spanish for some doc, and I offered before to try to
> make another Scheme interpreter work with TeXmacs, but I feel that the
> TeXmacs powered doc can help to more people and is more suited to me.
> Any advice or indication about where to start will be apreciated.

A first step would clearly be to provide help for CAS' where
no online help is available yet (Yacas for instance).

A next step might be to contact the developers of different CAS' and
see how to support interactive help (which is different from online
help: think about typing something like "?command" in a session).
Solving the interactive help brings us naturally to interactive
demos too.

Finally, for even more integrated help, we might try to figure out
how to enrich existing documentation in such a way that it becomes
more powerful for interaction with TeXmacs. Since this might require
some changes in the help files themselves, we would have to figure
out a suitable format for each CAS (modified texinfo, TeX/LaTeX or
Html with additional markup, etc.).

Of course, all help from the maintainers of the different
CAS systems would be very welcome too.

In any case, thanks a lot for your proposal !!!

<Joris>