[Maxima-discuss] Documentation of ?<lisp-function> and documentation in general

[Roland Salz]

Hi,



Only from a 2015 mailing list answer by Barton (thanks from my side) about ?print I found out that basically every
lisp-function can be used directly from within Maxima without preceding it by :lisp, and in the usual Maxima function
notation instead of CL's list notation. So instead of



:lisp (print a) I can also say ?print(a); in order to show the internal structure of an
expression.



But e.g. I could also say (provided that I have managed to declare "-" alphabetic)



?lisp-implementation-version();



And this notation has a significant advantage over saying :lisp (lisp-implementation-version),

because I can use it within other Maxima functions, expressions, assignments, e.g.



print(?lisp-implementation-version()); or

lispname: ?lisp-implementation-type();



Why am I writing this? We don't find this feature described in the manual. There is a minimal hint where "?" is
described, but this hint definitively is not enough to understand the scope of this feature and its possibilities. This
in my opinion is symptomatic for the Maxima documentation. Maxima has a lot of nice features which practically no one
knows. And if they are described in the manual, this description is often so cryptic and stenographic, that only someone
can understand it who knew it beforehand anyway. I'm aware of the fact that the manual has already 1100 pages. But
Maxima is very complex, and if the pdf file would have 2000 pages instead, but describing a lot more features in an
understandable way, I think Maxima would significantly gain. Nowadays, no one needs to print that out, it's only a pdf
file.



There is another significant drawback about the current manual, and this is its structure. The structure is fairly
elaborated and ok up to chapter 38, debugging. But after that, the structure basically vanishes and the whole thing
becomes an encyclopedia of packages, in alphabetical order. This means, there is no structured table of contents or any
index of features or search-terms which are not functions or variables.



The situation is even worse for packages that people write with a lot of effort and a lot of time and which then are not
even incorporated in Maxima any more. These packages aren't documented in the manual at all, either. So who is going to
know about them and use them? I can understand anyone who wrote one package for Maxima and then does it never again,
seeing what the result was.



What I also understand is the fear that all the valuable information that has been piled up in the manual carefully over
the years and decades might be screed up by someone who does not fully understand it. This of course is a real danger,
and this must not happen. But the current manual is also dead in some respect, and it should come to life again. In my
opinion, Maxima will not develop further, if the manual doesn't.



Best regards,

Roland

[Richard Fateman]

On 7/22/2017 2:32 PM, Roland Salz wrote:
>
> Hi,
>
> Only from a 2015 mailing list answer by Barton (thanks from my side)
> about ?print I found out that basically every lisp-function can be
> used directly from within Maxima without preceding it by :lisp, and in
> the usual Maxima function notation instead of CL’s list notation. So
> instead of
>
> :lisp (print a) I can also say ?print(a);
> in order to show the internal structure of an expression.
>
> But e.g. I could also say (provided that I have managed to declare “-“
> alphabetic)
>
> ?lisp-implementation-version();
>
or without any declarations,

?lisp\-implementation\-version();
>
> And this notation has a significant advantage over saying :lisp
> (lisp-implementation-version),
>
> because I can use it within other Maxima functions, expressions,
> assignments, e.g.
>
> print(?lisp-implementation-version()); or
>
> lispname: ?lisp-implementation-type();
>
Caution: lisp functions return results that may not make sense to the
Maxima
simplifier or display.
for example ?cons(1,2);

for fun, try ?append([a],[b]);

> Why am I writing this? We don’t find this feature described in the
> manual. There is a minimal hint where “?” is described, but this hint
> definitively is not enough to understand the scope of this feature and
> its possibilities. This in my opinion is symptomatic for the Maxima
> documentation. Maxima has a lot of nice features which practically no
> one knows. And if they are described in the manual, this description
> is often so cryptic and stenographic, that only someone can understand
> it who knew it beforehand anyway.
>
I agree. Several authors have written useful tutorial/reference separate
from
the manual. The original MIT manual, as amended by Symbolics, is here

https://people.eecs.berkeley.edu/~fateman/macsyma/docs/





The original documentation suffered from several defects, and some of them
are carried over into the current Maxima documentation.
You have noted some of them, but here are some more.

There is an uneven level of expectation of the reader. Sometimes
the reader is expected to understand programming languages,
sometimes some topic of advanced math, or sometimes just
an "advanced viewpoint" of not-so-advanced math. Like
why does the answer say log(x) when the textbook says log(|x|)..

