Discussion:
Introduction to simplification and corresponding simplifier paper
(too old to reply)
Roland Salz
2017-06-21 14:37:24 UTC
Permalink
Raw Message
Hi,



last summer Richard Fateman and I wrote an introduction to simplification to be incorporated into the manual. It can be
viewed at <https://people.eecs.berkeley.edu/%7Efateman/papers/intro5.txt>
https://people.eecs.berkeley.edu/~fateman/papers/intro5.txt. The current manual contains no introduction at all to
chapter 9, Simplification. Simplification, however, is a central part of the CAS Maxima system. Thus, its understanding
gives valuable insight into the overall CAS system. The leading goal in writing this introduction was to make the reader
curious and interested not only in what Maxima can do by itself, but in the numerous ways how it can be controlled,
tailored, enhanced by the user as his tool.



The idea to write such an introduction came from reading the German Maxima version 5.29 (the last one that has been
written), dating back to 2011 and translated at that time by Dieter Kaiser. This translation contains numerous chapter
introductions that do not appear in the English original.



Richard had written a very thorough paper on Maxima's simplifier back in 1979. This paper in my opinion and to my
knowledge is the best way to get an idea of how Maxima works at the programming level. Understanding simplification and
the corresponding part of the Maxima system, the simplifier, can thus be regarded as a means to take a look into
Maxima's way of operation in general. This paper was presented at a Maxima user's conference, it is theory directed to
users. Our introduction to simplification makes reference to this paper, which can be viewed as a natural continuation
of this introduction for the reader more interested in the subject. Although the information of this paper goes beyond
what is normally contained in a User's Manual, my belief is that it should be incorporated in the official Maxima
documentation corpus.



From the discussion we had on the list about the proposed text last summer, I got the impression that there was a
consensus to go ahead with this. In the meantime I made some experiences with building the documentation and I would
feel confident to be able to do the texinfo formatting myself. But before starting I would like to be reassured that the
project is agreed and the whole work will not be in vain.



My proposal therefore is to include the introduction itself at the beginning of Simplification.texi and to keep the
paper as a separate file. For this I see two possibilities: (1) Include the file in texi format as part of the manual.
(2) Include the file in the doc directory of the repository, in the tarball and in the installer version of Maxima, but
leave it in plain text format to be read with any text editor. The latter way would not include it in the online help,
the html or the pdf version of the manual itself, but it would make it accessible easily and offline to any Maxima user,
in the same way a readme file is.



Best regards,

Roland
Gunter Königsmann
2017-06-21 15:42:56 UTC
Permalink
Raw Message
Things are not this bad any more:
As a German user you will automatically be presented the German version of the manual - which isn't obvious as most of the HTML files never have been translated. ...and the English pages of the German manual are old enough to be seriously misleading at times.

... but AFAIK the English version of the manual should by now contain the parts that weren't subject of the discussion.

To everyone who wonders why I want maxima to use a2po for the translations:
If we used it the untranslated sections would be accurate and the rest would tell new translators what is still accurate and what needs to be revised.

We only would need to find out if there is a way to select which files are handled with a2po and which are handled the traditional way. And, of course, if we can live with the additional build dependency.


Kind regards,

Gunter.
Post by Roland Salz
Hi,
last summer Richard Fateman and I wrote an introduction to
simplification to be incorporated into the manual. It can be
viewed at
<https://people.eecs.berkeley.edu/%7Efateman/papers/intro5.txt>
https://people.eecs.berkeley.edu/~fateman/papers/intro5.txt. The
current manual contains no introduction at all to
chapter 9, Simplification. Simplification, however, is a central part
of the CAS Maxima system. Thus, its understanding
gives valuable insight into the overall CAS system. The leading goal in
writing this introduction was to make the reader
curious and interested not only in what Maxima can do by itself, but in
the numerous ways how it can be controlled,
tailored, enhanced by the user as his tool.
The idea to write such an introduction came from reading the German
Maxima version 5.29 (the last one that has been
written), dating back to 2011 and translated at that time by Dieter
Kaiser. This translation contains numerous chapter
introductions that do not appear in the English original.
Richard had written a very thorough paper on Maxima's simplifier back
in 1979. This paper in my opinion and to my
knowledge is the best way to get an idea of how Maxima works at the
programming level. Understanding simplification and
the corresponding part of the Maxima system, the simplifier, can thus
be regarded as a means to take a look into
Maxima's way of operation in general. This paper was presented at a
Maxima user's conference, it is theory directed to
users. Our introduction to simplification makes reference to this
paper, which can be viewed as a natural continuation
of this introduction for the reader more interested in the subject.
Although the information of this paper goes beyond
what is normally contained in a User's Manual, my belief is that it
should be incorporated in the official Maxima
documentation corpus.
From the discussion we had on the list about the proposed text last
summer, I got the impression that there was a
consensus to go ahead with this. In the meantime I made some
experiences with building the documentation and I would
feel confident to be able to do the texinfo formatting myself. But
before starting I would like to be reassured that the
project is agreed and the whole work will not be in vain.
My proposal therefore is to include the introduction itself at the
beginning of Simplification.texi and to keep the
paper as a separate file. For this I see two possibilities: (1) Include
the file in texi format as part of the manual.
(2) Include the file in the doc directory of the repository, in the
tarball and in the installer version of Maxima, but
leave it in plain text format to be read with any text editor. The
latter way would not include it in the online help,
the html or the pdf version of the manual itself, but it would make it
accessible easily and offline to any Maxima user,
in the same way a readme file is.
Best regards,
Roland
--
Diese Nachricht wurde von meinem Android-GerÀt mit K-9 Mail gesendet.
Michel Talon
2017-06-21 16:24:02 UTC
Permalink
Raw Message
Post by Roland Salz
ast summer Richard Fateman and I wrote an introduction to simplification
to be incorporated into the manual. It can be viewed at
https://people.eecs.berkeley.edu/~fateman/papers/intro5.txt
<https://people.eecs.berkeley.edu/%7Efateman/papers/intro5.txt>.
I have just reread this text, and i like it a lot. It would be so nice
if more of the maxima functionality was explained with the same sort of
detail rather than the present "man page" style (*). However there are
some character problems inside, for example on my Linux machine i see
things such as:

