> When I
> look collectterms up in the wxMaxima help index it tells me that this is
> a function for re-arranging forms (whatever they are) that are messed up
> by the facexp package (which does something I cannot decipher).
"re-arranging forms" means that it takes an expression and returns an
other but mathematically equivalent expression.
I think facexp basically does what you want. collectterms() is just a
special (speed optimized) case of that.
> That
> documentation says the arguments are:
> collectterms(arg_1,...,arg_n)
> but I was looking for a function with args like:
> collectterms(expr,var_1,...,var_n)
This is a bug in the documentation. Your description seems appropriate.
> To my surprise, if I assume that collectterms does what I want, it
> sometimes does! By dumb luck I found that if I expand the expression
> first, then collectterms always works! (Well, it has in two cases where
> I needed it).
I try to rephrase the documentation a bit to explain what's going on:
Consider you have two expressions with collected terms with respect
to the same variables. Now if you just add this two expressions, the
result usually won't have collected terms, but it's quite easy to do
the transformation in this case. That's the job of collectterms().
I think now it is easy to understand, why expand() helps: Each term
in a full expansion is a trivial case of a term collected expression
and thus a full expansion is a valid input for collectterms().
But I assume using other functions from facexp is generally much
faster than collectterms(expand(expr), var_1, ..., var_n);
> I'm happy now but how come the documentation was no help
> whatsoever
There are not enough people like you giving feedback on it.
> and where do I go the next time I want to do something different?
You are new to maxima, I think you did quite well. If you get to
a weak point of the documentation it will be unavoidable to ask
some questions on this list or get any other peer support.
HTH,
Harald