Am Sonntag, den 02.10.2011, 23:35 +0100 schrieb Rupert Swarbrick:
[...]
> NOTES:
> ======
>
> Some things I changed (intentionally!) from the German text: maybe
> these are improvements.
>
> (1) I pointed at the abs_integrate example when the abs_integrate
> package is mentioned.
Yes, it is helpful to have a hint to the example. I will add this to
German documentation.
> (2) I explained why one should see distribute_over.
Yes, it is helpful to give the user this hint. I will add this to the
German translation.
> (3) Since sqrt and sin are from the English names, I didn't clarify
> what they were in the cabs examples.
In the German manual at this point I use the names of the Maxima
functions with a special formating e.g. @code{sin} and @code{sqrt} and
do not translate these names. Furthermore, for the html-file I add cross
references to the documentation of the functions. Therefore it is
correct not to translate the names of Maxima functions.
The ascii-documentation does not show all special formating and the
cross references. It is more easy to have a look at the
html-documentation on my website
http://crategus.users.sourceforge.net/maxima.html
> Questions I have after reading this, which would be nice to add
> answers for! Providing this isn't just from my poor German, maybe
> answering these could improve the German manual too.
>
> (1) Why is abs_integrate functionality not permanently loaded if it
> improves Maxima's ability to integrate functions with abs() in? (I
> presume the answer is that it slows down general integration, but
> can someone confirm this?)
There is one open problem with the abs_integrate package. When loaded in
Maxima it is no longer possible to use the quote-operator to create a
noun form of an integral.
(%i1) 'integrate(x^2,x);
(%o1) 'integrate(x^2,x)
(%i2) load(abs_integrate)$
(%i3) 'integrate(x^2,x);
(%o3) x^3/3
This problem must be solved first. We have an open bug report about this
problem. The documentation of abs_integrate misses a hint about this
defect.
> (2) Is the repeat of the information about abs_integrate necessary?
> Maybe the text about it can be removed from the examples section,
> since it's already explained above? (Especially if there's a
> forward reference, like I added)
This is a matter of style. At a lot of places in the documentation the
style is to repeat informations in the examples.
> (3) Is there a reason that abs takes z as an argument and cabs takes
> expr?
I have thought about this point when writing the German translation. I
have tried to use a unique convention for naming arguments, because this
is very helpful for the user. The argument z emphasizes that abs is the
mathematical function with one argument which calculates the absolute
value of numbers and simplifies for other arguments.
In contrast the function cabs does not simplify, but decomposes any
expression expr in a realpart and a imagpart and calculates sqrt(x^2
+y^2). This behavior is quite different. cabs works on expressions and
abs simplifies expressions. Therefore, the naming of the argument should
help to distinguish between theses functionalities
> (4) I'm a bit confused about the German in the first sentence of the
> second paragraph in cabs. I suspect that what I wrote isn't quite
> what you meant.
Perhaps, it is possible to change "identities" with "known properties".
You might argue, that symmetry properties are "known properties". Then
it might be even better to write:
"The cabs function can use known properties like symmetry properties of
complex functions to help it calculate the absolute value of an
expression."
The point is, that Maxima has knowledge about functions like a mirror
symmetry. This knowledge is applied when calculating cabs of an
expression. Furthermore, the user can define properties in addition, but
a lot of possible things are not implemented well or are not documented
well. A lot of work is possible on this topic.
> (5) Is it possible for a user to set a property indicating that
> his/her function f has mirror symmetry, say? Maybe this
> documentation should point to the properties a user can set. Maybe
> with an example? (I would suggest wording, but I don't actually
> know how to do this!)
The handling of properties and the documentation is not as good as it
should be. In the German translation I have started to put in more
documentation about this point and I have listed all available
properties symbols and functions have by default and can get by the user
(see an example below). In the German translation there is a cross
reference e.g. to the Maxima function properties.
E.g. these are the defined properties for the function abs, but there is
not much documentation about their usage for the user.
(%i4) properties(abs);
(%o4) [integral,rule,"distributes over bags",noun,gradef,"system
function"]
> (6) Also, what exactly do these properties mean? Are they documented
> elsewhere? (In which case, it would probably be good to have "See
> foo, bar")
See above.
> (7) Is there a reason that cabs doesn't respect distribute_over?
cabs distributes over equations, lists and matrices like the abs
function. But cabs is not a simplifying function and does not call the
simplifier. The property distribute_over is applied by the simplifier.
Therefore, cabs can not use the property distribute_over and it is not
possible to switch off this property.
The diffeent behavior is a consequence of the difference between a noun
and a verb function. Perhaps, I can add a hint for the user about this
point.
Dieter Kaiser
P.S.
This is the documentation of properties in the English manual:
Function: properties (a)
Returns a list of the names of all the properties associated
with the atom a.
This is a first attempt to document the function properties more
complete:
-- Funktion: properties (<a>)
Gibt eine Liste mit den Eigenschaften zur?ck, die das Symbol <a>
von Maxima oder dem Nutzer erhalten hat. Die R?ckgabe kann jede
Eigenschaft enthalten, die mit der Funktion `declare' einem
Symbol zugewiesen ist. Diese Eigenschaften sind:
linear additive multiplicative
outative commutative symmetric
antisymmetric nary lassociativ
rassociative evenfun oddfun
bindtest feature alphabetic
scalar nonscalar nonarray
constant integer noninteger
even odd rational
irrational real imaginary
complex increasing decreasing
posfun integervalued
Die folgenden Eintr?ge beschreiben Eigenschaften, die Variablen
haben k?nnen:
`value'
Der Variable ist mit dem Operatoren `:' oder `::' ein Wert
zugewiesen.
`system value'
Die Variable ist eine Optionsvariable oder Systemvariable,
die von Maxima definiert ist.
`numer'
Die Variable hat einen numerischen Wert auf der
Eigenschaftsliste, der mit der Funktion `numerval'
zugewiesen ist.
`assign property'
Die Variable hat eine eine Funktion auf der
Eigenschaftsliste, die die Zuweisung eines Wertes
kontrolliert.
Eintr?ge, die die Eigenschaften von Funktionen beschreiben:
`function'
Eine mit dem Operator `:=' oder der Funktion `define'
definierte Nutzerfunktion.
`macro'
Eine mit dem Operator `::=' definierte Makrofunktion.
`system function'
Ein interne Maxima-Funktion.
`special evaluation form'
Eine Maxima-Spezialform, die die Argumente nicht auswertet.
`transfun'
Wird eine Nutzerfunktion mit `translate' ?bersetzt oder mit
der Funktion `compile' kompiliert, erh?lt sie die
Eigenschaft `transfun'. Interne Maxima-Funktionen, die mit
dem Lisp-Makro `defmfun' definiert werden, haben ebenfalls
diese Eigenschaft.
`deftaylor'
F?r die Funktion ist eine Taylorreihenentwicklung definiert.
`gradef'
Die Funktion hat eine Ableitung.
`integral'
Die Funktion hat eine Stammfunktion.
`distribute over bags'
Ist das Argument der Funktion eine Liste, Matrix oder
Gleichung so wird die Funktion auf die Elemente oder beide
Seiten der Gleichung angewendet.
`limit function'
Es existiert eine Funktion f?r die Behandlung spezieller
Grenzwerte.
`conjugate function'
Es existiert eine Funktion, um die konjugiert komplexe
Funktion f?r spezielle Wertebereiche zu ermitteln.
`mirror symmetry'
Die Funktion hat die Eigenschaft der Spiegelsymmetrie.
`complex characteristic'
Es existiert eine Funktion, um den Realteil und den
Imagin?rteil der Funktion f?r spezielle Wertebereiche zu
ermitteln.
`user autoload function'
Die Funktion wird automatisch beim ersten Aufruf aus einer
Datei geladen. Der Nutzer kann mit dem Funktion
`setup_autoload' eine solche Funktion definieren.
Weitere Eigenschaften, die Symbole erhalten k?nnen:
`operator'
Das Symbol ist ein Maxima-Operator oder ein nutzerdefinierte
Operator.
`rule'
Die Funktion oder der Operator haben eine Regel f?r die
Vereinfachung.
`alias'
`database info'
Das Symbol hat Eintr?ge in Maximas Datenbank.
`hashed array, declared array, complete array'
Ein Hashed-Array, ein deklariertes Array oder ein Array
dessen Elemente einen bestimmten Typ haben.
`array function'
Eine Array-Funktion die mit dem Operator `:=' definiert ist.
`atvalue'
Dem Symbol ist mit der Funktion `atvalue' ein Wert an einer
Stelle zugewiesen.
`atomgrad'
F?r das Symbol ist mit der Funktion `gradef' eine Ableitung
definiert.
`dependency'
F?r das Symbol ist eine Abh?ngigkeit mit der Funktion
`depends'
definiert.
`matchdeclare'
Das Symbol ist eine mit `matchdeclare' definierte
Mustervariable, der eine Aussagefunktion zugeordnet ist.
`modedeclare'
F?r das Symbol ist mit der Funktion `mode_declare' ein Typ
definiert.
`user properties'
`context'
Das Symbol bezeichnet einen Kontext.
`activecontext'
Das Symbol bezeichnet einen aktiven Kontextes.