simplify f(-x) to –f(x)
Maxima’s Database

(*) the chapter "Rules and Patterns" being for example documented in a
particularly impossible to understand way, would need vastly more
explanations, and tons of examples - which are in fact available in
maxima mailing lists. Arguably this would be contrary to the present
spirit of the documentation, and also would render the documentation huge.
--
Michel Talon
Robert Dodier
2017-06-22 05:48:32 UTC
Permalink
Raw Message
Post by Michel Talon
I have just reread this text, and i like it a lot. It would be so nice
if more of the maxima functionality was explained with the same sort of
detail rather than the present "man page" style (*).
I dunno. I'm pretty sure that reference documentation has to be a
man-page style. I wouldn't want the reference manual to contain a lot of
other stuff.
Post by Michel Talon
(*) the chapter "Rules and Patterns" being for example documented in a
particularly impossible to understand way, would need vastly more
explanations, and tons of examples - which are in fact available in
maxima mailing lists. Arguably this would be contrary to the present
spirit of the documentation, and also would render the documentation huge.
For better or worse I wrote some large swathes of "Rules and Patterns";
matchdeclare and tellsimpafter for sure, and maybe other stuff. I tried
pretty hard to be both concise and complete -- not an easy task, given
the complexity of the topic. No doubt the prose can be clarified -- it's
pretty dense -- but I wouldn't want to change the general organization
of it.

I didn't go into why those functions should be used for any purpose, or
how to solve a given problem; that kind of stuff is in the realm of
tutorials, which are very important, but a different goal than the
reference manual. If anyone wants to write tutorials, and include goals,
problems, motivations, and strategies, that would be great. We can put
that stuff on the website.

best

Robert Dodier
Robert Dodier
2017-06-22 05:25:02 UTC
Permalink
Raw Message
Post by Roland Salz
My proposal therefore is to include the introduction itself at the
beginning of Simplification.texi and to keep the paper as a separate
file.
OK by me to include the "Introduction to Simplification" from
https://people.eecs.berkeley.edu/~fateman/papers/intro5.txt
in Simplification.texi. I don't want to include the paper.
Post by Roland Salz
For this I see two possibilities: (1) Include the file in texi format
as part of the manual. (2) Include the file in the doc directory of
the repository, in the tarball and in the installer version of Maxima,
but leave it in plain text format to be read with any text editor.
My advice is to format the paper as PDF (via Texinfo or LaTeX) and post
it on the maxima.sourceforge.net website, and refer to it via the link
in the introduction in Simplification.texi, and link it from the
documentation page (documentation.html), and also include the paper
somewhere in maxima/doc.

best,

Robert Dodier
Roland Salz
2017-06-25 15:44:45 UTC
Permalink
Raw Message
-----Original Message-----
Sent: Thursday, June 22, 2017 7:25 AM
OK by me to include the "Introduction to Simplification" from
https://people.eecs.berkeley.edu/~fateman/papers/intro5.txt
in Simplification.texi.
After installing 5.40.0 today I found out that the introduction to simplification is already included. Gunter, thank you
very much for having done this work !!
My advice is to format the paper as PDF (via Texinfo or LaTeX) and post it on the maxima.sourceforge.net
website, and refer to it via the link in the introduction in Simplification.texi, and link it from the documentation
page (documentation.html), and also include the paper somewhere in maxima/doc.
This I'll prepare as far as I can do.

Some minor adaptations have to be made to the introduction then, so e.g. the reference to Richard's paper has to be
changed. I will do that and come up with a revised version of Simplification.texi.

Best regards,
Roland

Loading...