From: Robert D. <rob...@us...> - 2005-01-20 07:37:09
|
Update of /cvsroot/maxima/maxima/doc/info In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16726 Modified Files: Function.texi Input.texi Log Message: Pasting in some factoids about the actual behavior of translating and compiling (Function.texi) and loading files (Input.texi). Some attempt has been made to clarify the distinctions between related groups of functions (namely translate, compile, etc and load, batch, etc). Index: Function.texi =================================================================== RCS file: /cvsroot/maxima/maxima/doc/info/Function.texi,v retrieving revision 1.20 retrieving revision 1.21 diff -u -d -r1.20 -r1.21 --- Function.texi 19 Jan 2005 16:25:57 -0000 1.20 +++ Function.texi 20 Jan 2005 07:36:59 -0000 1.21 @@ -415,10 +415,16 @@ @end defun -@c COME BACK TO THIS POINT. SKIPPING FORWARD. @defun compfile (filename, f_1, ..., f_n) -Compiles functions @var{f_1}, ..., @var{f_n} into -the file @var{filename}. For convenience, see the @code{compile} function. +Translates Maxima functions @var{f_1}, ..., @var{f_n} into Lisp +and writes the translated code into the file @var{filename}. + +The Lisp translations are not evaluated, nor is the output file processed by the Lisp compiler. +@c SO LET'S CONSIDER GIVING THIS FUNCTION A MORE ACCURATE NAME. +@code{translate} creates and evaluates Lisp translations. +@code{compile_file} translates Maxima into Lisp, and then executes the Lisp compiler. + +See also @code{translate}, @code{translate_file}, and @code{compile_file}. @end defun @@ -436,14 +442,10 @@ @defun compile (@var{f_1}, ..., @var{f_n}) @defunx compile (functions) @defunx compile (all) -Translates Maxima functions into Lisp, executes the Lisp compiler, -and loads the compiler output into Maxima. +Translates Maxima functions into Lisp, evaluates the Lisp translations, +and calls the Lisp function @code{COMPILE} on each translated function. @code{compile} returns a list of the names of the compiled functions. -@code{compile (@var{f_1}, ..., @var{f_n})} compiles the functions @var{f_1}, ..., @var{f_n}. -@c REALLY ??? -It uses the name of function1 as the first name of the file to put the Lisp output. - @code{compile (all)} or @code{compile (functions)} compiles all user-defined functions. @code{compile} quotes its arguments; @@ -767,10 +769,15 @@ @end defvar @defun translate (@var{f_1}, ..., @var{f_n}) +@defunx translate (functions) +@defunx translate (all) Translates the user defined functions -@var{f_1}, ..., @var{f_n} from the Maxima language into Lisp. +@var{f_1}, ..., @var{f_n} from the Maxima language into Lisp +and evaluates the Lisp translations. Typically the translated functions run faster than the originals. +@code{translate (all)} or @code{translate (functions)} translates all user-defined functions. + Functions to be translated should include a call to @code{mode_declare} at the beginning when possible in order to produce more efficient code. For example: @@ -1166,8 +1173,8 @@ @defun compile_file (filename) @defunx compile_file (filename, compiled_filename) @defunx compile_file (filename, compiled_filename, lisp_filename) -Translates @var{filename} into Lisp, -compiles the resulting Lisp code, +Translates the Maxima file @var{filename} into Lisp, +executes the Lisp compiler, and, if the translation and compilation succeed, loads the compiled code into Maxima. @code{compile_file} returns a list of the names of four files: Index: Input.texi =================================================================== RCS file: /cvsroot/maxima/maxima/doc/info/Input.texi,v retrieving revision 1.27 retrieving revision 1.28 diff -u -d -r1.27 -r1.28 --- Input.texi 3 Dec 2004 07:25:21 -0000 1.27 +++ Input.texi 20 Jan 2005 07:36:59 -0000 1.28 @@ -133,6 +133,9 @@ @code{filename} comprises a sequence of Maxima expressions, each terminated with @code{;} or @code{$}. +The special variable @code{%} and the function @code{%th} +refer to previous results within the file. +The file may include @code{:lisp} constructs. Spaces, tabs, and newlines in the file are ignored. A suitable input file may be created by a text editor or by the @code{stringout} function. @@ -157,6 +160,8 @@ to give error-free demonstrations, or to help organize one's thinking in solving complex problems. +@code{batch} evaluates its argument. + See also @code{load}, @code{batchload}, and @code{demo}. @end defun @@ -168,7 +173,13 @@ Printed output (such as produced by @code{print} or @code{describe}) is displayed, however. +The special variable @code{%} and the function @code{%th} +refer to previous results from the interactive interpreter, +not results within the file. +The file cannot include @code{:lisp} constructs. + @code{batchload} returns the path of @code{filename}, as a string. +@code{batchload} evaluates its argument. See also @code{batch} and @code{load}. @c batchload APPEARS TO HAVE THE SAME EFFECT AS load. WHY NOT GET RID OF batchload ??? @@ -676,31 +687,37 @@ To find the file, @code{load} calls @code{file_search} with @code{file_search_maxima} and @code{file_search_lisp} as the search directories. -If @code{load} succeeds, it returns the path of the file. +If @code{load} succeeds, it returns the name of the file. Otherwise @code{load} prints an error message. @code{load} works equally well for Lisp code and Maxima code. Files created by @code{save}, @code{translate_file}, and @code{compile_file}, which create Lisp code, and @code{stringout}, which creates Maxima code, can all be processed by @code{load}. -See also @code{loadfile}, @code{batch}, and @code{demo}. +@code{load} calls @code{loadfile} to load Lisp files and @code{batchload} to load Maxima files. + +See also @code{loadfile}, @code{batch}, @code{batchload}, and @code{demo}. @code{loadfile} processes Lisp files; -@code{batch} and @code{demo} process Maxima files. +@code{batch}, @code{batchload}, and @code{demo} process Maxima files. See @code{file_search} for more detail about the file search mechanism. +@code{load} evaluates its argument. + @end defun @defun loadfile (filename) Evaluates Lisp expressions in @code{filename}. -@code{loadfile} quotes its argument, so @code{filename} must be a literal string, -not a string variable. -Also, @code{loadfile} does not invoke @code{file_search}, so @code{filename} must include +@code{loadfile} does not invoke @code{file_search}, so @code{filename} must include the file extension and as much of the path as needed to find the file. @code{loadfile} can process files created by @code{save}, @code{translate_file}, and @code{compile_file}. The user may find it more convenient to use @code{load} instead of @code{loadfile}. +@code{loadfile} quotes its argument, so @code{filename} must be a literal string, +not a string variable. +The double-single-quote operator defeats quotation. + @end defun @c SEEMS TO STILL EXIST; NEEDS UPDATING !!! |