In some cases the command description is almost nonexistent,
perhaps assuming that the user would figure out what the command
did from its name. But then the documentation consisted of
examples that are mostly exceptions (that is, where
are the boundaries beyond which the command
DOESN'T work).
>
> I’m aware of the fact that the manual has already 1100 pages. But
> Maxima is very complex, and if the pdf file would have 2000 pages
> instead, but describing a lot more features in an understandable way,
> I think Maxima would significantly gain. Nowadays, no one needs to
> print that out, it’s only a pdf file.
>
> There is another significant drawback about the current manual, and
> this is its structure. The structure is fairly elaborated and ok up to
> chapter 38, debugging. But after that, the structure basically
> vanishes and the whole thing becomes an encyclopedia of packages, in
> alphabetical order. This means, there is no structured table of
> contents or any index of features or search-terms which are not
> functions or variables.
>
> The situation is even worse for packages that people write with a lot
> of effort and a lot of time and which then are not even incorporated
> in Maxima any more. These packages aren’t documented in the manual at
> all, either. So who is going to know about them and use them? I can
> understand anyone who wrote one package for Maxima and then does it
> never again, seeing what the result was.
>
There is also a problem when someone writes a package for Maxima but it
is not any good.
There are many ways for a package to be bad. Some of them are
distributed in the share directory, unfortunately.
>
> What I also understand is the fear that all the valuable information
> that has been piled up in the manual carefully over the years and
> decades might be screed up by someone who does not fully understand
> it. This of course is a real danger, and this must not happen. But the
> current manual is also dead in some respect, and it should come to
> life again. In my opinion, Maxima will not develop further, if the
> manual doesn’t.
>

This is a challenge --- can one take "maxima by example" or some other
book, or maybe start from
scratch and write a new manual? There are examples of better approaches
in terms of
content and presentation. See for example the Mathematica Book. (or
maybe it is no
longer a book but a web presentation.

RJF

> Best regards,
>
> Roland
>
>
>

[Barton Willis]

Using CL functions from Maxima, isn't something that we particularly want to encourage users to do, I think. It deserves mention in developer manual (but we don't have one).


If a user wants to learn C and fix bugs or contribute to the core of Maxima, that's terrific. Highlighting the ? trick promotes the myth that a user needs to know CL to use or contribute to Maxima.


--Barton
________________________________
From: Roland Salz <***@gmail.com>
Sent: Saturday, July 22, 2017 4:32:56 PM
To: maxima-***@lists.sourceforge.net
Subject: [Maxima-discuss] Documentation of ?<lisp-function> and documentation in general

Hi,

Only from a 2015 mailing list answer by Barton (thanks from my side) about ?print I found out that basically every lisp-function can be used directly from within Maxima without preceding it by :lisp, and in the usual Maxima function notation instead of CL’s list notation. So instead of

:lisp (print a) I can also say ?print(a); in order to show the internal structure of an expression.

But e.g. I could also say (provided that I have managed to declare “-“ alphabetic)

?lisp-implementation-version();

And this notation has a significant advantage over saying :lisp (lisp-implementation-version),
because I can use it within other Maxima functions, expressions, assignments, e.g.

print(?lisp-implementation-version()); or
lispname: ?lisp-implementation-type();

Why am I writing this? We don’t find this feature described in the manual. There is a minimal hint where “?” is described, but this hint definitively is not enough to understand the scope of this feature and its possibilities. This in my opinion is symptomatic for the Maxima documentation. Maxima has a lot of nice features which practically no one knows. And if they are described in the manual, this description is often so cryptic and stenographic, that only someone can understand it who knew it beforehand anyway. I’m aware of the fact that the manual has already 1100 pages. But Maxima is very complex, and if the pdf file would have 2000 pages instead, but describing a lot more features in an understandable way, I think Maxima would significantly gain. Nowadays, no one needs to print that out, it’s only a pdf file.

There is another significant drawback about the current manual, and this is its structure. The structure is fairly elaborated and ok up to chapter 38, debugging. But after that, the structure basically vanishes and the whole thing becomes an encyclopedia of packages, in alphabetical order. This means, there is no structured table of contents or any index of features or search-terms which are not functions or variables.

The situation is even worse for packages that people write with a lot of effort and a lot of time and which then are not even incorporated in Maxima any more. These packages aren’t documented in the manual at all, either. So who is going to know about them and use them? I can understand anyone who wrote one package for Maxima and then does it never again, seeing what the result was.

What I also understand is the fear that all the valuable information that has been piled up in the manual carefully over the years and decades might be screed up by someone who does not fully understand it. This of course is a real danger, and this must not happen. But the current manual is also dead in some respect, and it should come to life again. In my opinion, Maxima will not develop further, if the manual doesn’t.

Best regards,
Roland

[Robert Dodier]

On 2017-07-22, Roland Salz <***@gmail.com> wrote:

> Why am I writing this? We don't find this feature described in the
> manual. There is a minimal hint where "?" is described, but this hint
> definitively is not enough to understand the scope of this feature
> and its possibilities.

I dunno -- the documentation for ? refers to "Lisp and Maxima" which
does explain ?symbol and :lisp in more detail.

> There is another significant drawback about the current manual, and
> this is its structure. The structure is fairly elaborated and ok up to
> chapter 38, debugging. But after that, the structure basically
> vanishes and the whole thing becomes an encyclopedia of packages, in
> alphabetical order. This means, there is no structured table of
> contents or any index of features or search-terms which are not
> functions or variables.

In the HTML version, there are subject category links which group
together different functions and packages. E.g. the user can look at the
"Simplification" category and see which functions and packages have
something to do with that. Unfortunately I don't see a way to make that
work in other formats.

> The situation is even worse for packages that people write with a lot
> of effort and a lot of time and which then are not even incorporated
> in Maxima any more.

At this point my preference is for package developers to manage their
projects independently, but make it easy for users to install and load.
This, I hope, will encourage a Maxima "ecosystem" similar to the clouds
of projects circling R, Ruby, Python, etc.

Maxima is pretty big already and we are quite short on experienced
developers. I feel pretty strongly that we have our hands full with the
central part of the system and so we must ask package developers to help
us out by managing their own projects.

> the current manual is also dead in some respect, and it should come to
> life again. In my opinion, Maxima will not develop further, if the
> manual doesn't.

I dunno. I can see a couple of substantial improvements to the reference
manual. One is to rewrite and expand some of the items. Some years ago
(10+) I rewrote a lot of the documentation, but didn't touch all of the
items. It wouldn't hurt to identify the ones that could benefit from an
update. The other is to put a concise introductory essay on each
chapter.

But I don't see a need for ongoing revisions. I wouldn't mind if we
could bring the manual to state where it just needs corrections and bug
fixes instead of constant expansion. That would free up our attention to
spend on other topics, of which there are always more.

best

Robert Dodier

[Stavros Macrakis (Σταῦρος Μακράκης)]

I agree with Barton.

:lisp and ? are of course very handy for debugging, but they break the
Maxima abstraction layer. If a user of Maxima needs to use them for
something other than debugging the *implementation*, we're doing something
wrong.

As a shortcut, we often recommend using ?print to understand the internal
structure of Maxima expressions, but I much prefer something like the
function below, which contains no internal magic. Obviously it could be
extended to show the interior structure of CREs (using ratpow), bfloats
(the only missing thing there is a way of extracting a given bfloat's
precision), etc.

-s


/* print internal form */

simple_print_internal(ex):=
block([inflag:true], _spi(ex))$

_spi(ex) :=
if stringp(ex) then concat(\",ex,\")
elseif atom(ex) then ex
elseif numberp(ex) and op(ex)="/" then funmake('rat,args(ex))
elseif subvarp(ex) then
funmake('subscript,[_spi(op(ex)),map('_spi,args(ex))])
elseif atom(op(ex)) then funmake(_spiop(op(ex)),map('_spi,args(ex)))
else funmake('apply, [_spi(op(ex)),map('_spi,args(ex))])$

_spiop(ex) :=
concat(verbify(if ex=nounify(ex) then "'" else ""), ex)$



On Sun, Jul 23, 2017 at 3:29 PM, Robert Dodier <***@gmail.com>
wrote:

> On 2017-07-22, Roland Salz <***@gmail.com> wrote:
>
> > Why am I writing this? We don't find this feature described in the
> > manual. There is a minimal hint where "?" is described, but this hint
> > definitively is not enough to understand the scope of this feature
> > and its possibilities.
>
> I dunno -- the documentation for ? refers to "Lisp and Maxima" which
> does explain ?symbol and :lisp in more detail.
>
> > There is another significant drawback about the current manual, and
> > this is its structure. The structure is fairly elaborated and ok up to
> > chapter 38, debugging. But after that, the structure basically
> > vanishes and the whole thing becomes an encyclopedia of packages, in
> > alphabetical order. This means, there is no structured table of
> > contents or any index of features or search-terms which are not
> > functions or variables.
>
> In the HTML version, there are subject category links which group
> together different functions and packages. E.g. the user can look at the
> "Simplification" category and see which functions and packages have
> something to do with that. Unfortunately I don't see a way to make that
> work in other formats.
>
> > The situation is even worse for packages that people write with a lot
> > of effort and a lot of time and which then are not even incorporated
> > in Maxima any more.
>
> At this point my preference is for package developers to manage their
> projects independently, but make it easy for users to install and load.
> This, I hope, will encourage a Maxima "ecosystem" similar to the clouds
> of projects circling R, Ruby, Python, etc.
>
> Maxima is pretty big already and we are quite short on experienced
> developers. I feel pretty strongly that we have our hands full with the
> central part of the system and so we must ask package developers to help
> us out by managing their own projects.
>
> > the current manual is also dead in some respect, and it should come to
> > life again. In my opinion, Maxima will not develop further, if the
> > manual doesn't.
>
> I dunno. I can see a couple of substantial improvements to the reference
> manual. One is to rewrite and expand some of the items. Some years ago
> (10+) I rewrote a lot of the documentation, but didn't touch all of the
> items. It wouldn't hurt to identify the ones that could benefit from an
> update. The other is to put a concise introductory essay on each
> chapter.
>
> But I don't see a need for ongoing revisions. I wouldn't mind if we
> could bring the manual to state where it just needs corrections and bug
> fixes instead of constant expansion. That would free up our attention to
> spend on other topics, of which there are always more.
>
> best
>
> Robert Dodier
>
>
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Maxima-discuss mailing list
> Maxima-***@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/maxima-discuss
>

[Barton Willis]

I do agree with the OP that improving and the user documentation and keeping it up to date is important.


Some time ago, I contributed a small package for numerically solving hamiltonian systems. Writing the user documentation wasn't the fun part, but I did it. And so it goes with volunteer projects.


--Barton
________________________________
From: ***@gmail.com <***@gmail.com> on behalf of Stavros Macrakis (ΣταῊρος Μακράκης) <***@alum.mit.edu>
Sent: Sunday, July 23, 2017 3:26:25 PM
To: Barton Willis
Cc: <maxima-***@lists.sourceforge.net>
Subject: Re: [Maxima-discuss] Documentation of ?<lisp-function> and documentation in general

I agree with Barton.

:lisp and ? are of course very handy for debugging, but they break the Maxima abstraction layer. If a user of Maxima needs to use them for something other than debugging the implementation, we're doing something wrong.

As a shortcut, we often recommend using ?print to understand the internal structure of Maxima expressions, but I much prefer something like the function below, which contains no internal magic. Obviously it could be extended to show the interior structure of CREs (using ratpow), bfloats (the only missing thing there is a way of extracting a given bfloat's precision), etc.

-s


/* print internal form */

simple_print_internal(ex):=
block([inflag:true], _spi(ex))$

_spi(ex) :=
if stringp(ex) then concat(\",ex,\")
elseif atom(ex) then ex
elseif numberp(ex) and op(ex)="/" then funmake('rat,args(ex))
elseif subvarp(ex) then funmake('subscript,[_spi(op(ex)),map('_spi,args(ex))])
elseif atom(op(ex)) then funmake(_spiop(op(ex)),map('_spi,args(ex)))
else funmake('apply, [_spi(op(ex)),map('_spi,args(ex))])$

_spiop(ex) :=
concat(verbify(if ex=nounify(ex) then "'" else ""), ex)$



On Sun, Jul 23, 2017 at 3:29 PM, Robert Dodier <***@gmail.com<mailto:***@gmail.com>> wrote:
On 2017-07-22, Roland Salz <***@gmail.com<mailto:***@gmail.com>> wrote:

> Why am I writing this? We don't find this feature described in the
> manual. There is a minimal hint where "?" is described, but this hint
> definitively is not enough to understand the scope of this feature
> and its possibilities.

I dunno -- the documentation for ? refers to "Lisp and Maxima" which
does explain ?symbol and :lisp in more detail.

> There is another significant drawback about the current manual, and
> this is its structure. The structure is fairly elaborated and ok up to
> chapter 38, debugging. But after that, the structure basically
> vanishes and the whole thing becomes an encyclopedia of packages, in
> alphabetical order. This means, there is no structured table of
> contents or any index of features or search-terms which are not
> functions or variables.

In the HTML version, there are subject category links which group
together different functions and packages. E.g. the user can look at the
"Simplification" category and see which functions and packages have
something to do with that. Unfortunately I don't see a way to make that
work in other formats.

> The situation is even worse for packages that people write with a lot
> of effort and a lot of time and which then are not even incorporated
> in Maxima any more.

At this point my preference is for package developers to manage their
projects independently, but make it easy for users to install and load.
This, I hope, will encourage a Maxima "ecosystem" similar to the clouds
of projects circling R, Ruby, Python, etc.

Maxima is pretty big already and we are quite short on experienced
developers. I feel pretty strongly that we have our hands full with the
central part of the system and so we must ask package developers to help
us out by managing their own projects.

> the current manual is also dead in some respect, and it should come to
> life again. In my opinion, Maxima will not develop further, if the
> manual doesn't.

I dunno. I can see a couple of substantial improvements to the reference
manual. One is to rewrite and expand some of the items. Some years ago
(10+) I rewrote a lot of the documentation, but didn't touch all of the
items. It wouldn't hurt to identify the ones that could benefit from an
update. The other is to put a concise introductory essay on each
chapter.

But I don't see a need for ongoing revisions. I wouldn't mind if we
could bring the manual to state where it just needs corrections and bug
fixes instead of constant expansion. That would free up our attention to
spend on other topics, of which there are always more.

best

Robert Dodier


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot<https://urldefense.proofpoint.com/v2/url?u=http-3A__sdm.link_slashdot&d=DwMFaQ&c=9ZQuuHhOefNvAzlN-3viIA&r=Y-7rxY5GkJ0PrHulpV2qSA&m=waEUL54RolSIHfCQ-TxpTkfplE9Vo01G61NfxYEO4TE&s=CFscJqtbRYXPhXJ5Ep3UB1aWD0iAXSP0vX4CjoSbawc&e=>
_______________________________________________
Maxima-discuss mailing list
Maxima-***@lists.sourceforge.net<mailto:Maxima-***@lists.sourceforge.net>
https://lists.sourceforge.net/lists/listinfo/maxima-discuss<https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.sourceforge.net_lists_listinfo_maxima-2Ddiscuss&d=DwMFaQ&c=9ZQuuHhOefNvAzlN-3viIA&r=Y-7rxY5GkJ0PrHulpV2qSA&m=waEUL54RolSIHfCQ-TxpTkfplE9Vo01G61NfxYEO4TE&s=LtsqXJyZTwBWSqRn3L5sn2mZCs-H25sIfNDt4_TyrCw&e=>

[Gunter Königsmann]

On 24.07.2017 16:17, Barton Willis wrote:
> I do agree with the OP that improving and the user documentation and
> keeping it up to date is important.
>
>
> Some time ago, I contributed a small package for numerically solving
> hamiltonian systems. Writing the user documentation wasn't the fun part,
> but I did it. And so it goes with volunteer projects.
>

The three points I personally would prioritize if documentation-related
things are to be changed are:

- Maxima's internal help browser lacks support for the menus. Example:

? draw

does only show the introduction to draw, but no real documentation
nor a way of getting documentation.

- If the words I am searching for can be found in the untranslated
part of the german translation google presents me a english page
with outdated and therefore incomplete and partially misleading
documentation. On the plus side it is surprising how much better
the manual has gotten in the last few years that this really makes
a big difference.

- If we had a package manager for maxima packets we would urgently
need a way to add user documentation to the central maxima
documentation / maxima's built in help system / ???

Kind regards,

Gunter.

[Raymond Toy]

>>>>> "Gunter" == Gunter Königsmann <***@peterpall.de> writes:

Gunter> On 24.07.2017 16:17, Barton Willis wrote:
>> I do agree with the OP that improving and the user documentation and
>> keeping it up to date is important.
>>
>>
>> Some time ago, I contributed a small package for numerically solving
>> hamiltonian systems. Writing the user documentation wasn't the fun part,
>> but I did it. And so it goes with volunteer projects.
>>

Gunter> The three points I personally would prioritize if documentation-related
Gunter> things are to be changed are:

Gunter> - Maxima's internal help browser lacks support for the menus. Example:

Gunter> ? draw

Gunter> does only show the introduction to draw, but no real documentation
Gunter> nor a way of getting documentation.

Isn't that a result of the fact that draw documentation isn't part of
maxima? I wish it were though, but nice documentation for draw does
exist.

Gunter> - If we had a package manager for maxima packets we would urgently
Gunter> need a way to add user documentation to the central maxima
Gunter> documentation / maxima's built in help system / ???

It's certainly possible. Don't know about emacs, but xemacs used to
be able to search directories and merge information from each info
file into a nice overall info link page where you could navigate to
the individual info pages.

Would be great if we could do the same.

--
Ray

[Robert Dodier]

While we're mentioning possible improvements for the reference manual, I
think one pretty big improvement would be to document the
simplifications that are known for various operators, and the flags
which control them. E.g. what are the simplifications that are applied
to trig functions, and what are the flags that control them? The flags
are documented by themselves, but there's (mostly) no way to reach the
flags from the affected functions or operators, and simplifications
which are not conditional on flags are mostly not documented.

best

Robert Dodier

[Robert Dodier]

On 2017-07-24, Gunter Königsmann <***@peterpall.de> wrote:

> - If we had a package manager for maxima packets we would urgently
> need a way to add user documentation to the central maxima
> documentation / maxima's built in help system / ???

There are at least two contexts for that and I'm not sure which one you
mean. One context is that a package has been installed (either under the
usual Maxima installation directory or some other well-known place) on
the user's system. Then making the documentation available to the
on-line reference system only requires loading the index file for the
package. It's easy to create such files, the hard part is finding them.
But a worst-case scenario is to just scan a list of well-known
directories and load all foo-index.lisp files, so that's probably
relatively easy to do.

Another context is a package that has not been installed, but let's say
it's listed on some package index web site. I dunno if Maxima should try
to download and load all documentation for all known packages, that just
sounds like too much. I'm not in favor of it. A user would have to know
that the package exists and give a command to install it. That seems
like a reasonable burden to put on the user.

best

Robert Dodier

[Gunter Königsmann]

On 25.07.2017 07:43, Robert Dodier wrote:
> On 2017-07-24, Gunter Königsmann <***@peterpall.de> wrote:
>
> > - If we had a package manager for maxima packets we would urgently
> > need a way to add user documentation to the central maxima
> > documentation / maxima's built in help system / ???
>
> There are at least two contexts for that and I'm not sure which one you
> mean. One context is that a package has been installed (either under the
> usual Maxima installation directory or some other well-known place) on
> the user's system. Then making the documentation available to the
> on-line reference system only requires loading the index file for the
> package. It's easy to create such files, the hard part is finding them.
> But a worst-case scenario is to just scan a list of well-known
> directories and load all foo-index.lisp files, so that's probably
> relatively easy to do.
This one is the one I would prefer:

There are already so many websites with packages that downloading all
information from all of those sites would provide one with way too many
manual pages.

---

Having an central index of maxima packages would be cool, though. Even
if for completeness I would add that maxima is powerful enough that one
could add a malicious package to that index...
...even if I don't know if there is a real solution for that: the index
for ruby or perl still are potentially affected by that problem, for
example.

Kind regards,

Gunter.

[Richard Fateman]

On 7/24/2017 11:41 PM, Gunter Königsmann wrote:
> There are already so many websites with packages that downloading all
> information from all of those sites would provide one with way too many
> manual pages.
Is this solved by having a searchable thing like stackexchange? I
recall vaguely
that this or some similar organizations refused to allow "Maxima"
claiming that
either people could use the Mathematica one or some
"computer-algebra-systems"
but now I notice that there is
https://math.stackexchange.com/questions/tagged/maxima-software
whose contents seem sparse and not particularly useful. Maybe it is not
the same
thing.

or a Maxima "wiki"?


Anything that is curated can seem arbitrary to people whose work is
excluded.
Anything that is not curated can be loaded up with poor contributions or
outright trollery.

[Roland Salz]

> -----Original Message-----
> From: Gunter Königsmann [mailto:***@peterpall.de]
> Sent: Tuesday, July 25, 2017 8:42 AM
>
> Having an central index of maxima packages would be cool, though.

+1 for such an index, including external packages and also the useful ones of the packages that are in Maxima's share directory and are not documented in the manual.

This list should not only be an alphabetic enumeration of package names; it should allow for a brief description of what the package is about. Otherwise a potential user will be rather lost and will not be able to find in a reasonable amount of time what he is looking for.

I don't know how this is done for other systems, but in order to avoid spam or malicious packages or the obviously poorly written ones, or packages that are not maintained at all, it might make sense to have some censorship from behalf of the maxima team as to which package is to be included and which is not. Maybe a voting among the developers, or something like that.

If a mechanism for registering external packages in such an index is set up, and also an easy mechanism for users to access these packages, then the only thing the reference manual would need (but it would really need that!!) is a short, but well-placed section describing this mechanism, both for people who want to add a package and for people who want to get more information about a specific package and download it.

Best regards,
Roland

[Robert Dodier]

On 2017-07-25, Gunter Königsmann <***@peterpall.de> wrote:

> Having an central index of maxima packages would be cool, though. Even
> if for completeness I would add that maxima is powerful enough that one
> could add a malicious package to that index...
> ...even if I don't know if there is a real solution for that: the index
> for ruby or perl still are potentially affected by that problem, for
> example.

As far as I know, the only way to avoid malicious packages is to review
them one at a time. I don't know to what extent the various widely-used
package repositories (Python, Ruby, R, etc) enforce that. It would be
interesting to survey the various repositories and see what range of
policies are in place. It would also be interesting to review any known
attempts to distribute malicious packages of any kind.

I have been toying with the idea of distributing Maxima packages via
Quicklisp, which is essentially a package repository + download
mechanism + ASDF. I believe the packages are reviewed by the Quicklisp
maintainer. Obviously that helps and also obviously it is not a
guarantee.

best,

Robert Dodier

[Raymond]

On 07/25/2017 01:43 AM, Robert Dodier wrote:
> On 2017-07-24, Gunter Königsmann <***@peterpall.de> wrote:
>
>> - If we had a package manager for maxima packets we would urgently
>> need a way to add user documentation to the central maxima
>> documentation / maxima's built in help system / ???
> There are at least two contexts for that and I'm not sure which one you
> mean. One context is that a package has been installed (either under the
> usual Maxima installation directory or some other well-known place) on
> the user's system. Then making the documentation available to the
> on-line reference system only requires loading the index file for the
> package. It's easy to create such files, the hard part is finding them.
> But a worst-case scenario is to just scan a list of well-known
> directories and load all foo-index.lisp files, so that's probably
> relatively easy to do.
>
> Another context is a package that has not been installed, but let's say
> it's listed on some package index web site. I dunno if Maxima should try
> to download and load all documentation for all known packages, that just
> sounds like too much. I'm not in favor of it. A user would have to know
> that the package exists and give a command to install it. That seems
> like a reasonable burden to put on the user.
I would mention that the most useful indexing scheme, that I have
actually used, is a Concordance. I found it human and computer usable.
RayR

[Roland Salz]

From: Barton Willis [mailto:***@unk.edu]
Sent: Monday, July 24, 2017 4:17 PM



I do agree with the OP that improving and the user documentation and keeping it up to date is important.



Maybe my mathematical background is not strong enough for understanding what Maxima sometimes is doing, this may well be. But probably I’m not the only one.



Example: Presently I’m trying to understand what the difference is between log and plog. “Plog represents the principal branch of the complex-valued natural logarithm.” That makes sense. But then what is log? Does it return other branches, or all branches, or what? I see that it returns the principal branch, too. There are differences in the behavior of log and plog, though, and I have little idea what they mean. For instance



log(1+%i); -> log(1+%i) does nothing, whereas

plog(1+%i); -> log(2)/2 + %i*%pi/4 gives a rectform. Why this difference? Well, maybe log does not evaluate/simplify, because it does not want to limit itself to the principal branch. But then



float(log(2+%i)); -> (which is the principal branch, since

float(carg(log(2+%i))); -> !) whereas

float(plog(2+%i)) ->

Why does this not evaluate to a complex floating point number? Why does it only evaluate the realpart of the variable?



Now I’m totally surprised:

plog(2+%i); -> plog(2+%i) This time I don’t get a rectform from plog.

rectform(plog(2+%i)); -> log(5)/2 + %i * atan(1/2) Here it is!



So what do I do? I look into the internet, and the only thing I find about plog is some old threads in the mailing list that don’t really clarify the point either. Maybe I’m missing some tutorial which explains this aspect, but up till now I did not find it. Maybe also I’m missing a general point in understanding Maxima, or more than one. All this is possible.



But my opinion is that the manual should say more about this issue than just: “Plog represents the principal branch of the complex-valued natural logarithm.”



Best regards,

Roland

[Stavros Macrakis (Σταῦρος Μακράκης)]

Grepping through the Maxima source, I see that plog is only used in output
from defint, to inhibit certain incorrect simplifications.

For example, if zz is declared complex, then plog(%e^zz) => plog(%e^zz),
whereas log(%e^zz) => zz

On the other hand, if plog can prove that the argument is positive real, it
simplifies to log: plog((a^2+1)*(b^2+2)) => log(...) (Remember that by
default, Maxima variables are considered to be real.)

plog's handling of zero is a little idiosyncratic: plog(x^2) asks whether
x=0 and gives an error if yes, though I'd think that simplifying to
2*log(x) would be fine, since if x is zero in that simplified form, you get
the same error.

I don't know why plog(1+%i) generates the rectform, while plog(2+%i) does
not.

plog is not very clever. plog(a+b*%i) could perfectly well simplify to
log(a+b*%i) (remembering that variables are assumed real), but doesn't.

---------

Re float(plog(2+%i)) or float(plog(2.0+%i)), float is not specified to
calculate a rectform under *any* circumstances. Cf. float(exp(%i)). Perhaps
we should have a cfloat function to do that.

On Mon, Jul 24, 2017 at 2:03 PM, Roland Salz <***@gmail.com> wrote:

> *From:* Barton Willis [mailto:***@unk.edu]
> *Sent:* Monday, July 24, 2017 4:17 PM
>
> I do agree with the OP that improving and the user documentation and
> keeping it up to date is important.
>
>
>
> Maybe my mathematical background is not strong enough for understanding
> what Maxima sometimes is doing, this may well be. But probably I’m not the
> only one.
>
>
>
> Example: Presently I’m trying to understand what the difference is between
> log and plog. “Plog represents the principal branch of the complex-valued
> natural logarithm.” That makes sense. But then what is log? Does it return
> other branches, or all branches, or what? I see that it returns the
> principal branch, too. There are differences in the behavior of log and
> plog, though, and I have little idea what they mean. For instance
>
>
>
> log(1+%i); -> log(1+%i) does nothing, whereas
>
> plog(1+%i); -> log(2)/2 + %i*%pi/4 gives a rectform. Why this
> difference? Well, maybe log does not evaluate/simplify, because it does not
> want to limit itself to the principal branch. But then
>
>
>
> float(log(2+%i)); -> (which is the principal branch, since
>
> float(carg(log(2+%i))); -> !) whereas
>
> float(plog(2+%i)) ->
>
> Why does this not evaluate to a complex floating point number? Why does it
> only evaluate the realpart of the variable?
>
>
>
> Now I’m totally surprised:
>
> plog(2+%i); -> plog(2+%i) This time I don’t get a rectform from plog.
>
> rectform(plog(2+%i)); -> log(5)/2 + %i * atan(1/2) Here it is!
>
>
>
> So what do I do? I look into the internet, and the only thing I find about
> plog is some old threads in the mailing list that don’t really clarify the
> point either. Maybe I’m missing some tutorial which explains this aspect,
> but up till now I did not find it. Maybe also I’m missing a general point
> in understanding Maxima, or more than one. All this is possible.
>
>
>
> But my opinion is that the manual should say more about this issue than
> just: “Plog represents the principal branch of the complex-valued natural
> logarithm.”
>
>
>
> Best regards,
>
> Roland
>
>
>
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Maxima-discuss mailing list
> Maxima-***@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/maxima-discuss
>
>

[Stavros Macrakis (Σταῦρος Μακράκης)]

A few more comments....

On Mon, Jul 24, 2017 at 2:03 PM, Roland Salz <***@gmail.com> wrote:

> ​...​
>
> Example: Presently I’m trying to understand what the difference is between
> log and plog. “Plog represents the principal branch of the complex-valued
> natural logarithm.” That makes sense. But then what is log? Does it return
> other branches, or all branches, or what? I see that it returns the
> principal branch, too.
>

They both denote the principal branch for constants. The difference comes
with variable arguments like %i*z, where some log simplifications (notably
with logexpand:all) might not preserve the principal value.


> ​..​
> Well, maybe log does not evaluate/simplify, because it does not want to
> limit itself to
> ​​
> the principal branch.
>
>
​First of all, neither log nor plog ever "evaluate", which in Maxima means
to dereference symbol and function values. Calculating 1+1 => 2 or
sin(0.223) => 0.221 is simplification, not evaluation.​ The distinction is
important, though I do understand that this conflicts with the usual
expression "evaluate the sine function at 0.223".

​Secondly, log will never return a non-principal value for a constant. The
only problematic case is a variable argument.​
​
​...​


But my opinion is that the manual should say more about this issue than
> just: “Plog represents the principal branch of the complex-valued natural
> logarithm.”
>

​I think the manual should say "plog represents the principal branch of the
complex-valued natural logarithm *in output from the definite integration
package*. *It should not be used otherwise.*"

More generally, I don't know of any framework for handling multivalued
functions (like log, roots, inverse trig, etc.) in a symbolic system in a
complete, consistent, and useful way. The to_poly_solve system uses integer
variables in its output, e.g., %solve(sin(x)=0,x) => %union([x=%pi*%z194]),
but it is hard to compute with objects like this in general.

Perhaps RJF knows of some publications in this area that could point us in
the right direction.

-s