Month: October 2016

A home-grown help utility for my Maxima functions

I have written a number of Maxima functions for my students.   I really miss the MATLAB convention by which help(functionname) prints to the console the leading comment lines in the function.  That is really easy for the developer, because the documentation lines within the function also serve as the user documentation in the console.

Maxima’s built-in documentation capabilities ?, ??, example(), demo(), and describe() are, as far as I can tell, unwieldy at best and unsuited for portable documentation to accompany user-written functions.

So, I’ve implemented my own home-grown help utility that can travel along with my *.mac files.  The scheme is:

  • Include in each *.mac file a simple help() utility that when invoked on the maxima command line as help(functionname) calls the ancillary documentation utility functionname_help() contained in the *mac file.  I’ll include this same little utility in all my *.mac files for consistency.
  • This requires that in addition to the functions themselves, the author of the functions include for each function in the *.mac file a help utility with the name convention functionname_help().
  • Upon loading of the *.mac file, I display an invitation to see the contents of the *.mac file using help(macFileName), which again requires an ancillary macFileName_help() function.  The resulting contents message also instructs in the use of the help() utility for functions.

Not as easy to implement as the MATLAB convention, but very workable from the point of view of my students as they learn to use these custom functions.

Below is an example for the ComplexVariables.mac, (which I’ll post in the next few days.)  I plan to use this as a template in all my *.mac files and I really hope the practice catches on in the Maxima community!

/*Complex Variables.mac 
Contents for use with help() */
ComplexVariables_help():=block(
printf(true,
"ComplexVariables.mac contains:
 factorC(f,z)
 partfracC(f,z)
 residueC(f,z,a)
 integratePathC(f,r,t,a,b)
 limitC(f,z,a)
 absC(exp)
 -
 -
 for any of the above functions,
 help(function_name) returns help lines for function_name"
)
);
/* The help utility */
help(_input):=block(
eval_string(sconcat(string(_input),"_help()")
)
);
/* the following is displayed upon loading */
disp("ComplexVariables.mac: help(ComplexVariables) for contents");