Seeking areas of little or weak documentation

Am Montag, den 21.03.2011, 16:54 -0400 schrieb Stavros Macrakis:
> Oh, I just *assumed* that whatever Sol came up with would be designed
> for on-line use, not for paper.  Don't we all hate reading
> page-formatted PDFs online?
> 
> 
>                -s
> 
> On Mon, Mar 21, 2011 at 16:44, Henry Baker <hbaker1 at pipeline.com>
> wrote:
>         I would hate to see YAMM (Yet Another Maxima Manual).  In this
>         day & age, paper isn't where it's at; you want everything to
>         on-line.
>         
>         It should be possible _within Maxima itself_ to bring up one
>         or more web pages in your web browser which include function
>         definitions, examples, source code, etc.  Javascript is
>         sufficiently powerful to do a lot, and with HTML5 becoming
>         available momentarily, a web-based interface will allow
>         real-time hardware-accelerated shaded animated graphics from
>         within Maxima.  The newest generation of browsers have
>         just-in-time compilers for Javascript, so javascript is
>         actually pretty zippy.  Check out Microsoft's beta browser,
>         for example.
>         
>         If you want to look at better on-line documentation, look at
>         the Javascript pages at
>         
>         http://www.w3schools.com/js/
>         
>         They aren't perfect, but they're pretty good, and they're
>         Google searchable, which helps enormously.
>         
>         P.S., I would love to replace the existing Maxima front-end
>         with a browser-based one, so that I could utilize some of the
>         interactive javascript graphical tools -- e.g., JSXGraph.
>         
>         
>         At 01:24 PM 3/21/2011, Stavros Macrakis wrote:
>         >I think just about any topic in Maxima could benefit from
>         intelligent documentation.
>         >
>         >Today, each section (e.g. polynomials) is organized
>         alphabetically by function.  That is fine if you know what
>         function you want, but very hard to use if you're trying to
>         get something accomplished and don't know how.  The problem is
>         that it's not clear what resources a tech writer could use to
>         write this up in a goal-oriented way.  There is lots of useful
>         information in the mailing list archives, but it is *a lot* of
>         material.
>         >
>         >                -s
>         >
>         >On Mon, Mar 21, 2011 at 16:21, Michel Talon
>         <talon at lpthe.jussieu.fr> wrote:
>         >Sol Lederman wrote:
>         >
>         >> Henry and Richard,
>         >>
>         >> Thank you for taking the time to respond so thoroughly to
>         my post.
>         >>
>         >> I see a common thread in your responses -- that there are
>         areas of Maxima
>         >> where information is not well organized/catalogued.
>         >
>         >One of the areas which would benefit from a better
>         documentation is the part
>         >36, Rules and patterns. This is a difficult subject, and
>         frequently
>         >questions about it appear in this forum. By collecting all
>         this information,
>         >and playing with the program, perhaps one could enhance this
>         documentation.
>         >This is a set of features which work very well in Mathematica
>         and are very
>         >well documented in the Mathematica book. This perhaps could
>         help as example.
>         >Robert Dodier is the expert on these features, he certainly
>         could also help.
>         >
>         >In another department, R. Toy has recently added lbfgs to the
>         share
>         >directory. I suppose this is related to
>         >http://en.wikipedia.org/wiki/BFGS_method
>         >http://en.wikipedia.org/wiki/L-BFGS
>         >but there is zero documentation. this would be a target for
>         experimentation
>         >and documentation on a limited domain.
>         >
>         >I would say the same for colnew but i am working on it,
>         because i have
>         >special interest on this program.
>         >
>         >There are other interesting programs which are presently
>         broken such as
>         >share/gentran. Dan Stanger is working on that, probably it
>         will be an
>         >interesting target of documentation  because gentran
>         functionality is nice.
>         >
>         >--
>         >Michel Talon

Since several month I am working on a German translation and it is like
Stavros has written in one of the last postings, every chapter could
benefit from more documentation. 

This work is not finished, but I have an online version of the German
translation which might be interesting to compare with the actual
English version http://crategus.users.sourceforge.net/maxima.html

I have opened some new chapters, closed other chapters and collected the
functions in a more logical order.

I have added more documentation of functions and more examples, and I
tried to describe the functions less technical, but more user friendly.
One point is that I started to collect all option variables, which
control the simplification of functions, see e. g. the trigonometric
functions or the Exponential function in the German translation.

Furthermore, I have added a lot of cross references in the online
version, and started to add more verbose introductions to every chapter,
which gives the user an overview.

Dieter Kaiser