@menu
* Introduction to Input and Output::  
* Comments::
* Files::                       
* Definitions for Input and Output::  
@end menu

@node Introduction to Input and Output, Comments, Input and Output, Input and Output
@section Introduction to Input and Output

@node Comments, Files, Introduction to Input and Output, Input and Output
@section Comments

A comment in Maxima input is any text between @code{/*} and @code{*/}.

The Maxima parser treats a comment as whitespace for the purpose of
finding tokens in the input stream;
a token always ends at a comment.
An input such as @code{a/* foo */b} contains two tokens, @code{a} and @code{b},
and not a single token @code{ab}.
Comments are otherwise ignored by Maxima;
neither the content nor the location of comments is stored in parsed input expressions.

Comments can be nested to arbitrary depth.
The @code{/*} and @code{*/} delimiters form matching pairs.
There must be the same number of @code{/*} as there are @code{*/}.

Examples:

@c ===beg===
@c /* aa is a variable of interest */  aa : 1234;
@c /* Value of bb depends on aa */  bb : aa^2;
@c /* User-defined infix operator */  infix ("b");
@c /* Parses same as a b c, not abc */  a/* foo */b/* bar */c;
@c /* Comments /* can be nested /* to arbitrary depth */ */ */  1 + xyz;
@c ===end===
@example
(%i1) /* aa is a variable of interest */  aa : 1234;
(%o1)                         1234
(%i2) /* Value of bb depends on aa */  bb : aa^2;
(%o2)                        1522756
(%i3) /* User-defined infix operator */  infix ("b");
(%o3)                           b
(%i4) /* Parses same as a b c, not abc */  a/* foo */b/* bar */c;
(%o4)                         a b c
(%i5) /* Comments /* can be nested /* to arbitrary depth */ */ */  1 + xyz;
(%o5)                        xyz + 1
@end example


@node Files, Definitions for Input and Output, Comments, Input and Output
@section Files
A file is simply an area on a particular storage device which contains data or text.
Files on the disks are figuratively grouped into "directories".
A directory is just a list of files.
Commands which deal with files are:
@code{save},
@code{load},
@code{loadfile},
@code{stringout},
@code{batch},
@code{demo},
@code{writefile},
@code{closefile},
and
@code{appendfile}.

@node Definitions for Input and Output,  , Files, Input and Output
@section Definitions for Input and Output

@defvr {System variable} __

@code{__} is the input expression currently being evaluated.
That is, while an input expression @var{expr} is being evaluated, @code{__} is @var{expr}.

@code{__} is assigned the input expression before the input is simplified or evaluated.
However, the value of @code{__} is simplified (but not evaluated) when it is displayed.

@code{__} is recognized by @code{batch} and @code{load}.
In a file processed by @code{batch},
@code{__} has the same meaning as at the interactive prompt.
In a file processed by @code{load},
@code{__} is bound to the input expression most recently entered at the interactive prompt
or in a batch file;
@code{__} is not bound to the input expressions in the file being processed.
In particular, when @code{load (@var{filename})} is called from the interactive prompt,
@code{__} is bound to @code{load (@var{filename})}
while the file is being processed.

See also @code{_} and @code{%}.

Examples:

@c ===beg===
@c print ("I was called as", __);
@c foo (__);
@c g (x) := (print ("Current input expression =", __), 0);
@c [aa : 1, bb : 2, cc : 3];
@c (aa + bb + cc)/(dd + ee + g(x));
@c ===end===
@example
(%i1) print ("I was called as", __);
I was called as print(I was called as, __) 
(%o1)              print(I was called as, __)
(%i2) foo (__);
(%o2)                     foo(foo(__))
(%i3) g (x) := (print ("Current input expression =", __), 0);
(%o3) g(x) := (print("Current input expression =", __), 0)
(%i4) [aa : 1, bb : 2, cc : 3];
(%o4)                       [1, 2, 3]
(%i5) (aa + bb + cc)/(dd + ee + g(x));
                            cc + bb + aa
Current input expression = -------------- 
                           g(x) + ee + dd
                                6
(%o5)                        -------
                             ee + dd
@end example

@end defvr

@defvr {System variable} _

@code{_} is the most recent input expression (e.g., @code{%i1}, @code{%i2}, @code{%i3}, ...).

@code{_} is assigned the input expression before the input is simplified or evaluated.
However, the value of @code{_} is simplified (but not evaluated) when it is displayed.

@code{_} is recognized by @code{batch} and @code{load}.
In a file processed by @code{batch},
@code{_} has the same meaning as at the interactive prompt.
In a file processed by @code{load},
@code{_} is bound to the input expression most recently evaluated at the interactive prompt
or in a batch file;
@code{_} is not bound to the input expressions in the file being processed.

See also @code{__} and @code{%}.

Examples:

@c ===beg===
@c 13 + 29;
@c :lisp $_
@c _;
@c sin (%pi/2);
@c :lisp $_
@c _;
@c a: 13$
@c b: 29$
@c a + b;
@c :lisp $_
@c _;
@c a + b;
@c ev (_);
@c ===end===
@example
(%i1) 13 + 29;
(%o1)                          42
(%i2) :lisp $_
((MPLUS) 13 29)
(%i2) _;
(%o2)                          42
(%i3) sin (%pi/2);
(%o3)                           1
(%i4) :lisp $_
((%SIN) ((MQUOTIENT) $%PI 2))
(%i4) _;
(%o4)                           1
(%i5) a: 13$
(%i6) b: 29$
(%i7) a + b;
(%o7)                          42
(%i8) :lisp $_
((MPLUS) $A $B)
(%i8) _;
(%o8)                         b + a
(%i9) a + b;
(%o9)                          42
(%i10) ev (_);
(%o10)                         42
@end example

@end defvr

@defvr {System variable} %
@code{%} is the output expression (e.g., @code{%o1}, @code{%o2}, @code{%o3}, ...)
most recently computed by Maxima,
whether or not it was displayed.

@code{%} is recognized by @code{batch} and @code{load}.
In a file processed by @code{batch},
@code{%} has the same meaning as at the interactive prompt.
In a file processed by @code{load},
@code{%} is bound to the output expression most recently computed at the interactive prompt
or in a batch file;
@code{%} is not bound to output expressions in the file being processed.

See also @code{_}, @code{%%}, and @code{%th}.

@end defvr

@defvr {System variable} %%
In compound statements,
namely @code{block}, @code{lambda}, or @code{(@var{s_1}, ..., @var{s_n})},
@code{%%} is the value of the previous statement.
For example,

@example
block (integrate (x^5, x), ev (%%, x=2) - ev (%%, x=1));
block ([prev], prev: integrate (x^5, x), ev (prev, x=2) - ev (prev, x=1));
@end example

yield the same result, namely @code{21/2}.

A compound statement may comprise other compound statements.
Whether a statement be simple or compound, 
@code{%%} is the value of the previous statement.
For example,

@example
block (block (a^n, %%*42), %%/6)
@end example

yields @code{7*a^n}.

Within a compound statement, the value of @code{%%} may be inspected at a break prompt,
which is opened by executing the @code{break} function.
For example, at the break prompt opened by

@example
block (a: 42, break ())$
@end example

entering @code{%%;} yields @code{42}.

At the first statement in a compound statement,
or outside of a compound statement,
@code{%%} is undefined.

@code{%%} is recognized by @code{batch} and @code{load},
and it has the same meaning as at the interactive prompt.

See also @code{%}.

@end defvr

@defvr {Option variable} %edispflag
Default value: @code{false}

When @code{%edispflag} is @code{true},
Maxima displays @code{%e} to a negative exponent as a quotient.
For example, @code{%e^-x} is displayed as @code{1/%e^x}.

@end defvr

@deffn {Function} %th (@var{i})
The value of the @var{i}'th previous output expression.
That is, if the next expression to be computed is the @var{n}'th output,
@code{%th (@var{m})} is the (@var{n} - @var{m})'th output.

@code{%th} is useful in @code{batch} files or for referring to a group of output expressions.
For example,

@example
block (s: 0, for i:1 thru 10 do s: s + %th (i))$
@end example

sets @code{s} to the sum of the last ten output expressions.

@code{%th} is recognized by @code{batch} and @code{load}.
In a file processed by @code{batch},
@code{%th} has the same meaning as at the interactive prompt.
In a file processed by @code{load},
@code{%th} refers to output expressions most recently computed at the interactive prompt
or in a batch file;
@code{%th} does not refer to output expressions in the file being processed.

See also @code{%}.

@end deffn

@deffn {Special symbol} ?
As prefix to a function or variable name, @code{?} signifies that the
name is a Lisp name, not a Maxima name.
For example, @code{?round} signifies the Lisp function @code{ROUND}.
See @ref{Lisp and Maxima} for more on this point.

The notation @code{? word} (a question mark followed a word, separated by whitespace)
is equivalent to @code{describe ("word")}.

@end deffn

@defvr {Option variable} absboxchar
Default value: @code{!}

@code{absboxchar} is the character used to draw absolute value
signs around expressions which are more than one line tall.

@end defvr

@defvr {Option variable} file_output_append
Default value: @code{false}

@code{file_output_append} governs whether file output functions
append or truncate their output file.
When @code{file_output_append} is @code{true},
such functions append to their output file.
Otherwise, the output file is truncated.

@code{save}, @code{stringout}, and @code{with_stdout} respect @code{file_output_append}.
Other functions which write output files do not respect @code{file_output_append}.
In particular, plotting and translation functions always truncate their output file,
and @code{tex} and @code{appendfile} always append.
@c WHAT ABOUT WRITEFILE ??

@end defvr

@deffn {Function} appendfile (@var{filename})
Appends a console transcript to @var{filename}.
@code{appendfile} is the same as @code{writefile}, 
except that the transcript file, if it exists, is always appended.

@code{closefile} closes the transcript file opened by @code{appendfile} or @code{writefile}.

@end deffn

@c batch CAN TAKE 'test AS AN OPTIONAL ARGUMENT IN WHICH CASE IT CALLS test-batch
@c (SAME AS run_testsuite) -- SHOULD DOCUMENT batch (file, 'test)
@c FIX BUG WHICH CAUSES batch (<file>, 'test) TO FAIL, THEN DOCUMENT IT HERE
@deffn {Function} batch (@var{filename})
Reads Maxima expressions from @var{filename} and evaluates them.
@code{batch} searches for @var{filename} in the list @code{file_search_maxima}.
See @code{file_search}.

@var{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.

@code{batch} reads each input expression from @var{filename},
displays the input to the console, 
computes the corresponding output expression,
and displays the output expression.
Input labels are assigned to the input expressions
and output labels are assigned to the output expressions.
@code{batch} evaluates every input expression in the file
unless there is an error.
If user input is requested (by @code{asksign} or @code{askinteger}, for example)
@code{batch} pauses to collect the requisite input and then continue.

@c CTRL-C BREAKS batch IN CMUCL, BUT CLISP (ALTHO IT SHOWS "User break") KEEPS GOING !!!
@c DON'T KNOW ABOUT GCL !!!
It may be possible to halt @code{batch} by typing @code{control-C} at the console.
The effect of @code{control-C} depends on the underlying Lisp implementation.

@code{batch} has several uses,
such as to provide a reservoir for working command lines,
to give error-free demonstrations,
or to help organize one's thinking in solving complex problems.

@code{batch} evaluates its argument.
@c LACK OF A RETURN VALUE IS A BUG; THE INTENT IS TO RETURN THE FILE PATH, TO JUDGE BY THE SOURCE CODE
@code{batch} has no return value.

See also @code{load}, @code{batchload}, and @code{demo}.

@end deffn

@c RECOMMEND CUTTING THIS ITEM, AS THE load SUBSUMES FUNCTIONALITY OF batchload
@deffn {Function} batchload (@var{filename})
Reads Maxima expressions from @var{filename} and evaluates them,
without displaying the input or output expressions
and without assigning labels to output expressions.
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 @var{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 ???

@end deffn

@deffn {Function} closefile ()
Closes the transcript file opened by @code{writefile} or @code{appendfile}.

@end deffn

@c NEEDS CLARIFICATION !!!
@deffn {Function} collapse (@var{expr})
Collapses @var{expr} by causing all of its
common (i.e., equal) subexpressions to share (i.e., use the same cells),
thereby saving space.  (@code{collapse} is a subroutine used by the @code{optimize}
command.)  Thus, calling @code{collapse} may be useful
after loading in a @code{save} file.  You can collapse several expressions
together by using @code{collapse ([@var{expr_1}, ..., @var{expr_n}])}.  Similarly, you can
collapse the elements of the array @code{A} by doing
@code{collapse (listarray ('A))}.

@end deffn

@deffn {Function} concat (@var{arg_1}, @var{arg_2}, ...)
Concatenates its arguments.
The arguments must evaluate to atoms.
The return value is a symbol if the first argument is a symbol
and a Maxima string otherwise.

@code{concat} evaluates its arguments.
The single quote @code{'} prevents evaluation.

@example
(%i1) y: 7$
(%i2) z: 88$
(%i3) concat (y, z/2);
(%o3)                          744
(%i4) concat ('y, z/2);
(%o4)                          y44
@end example

A symbol constructed by @code{concat} may
be assigned a value and appear in expressions.
The @code{::} (double colon) assignment operator evaluates its left-hand side.

@example
(%i5) a: concat ('y, z/2);
(%o5)                          y44
(%i6) a:: 123;
(%o6)                          123
(%i7) y44;
(%o7)                          123
(%i8) b^a;
                               y44
(%o8)                         b
(%i9) %, numer;
                               123
(%o9)                         b
@end example

Note that although @code{concat (1, 2)} looks like a number, it is a Maxima string.

@example
(%i10) concat (1, 2) + 3;
(%o10)                       12 + 3
@end example

@end deffn

@deffn {Function} sconcat (@var{arg_1}, @var{arg_2}, ...)

Concatenates its arguments into a string.
Unlike @code{concat}, the arguments do @i{not} need to be atoms.

The result is a Lisp string.
@c THAT'S ODD; WHY NOT A MAXIMA STRING ??

@example
(%i1) sconcat ("xx[", 3, "]:", expand ((x+y)^3));
(%o1)               xx[3]:y^3+3*x*y^2+3*x^2*y+x^3
@end example

@end deffn

@c AFTER REVIEWING src/displa.lisp, IT LOOKS LIKE THIS VARIABLE HAS NO EFFECT
@c CUT IT ON THE NEXT PASS
@c @defvar cursordisp
@c Default value: @code{true}
@c 
@c When @code{cursordisp} is @code{true}, expressions are drawn by
@c the displayer in logical sequence.  This only works with a console
@c which can do cursor movement.  If @code{false}, expressions are
@c printed line by line.
@c 
@c @code{cursordisp} is always @code{false} when a @code{writefile} is in
@c effect.
@c 
@c @end defvar

@c REPHRASE, NEEDS EXAMPLES
@deffn {Function} disp (@var{expr_1}, @var{expr_2}, ...)
is like @code{display} but only the value of the
arguments are displayed rather than equations.  This is useful for
complicated arguments which don't have names or where only the value
of the argument is of interest and not the name.

@end deffn

@c HMM, THIS NEXT ITEM IS DEFINED IN A SHARE FILE (itensor.lisp); 
@c DOES ITS DESCRIPTION WANT TO BE ELSEWHERE ???
@deffn {Function} dispcon (@var{tensor_1}, @var{tensor_2}, ...)
@deffnx {Function} dispcon (all)
Displays the contraction properties of
its arguments as were given to @code{defcon}.  @code{dispcon (all)} displays all the
contraction properties which were defined.

@end deffn

@c REPHRASE, MORE EXAMPLES
@deffn {Function} display (@var{expr_1}, @var{expr_2}, ...)
Displays equations whose left side is
@var{expr_i} unevaluated, and whose right side is the value of the expression
centered on the line.  This function is useful in blocks and @code{for}
statements in order to have intermediate results displayed.  The
arguments to @code{display} are usually atoms, subscripted variables, or
function calls.  See also @code{disp}.

@example
(%i1) display(B[1,2]);
                                      2
                         B     = X - X
                          1, 2
(%o1)                            done
@end example

@end deffn

@defvr {Option variable} display2d
Default value: @code{true}

When @code{display2d} is @code{false},
the console display is a string (1-dimensional) form rather than a display
(2-dimensional) form.

@end defvr

@defvr {Option variable} display_format_internal
Default value: @code{false}

When @code{display_format_internal} is @code{true},
expressions are displayed without being transformed in ways that
hide the internal mathematical representation.  The display then
corresponds to what @code{inpart} returns rather than @code{part}.

Examples:

@example
User     part       inpart
a-b;      A - B     A + (- 1) B

           A            - 1
a/b;       -         A B
           B
                       1/2
sqrt(x);   sqrt(X)    X

          4 X        4
X*4/3;    ---        - X
           3         3
@end example

@end defvr

@c IS THIS FUNCTION STILL USEFUL ???
@c REPHRASE, NEEDS EXAMPLES
@deffn {Function} dispterms (@var{expr})
Displays @var{expr} in parts one below the other.
That is, first the operator of @var{expr} is displayed, then each term in
a sum, or factor in a product, or part of a more general expression is
displayed separately.  This is useful if @var{expr} is too large to be
otherwise displayed.  For example if @code{P1}, @code{P2}, ...  are very large
expressions then the display program may run out of storage space in
trying to display @code{P1 + P2 + ...}  all at once.  However,
@code{dispterms (P1 + P2 + ...)} displays @code{P1}, then below it @code{P2}, etc.  When not
using @code{dispterms}, if an exponential expression is too wide to be
displayed as @code{A^B} it appears as @code{expt (A, B)} (or as @code{ncexpt (A, B)} in
the case of @code{A^^B}).

@end deffn

@defvr {Option variable} error_size
Default value: 10

@code{error_size} modifies error messages according to the size of expressions which appear in them.
If the size of an expression (as determined by the Lisp function @code{ERROR-SIZE})
is greater than @code{error_size},
the expression is replaced in the message by a symbol,
and the symbol is assigned the expression.
The symbols are taken from the list @code{error_syms}.

Otherwise, the expression is smaller than @code{error_size},
and the expression is displayed in the message.

See also @code{error} and @code{error_syms}.

Example:
@c OUTPUT GENERATED BY THE FOLLOWING
@c U: (C^D^E + B + A)/(cos(X-1) + 1)$
@c error_size: 20$
@c error ("Example expression is", U);
@c errexp1;
@c error_size: 30$
@c error ("Example expression is", U);

The size of @code{U}, as determined by @code{ERROR-SIZE}, is 24.

@example
(%i1) U: (C^D^E + B + A)/(cos(X-1) + 1)$

(%i2) error_size: 20$

(%i3) error ("Example expression is", U);

Example expression is errexp1
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i4) errexp1;
                            E
                           D
                          C   + B + A
(%o4)                    --------------
                         cos(X - 1) + 1
(%i5) error_size: 30$

(%i6) error ("Example expression is", U);

                         E
                        D
                       C   + B + A
Example expression is --------------
                      cos(X - 1) + 1
 -- an error.  Quitting.  To debug this try debugmode(true);
@end example

@end defvr

@defvr {Option variable} error_syms
Default value: @code{[errexp1, errexp2, errexp3]}

In error messages,
expressions larger than @code{error_size} are replaced by symbols, and the
symbols are set to the expressions.  The symbols are taken from the
list @code{error_syms}.
The first too-large expression is replaced by @code{error_syms[1]},
the second by @code{error_syms[2]}, and so on.

If there are more too-large expressions than there are elements of @code{error_syms},
symbols are constructed automatically,
with the @var{n}-th symbol equivalent to @code{concat ('errexp, @var{n})}.

See also @code{error} and @code{error_size}.

@end defvr

@deffn {Function} expt (@var{a}, @var{b})
If an exponential expression is too wide to be displayed
as @code{@var{a}^@var{b}} it appears as @code{expt (@var{a}, @var{b})} (or as @code{ncexpt (@var{a}, @var{b})} in the case of
@code{@var{a}^^@var{b}}).

@c THIS SEEMS LIKE A BUG TO ME. expt, ncexpt SHOULD BE RECOGNIZED SINCE MAXIMA
@c ITSELF PRINTS THEM SOMETIMES. THESE SHOULD JUST SIMPLIFY TO ^ AND ^^, RESPECTIVELY.
@code{expt} and @code{ncexpt} are not recognized in input.

@end deffn

@defvr {Option variable} exptdispflag
Default value: @code{true}

When @code{exptdispflag} is @code{true}, Maxima displays expressions
with negative exponents using quotients, e.g., @code{X^(-1)} as @code{1/X}.

@end defvr

@c NEEDS EXAMPLES
@deffn {Function} filename_merge (@var{path}, @var{filename})
Constructs a modified path from @var{path} and @var{filename}.
If the final component of @var{path} is of the form @code{###.@var{something}},
the component is replaced with @code{@var{filename}.@var{something}}.
Otherwise, the final component is simply replaced by @var{filename}.

@c SAY SOMETHING ABOUT ARG TYPE -- LISP STRINGS WORK BETTER THAN MAXIMA STRINGS
@c SAY SOMETHING ABOUT RETURN TYPE
@end deffn

@deffn {Function} file_search (@var{filename})
@deffnx {Function} file_search (@var{filename}, @var{pathlist})

@code{file_search} searches for the file @var{filename} and returns the path to the file
(as a string) if it can be found; otherwise @code{file_search} returns @code{false}.
@code{file_search (@var{filename})} searches in the default search directories,
which are specified by the @code{file_search_maxima}, @code{file_search_lisp}, and @code{file_search_demo} variables.

@code{file_search} first checks if the actual name passed exists,
before attempting to match it to ``wildcard'' file search patterns.
See @code{file_search_maxima} concerning file search patterns.

The argument @var{filename} can be a path and file name,
or just a file name, or, if a file search directory includes a file search pattern,
just the base of the file name (without an extension).
For example,

@example
file_search ("/home/wfs/special/zeta.mac");
file_search ("zeta.mac");
file_search ("zeta");
@end example

all find the same file, assuming the file exists and @code{/home/wfs/special/###.mac}
is in @code{file_search_maxima}.

@code{file_search (@var{filename}, @var{pathlist})} searches only in the directories
specified by @var{pathlist},
which is a list of strings.
The argument @var{pathlist} supersedes the default search directories,
so if the path list is given, @code{file_search} searches only the ones specified,
and not any of the default search directories.
Even if there is only one directory in @var{pathlist}, it must still be given as a one-element list.

The user may modify the default search directories. See @code{file_search_maxima}.

@code{file_search} is invoked by @code{load} with @code{file_search_maxima} and @code{file_search_lisp}
as the search directories.

@end deffn

@defvr {Option variable} file_search_maxima
@defvrx {Option variable} file_search_lisp
@defvrx {Option variable} file_search_demo
These variables specify lists of directories to be searched
by @code{load}, @code{demo}, and some other Maxima functions.
The default values of these variables
name various directories in the Maxima installation.

The user can modify these variables,
either to replace the default values or to append additional directories.
For example,

@example
file_search_maxima: ["/usr/local/foo/###.mac",
    "/usr/local/bar/###.mac"]$
@end example

replaces the default value of @code{file_search_maxima},
while

@example
file_search_maxima: append (file_search_maxima,
    ["/usr/local/foo/###.mac", "/usr/local/bar/###.mac"])$
@end example

appends two additional directories.
It may be convenient to put such an expression in the file @code{maxima-init.mac}
so that the file search path is assigned automatically when Maxima starts.

Multiple filename extensions and multiple paths can be specified by
special ``wildcard'' constructions.
The string @code{###} expands into the sought-after name,
while a comma-separated list enclosed in curly braces @code{@{foo,bar,baz@}} expands
into multiple strings.
For example, supposing the sought-after name is @code{neumann},

@example
"/home/@{wfs,gcj@}/###.@{lisp,mac@}"
@end example

expands into @code{/home/wfs/neumann.lisp}, @code{/home/gcj/neumann.lisp}, @code{/home/wfs/neumann.mac}, and @code{/home/gcj/neumann.mac}.

@end defvr

@deffn {Function} file_type (@var{filename})
Returns a guess about the content of @var{filename},
based on the filename extension.
@var{filename} need not refer to an actual file;
no attempt is made to open the file and inspect the content.

The return value is a symbol, either @code{object}, @code{lisp}, or @code{maxima}.
If the extension starts with @code{m} or @code{d}, @code{file_type} returns @code{maxima}.
If the extension starts with @code{l}, @code{file_type} returns @code{lisp}.
If none of the above, @code{file_type} returns @code{object}.

@end deffn

@deffn {Function} grind (@var{expr})
@deffnx {Option variable} grind
The function @code{grind} prints @var{expr}
to the console in a form suitable for input to Maxima.
@code{grind} always returns @code{done}.

When @var{expr} is the name of a function or macro,
@code{grind} prints the function or macro definition instead of just the name.

See also @code{string}, which returns a string instead of printing its output.
@code{grind} attempts to print the expression in a manner which makes it
slightly easier to read than the output of @code{string}.

When the variable @code{grind} is @code{true},
the output of @code{string} and @code{stringout} has the same format as that of @code{grind};
otherwise no attempt is made to specially format the output of those functions.
The default value of the variable @code{grind} is @code{false}.

@code{grind} can also be specified as an argument of @code{playback}.
When @code{grind} is present,
@code{playback} prints input expressions in the same format as the @code{grind} function.
Otherwise, no attempt is made to specially format input expressions.

@code{grind} evaluates its argument.

Examples:

@c ===beg===
@c aa + 1729;
@c grind (%);
@c [aa, 1729, aa + 1729];
@c grind (%);
@c matrix ([aa, 17], [29, bb]);
@c grind (%);
@c set (aa, 17, 29, bb);
@c grind (%);
@c exp (aa / (bb + 17)^29);
@c grind (%);
@c expr: expand ((aa + bb)^10);
@c grind (expr);
@c string (expr);
@c cholesky (A):= block ([n : length (A), L : copymatrix (A),
@c p : makelist (0, i, 1, length (A))], for i thru n do for j : i thru n do
@c (x : L[i, j], x : x - sum (L[j, k] * L[i, k], k, 1, i - 1), if i = j then
@c p[i] : 1 / sqrt(x) else L[j, i] : x * p[i]), for i thru n do L[i, i] : 1 / p[i],
@c for i thru n do for j : i + 1 thru n do L[i, j] : 0, L)$
@c grind (cholesky);
@c string (fundef (cholesky));
@c ===end===
@example
(%i1) aa + 1729;
(%o1)                       aa + 1729
(%i2) grind (%);
aa+1729$
(%o2)                         done
(%i3) [aa, 1729, aa + 1729];
(%o3)                 [aa, 1729, aa + 1729]
(%i4) grind (%);
[aa,1729,aa+1729]$
(%o4)                         done
(%i5) matrix ([aa, 17], [29, bb]);
                           [ aa  17 ]
(%o5)                      [        ]
                           [ 29  bb ]
(%i6) grind (%);
matrix([aa,17],[29,bb])$
(%o6)                         done
(%i7) set (aa, 17, 29, bb);
(%o7)                   @{17, 29, aa, bb@}
(%i8) grind (%);
@{17,29,aa,bb@}$
(%o8)                         done
(%i9) exp (aa / (bb + 17)^29);
                                aa
                            -----------
                                     29
                            (bb + 17)
(%o9)                     %e
(%i10) grind (%);
%e^(aa/(bb+17)^29)$
(%o10)                        done
(%i11) expr: expand ((aa + bb)^10);
         10           9        2   8         3   7         4   6
(%o11) bb   + 10 aa bb  + 45 aa  bb  + 120 aa  bb  + 210 aa  bb
         5   5         6   4         7   3        8   2
 + 252 aa  bb  + 210 aa  bb  + 120 aa  bb  + 45 aa  bb
        9        10
 + 10 aa  bb + aa
(%i12) grind (expr);
bb^10+10*aa*bb^9+45*aa^2*bb^8+120*aa^3*bb^7+210*aa^4*bb^6
     +252*aa^5*bb^5+210*aa^6*bb^4+120*aa^7*bb^3+45*aa^8*bb^2
     +10*aa^9*bb+aa^10$
(%o12)                        done
(%i13) string (expr);
(%o13) bb^10+10*aa*bb^9+45*aa^2*bb^8+120*aa^3*bb^7+210*aa^4*bb^6\
+252*aa^5*bb^5+210*aa^6*bb^4+120*aa^7*bb^3+45*aa^8*bb^2+10*aa^9*\
bb+aa^10
(%i14) cholesky (A):= block ([n : length (A), L : copymatrix (A),
p : makelist (0, i, 1, length (A))], for i thru n do for j : i thru n do
(x : L[i, j], x : x - sum (L[j, k] * L[i, k], k, 1, i - 1), if i = j then
p[i] : 1 / sqrt(x) else L[j, i] : x * p[i]), for i thru n do L[i, i] : 1 / p[i],
for i thru n do for j : i + 1 thru n do L[i, j] : 0, L)$
(%i15) grind (cholesky);
cholesky(A):=block(
         [n:length(A),L:copymatrix(A),
          p:makelist(0,i,1,length(A))],
         for i thru n do
             (for j from i thru n do
                  (x:L[i,j],x:x-sum(L[j,k]*L[i,k],k,1,i-1),
                   if i = j then p[i]:1/sqrt(x)
                       else L[j,i]:x*p[i])),
         for i thru n do L[i,i]:1/p[i],
         for i thru n do (for j from i+1 thru n do L[i,j]:0),L)$
(%o15)                        done
(%i16) string (fundef (cholesky));
(%o16) cholesky(A):=block([n:length(A),L:copymatrix(A),p:makelis\
t(0,i,1,length(A))],for i thru n do (for j from i thru n do (x:L\
[i,j],x:x-sum(L[j,k]*L[i,k],k,1,i-1),if i = j then p[i]:1/sqrt(x\
) else L[j,i]:x*p[i])),for i thru n do L[i,i]:1/p[i],for i thru \
n do (for j from i+1 thru n do L[i,j]:0),L)
@end example

@end deffn

@defvr {Option variable} ibase
Default value: 10

Integers entered into Maxima are interpreted
with respect to the base @code{ibase}.

@code{ibase} may be assigned any integer between 2 and 35 (decimal), inclusive.
@c WHY NOT 36, BY THE WAY ??
When @code{ibase} is greater than 10, the numerals comprise the decimal numerals 0 through 9
@c UPPERCASE/LOWERCASE DISTINCTION HERE ??
plus capital letters of the alphabet A, B, C, ..., as needed.
The numerals for base 35, the largest acceptable base,
comprise 0 through 9 and A through Y.
@c HOW, EXACTLY, DOES ONE TYPE IN THE LETTERS ??
@c ibase: 11$ 1A; YIELDS AN ERROR
@c \1A; #1A; \#1A; DON'T WORK EITHER

See also @code{obase}.

@c NEED EXAMPLES HERE
@end defvr

@defvr {Option variable} inchar
Default value: @code{%i}

@code{inchar} is the prefix of the labels of expressions entered by the user.
Maxima automatically constructs a label for each input expression
by concatenating @code{inchar} and @code{linenum}.
@code{inchar} may be assigned any string or symbol, not necessarily a single character.

@example
(%i1) inchar: "input";
(%o1)                                input
(input1) expand ((a+b)^3);
                            3        2      2      3
(%o1)                      b  + 3 a b  + 3 a  b + a
(input2)
@end example

See also @code{labels}.

@end defvr

@deffn {Function} ldisp (@var{expr_1}, ..., @var{expr_n})
Displays expressions @var{expr_1}, ..., @var{expr_n} to the console
as printed output.
@code{ldisp} assigns an intermediate expression label to each argument
and returns the list of labels.

See also @code{disp}.

@example
(%i1) e: (a+b)^3;
                                   3
(%o1)                       (b + a)
(%i2) f: expand (e);
                     3        2      2      3
(%o2)               b  + 3 a b  + 3 a  b + a
(%i3) ldisp (e, f);
                                   3
(%t3)                       (b + a)

                     3        2      2      3
(%t4)               b  + 3 a b  + 3 a  b + a

(%o4)                      [%t3, %t4]
(%i4) %t3;
                                   3
(%o4)                       (b + a)
(%i5) %t4;
                     3        2      2      3
(%o5)               b  + 3 a b  + 3 a  b + a
@end example

@end deffn

@deffn {Function} ldisplay (@var{expr_1}, ..., @var{expr_n})
Displays expressions @var{expr_1}, ..., @var{expr_n} to the console
as printed output.
Each expression is printed as an equation of the form @code{lhs = rhs}
in which @code{lhs} is one of the arguments of @code{ldisplay}
and @code{rhs} is its value.
Typically each argument is a variable.
@code{ldisp} assigns an intermediate expression label to each equation
and returns the list of labels.

See also @code{display}.

@example
(%i1) e: (a+b)^3;
                                   3
(%o1)                       (b + a)
(%i2) f: expand (e);
                     3        2      2      3
(%o2)               b  + 3 a b  + 3 a  b + a
(%i3) ldisplay (e, f);
                                     3
(%t3)                     e = (b + a)

                       3        2      2      3
(%t4)             f = b  + 3 a b  + 3 a  b + a

(%o4)                      [%t3, %t4]
(%i4) %t3;
                                     3
(%o4)                     e = (b + a)
(%i5) %t4;
                       3        2      2      3
(%o5)             f = b  + 3 a b  + 3 a  b + a
@end example

@end deffn

@defvr {Option variable} linechar
Default value: @code{%t}

@code{linechar} is the prefix of the labels of intermediate expressions generated by Maxima.
Maxima constructs a label for each intermediate expression (if displayed)
by concatenating @code{linechar} and @code{linenum}.
@code{linechar} may be assigned any string or symbol, not necessarily a single character.

Intermediate expressions might or might not be displayed.
See @code{programmode} and @code{labels}.

@end defvr

@defvr {Option variable} linel
Default value: 79

@code{linel} is the assumed width (in characters) of the console display
for the purpose of displaying expressions.
@code{linel} may be assigned any value by the user,
although very small or very large values may be impractical.
Text printed by built-in Maxima functions, such as error messages and the output of @code{describe},
is not affected by @code{linel}.

@end defvr

@defvr {Option variable} lispdisp
Default value: @code{false}

When @code{lispdisp} is @code{true},
Lisp symbols are displayed with a leading question mark @code{?}.
Otherwise,
Lisp symbols are displayed with no leading mark.

Examples:

@c ===beg===
@c lispdisp: false$
@c ?foo + ?bar;
@c lispdisp: true$
@c ?foo + ?bar;
@c ===end===
@example
(%i1) lispdisp: false$
(%i2) ?foo + ?bar;
(%o2)                       foo + bar
(%i3) lispdisp: true$
(%i4) ?foo + ?bar;
(%o4)                      ?foo + ?bar
@end example

@end defvr

@deffn {Function} load (@var{filename})
Evaluates expressions in @var{filename}, 
thus bringing variables, functions, and other objects into Maxima.
The binding of any existing object is clobbered by the binding recovered from @var{filename}. 
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 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}.
@code{load} calls @code{loadfile} to load Lisp files and @code{batchload} to load Maxima files.

@code{load} does not recognize @code{:lisp} constructs in Maxima files,
and while processing @var{filename},
the global variables @code{_}, @code{__}, @code{%}, and @code{%th} have whatever bindings
they had when @code{load} was called.

See also @code{loadfile}, @code{batch}, @code{batchload}, and @code{demo}.
@code{loadfile} processes Lisp 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 deffn

@c RECOMMEND CUTTING THIS ITEM, AS THE load SUBSUMES FUNCTIONALITY OF loadfile
@deffn {Function} loadfile (@var{filename})
Evaluates Lisp expressions in @var{filename}.
@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 quote-quote operator @code{'@w{}'} defeats quotation.

@end deffn

@c loadprint DOESN'T EXACTLY WORK LIKE THIS, BUT IT HARDLY SEEMS WORTH FIXING
@c I GUESS THIS COULD BE UPDATED TO DESCRIBE THE WAY IT ACTUALLY WORKS
@defvr {Option variable} loadprint
Default value: @code{true}

@code{loadprint} tells whether to print a message when a file is loaded.

@itemize @bullet
@item
When @code{loadprint} is @code{true}, always print a message.
@item
When @code{loadprint} is @code{'loadfile}, print a message only if
a file is loaded by the function @code{loadfile}.
@item
When @code{loadprint} is @code{'autoload},
print a message only if a file is automatically loaded.
See @code{setup_autoload}.
@item
When @code{loadprint} is @code{false}, never print a message.
@end itemize

@end defvr

@defvr {Option variable} obase
Default value: 10

@code{obase} is the base for integers displayed by Maxima.

@code{obase} may be assigned any integer between 2 and 35 (decimal), inclusive.
@c WHY NOT 36, BY THE WAY ??
When @code{obase} is greater than 10, the numerals comprise the decimal numerals 0 through 9
plus capital letters of the alphabet A, B, C, ..., as needed.
The numerals for base 35, the largest acceptable base,
comprise 0 through 9, and A through Y.

See also @code{ibase}.

@c NEED EXAMPLES HERE
@end defvr

@defvr {Option variable} outchar
Default value: @code{%o}

@code{outchar} is the prefix of the labels of expressions computed by Maxima.
Maxima automatically constructs a label for each computed expression
by concatenating @code{outchar} and @code{linenum}.
@code{outchar} may be assigned any string or symbol, not necessarily a single character.

@example
(%i1) outchar: "output";
(output1)                           output
(%i2) expand ((a+b)^3);
                            3        2      2      3
(output2)                  b  + 3 a b  + 3 a  b + a
(%i3)
@end example

See also @code{labels}.

@end defvr

@c STILL EXISTS, NEEDS CLARIFICATION !!!
@defvr {Option variable} packagefile
Default value: @code{false}

Package designers who use @code{save}
or @code{translate} to create packages (files) for others
to use may want to set @code{packagefile: true} to prevent information
from being added to Maxima's information-lists (e.g. @code{values},
@code{functions}) except where necessary when the file is loaded in.
In this way, the contents of the package will not get in the
user's way when he adds his own data.  Note that this will not
solve the problem of possible name conflicts.  Also note that
the flag simply affects what is output to the package file.
Setting the flag to @code{true} is also useful for creating Maxima
init files.

@end defvr

@defvr {Option variable} pfeformat
Default value: @code{false}

When @code{pfeformat} is @code{true}, a ratio of integers is
displayed with the solidus (forward slash) character,
and an integer denominator @code{n}
is displayed as a leading multiplicative term @code{1/n}.

@example
(%i1) pfeformat: false$
(%i2) 2^16/7^3;
                              65536
(%o2)                         -----
                               343
(%i3) (a+b)/8;
                              b + a
(%o3)                         -----
                                8
(%i4) pfeformat: true$ 
(%i5) 2^16/7^3;
(%o5)                       65536/343
(%i6) (a+b)/8;
(%o6)                      1/8 (b + a)
@end example

@end defvr

@deffn {Function} print (@var{expr_1}, ..., @var{expr_n})
Evaluates and displays @var{expr_1}, ..., @var{expr_n}
one after another, from left to right,
starting at the left edge of the console display.

The value returned by @code{print} is the value of its last argument.
@code{print} does not generate intermediate expression labels.

See also @code{display}, @code{disp}, @code{ldisplay}, and @code{ldisp}.
Those functions display one expression per line, while @code{print} attempts
to display two or more expressions per line.

To display the contents of a file, see @code{printfile}.

@example
(%i1) r: print ("(a+b)^3 is", expand ((a+b)^3), "log (a^10/b) is", radcan (log (a^10/b)))$
            3        2      2      3
(a+b)^3 is b  + 3 a b  + 3 a  b + a  log (a^10/b) is 

                                              10 log(a) - log(b) 
(%i2) r;
(%o2)                  10 log(a) - log(b)
(%i3) disp ("(a+b)^3 is", expand ((a+b)^3), "log (a^10/b) is", radcan (log (a^10/b)))$
                           (a+b)^3 is

                     3        2      2      3
                    b  + 3 a b  + 3 a  b + a

                         log (a^10/b) is

                       10 log(a) - log(b)
@end example

@end deffn

@c RECOMMEND CUTTING THIS ITEM AND CUTTING $tcl_output IN src/plot.lisp
@c THIS REALLY, REALLY SEEMS LIKE CRUFT:
@c $tcl_output IS NEVER CALLED WITHIN MAXIMA SOURCE,
@c AND THIS EXTREMELY NARROW, LIMITED FUNCTIONALITY ISN'T USEFUL TO USERS
@c AND IT'S BROKEN: INCORRECT OUTPUT FOR CLISP, DIES ON GCL
@deffn {Function} tcl_output (@var{list}, @var{i0}, @var{skip})
@deffnx {Function} tcl_output (@var{list}, @var{i0})
@deffnx {Function} tcl_output ([@var{list_1}, ..., @var{list_n}], @var{i})

Prints elements of a list enclosed by curly braces @code{@{ @}},
suitable as part of a program in the Tcl/Tk language.

@code{tcl_output (@var{list}, @var{i0}, @var{skip})}
prints @var{list}, beginning with element @var{i0} and printing elements
@code{@var{i0} + @var{skip}}, @code{@var{i0} + 2 @var{skip}}, etc.

@code{tcl_output (@var{list}, @var{i0})}
is equivalent to @code{tcl_output (@var{list}, @var{i0}, 2)}.

@code{tcl_output ([@var{list_1}, ..., @var{list_n}], @var{i})}
prints the @var{i}'th elements of @var{list_1}, ..., @var{list_n}.

Examples:
@c EXAMPLE INPUT
@c tcl_output ([1, 2, 3, 4, 5, 6], 1, 3)$
@c tcl_output ([1, 2, 3, 4, 5, 6], 2, 3)$
@c tcl_output ([3/7, 5/9, 11/13, 13/17], 1)$
@c tcl_output ([x1, y1, x2, y2, x3, y3], 2)$
@c tcl_output ([[1, 2, 3], [11, 22, 33]], 1)$

@c EXAMPLE OUTPUT: CLISP
@c OUTPUT IS OK FOR FIRST TWO, BROKEN FOR OTHERS
@c GCL OUTPUT: SAME FOR FIRST TWO
@c GCL FAILS ON OTHERS (IN EACH CASE COMPLAINING ELEMENTS ARE "not of type (OR RATIONAL LISP:FLOAT)"
@example
(%i1) tcl_output ([1, 2, 3, 4, 5, 6], 1, 3)$

 @{1.000000000     4.000000000     
 @}
(%i2) tcl_output ([1, 2, 3, 4, 5, 6], 2, 3)$

 @{2.000000000     5.000000000     
 @}
(%i3) tcl_output ([3/7, 5/9, 11/13, 13/17], 1)$

 @{((RAT SIMP) 3 7) ((RAT SIMP) 11 13) 
 @}
(%i4) tcl_output ([x1, y1, x2, y2, x3, y3], 2)$

 @{$Y1 $Y2 $Y3 
 @}
(%i5) tcl_output ([[1, 2, 3], [11, 22, 33]], 1)$

 @{SIMP 1.000000000     11.00000000     
 @}
@end example

@end deffn

@deffn {Function} read (@var{expr_1}, ..., @var{expr_n})
Prints @var{expr_1}, ..., @var{expr_n}, then reads one expression from the console
and returns the evaluated expression.
The expression is terminated with a semicolon @code{;} or dollar sign @code{$}.

See also @code{readonly}.

@example
(%i1) foo: 42$ 
(%i2) foo: read ("foo is", foo, " -- enter new value.")$
foo is 42  -- enter new value. 
(a+b)^3;
(%i3) foo;
                                     3
(%o3)                         (b + a)
@end example

@end deffn

@deffn {Function} readonly (@var{expr_1}, ..., @var{expr_n})
Prints @var{expr_1}, ..., @var{expr_n}, then reads one expression from the console
and returns the expression (without evaluation).
The expression is terminated with a @code{;} (semicolon) or @code{$} (dollar sign).

@example
(%i1) aa: 7$
(%i2) foo: readonly ("Enter an expression:");
Enter an expression: 
2^aa;
                                  aa
(%o2)                            2
(%i3) foo: read ("Enter an expression:");
Enter an expression: 
2^aa;
(%o3)                            128
@end example

See also @code{read}.

@end deffn

@deffn {Function} reveal (@var{expr}, @var{depth})
Replaces parts of @var{expr} at the specified integer @var{depth}
with descriptive summaries.

@itemize @bullet
@item
Sums and differences are replaced by @code{sum(@var{n})}
where @var{n} is the number of operands of the sum.
@item
Products are replaced by @code{product(@var{n})}
where @var{n} is the number of operands of the product.
@item
Exponentials are replaced by @code{expt}. 
@item
Quotients are replaced by @code{quotient}.
@item
Unary negation is replaced by @code{negterm}.
@end itemize

When @var{depth} is greater than or equal to the maximum depth of @var{expr},
@code{reveal (@var{expr}, @var{depth})} returns @var{expr} unmodified.

@code{reveal} evaluates its arguments.
@code{reveal} returns the summarized expression.

Example:

@example
(%i1) e: expand ((a - b)^2)/expand ((exp(a) + exp(b))^2);
                          2            2
                         b  - 2 a b + a
(%o1)               -------------------------
                        b + a     2 b     2 a
                    2 %e      + %e    + %e
(%i2) reveal (e, 1);
(%o2)                       quotient
(%i3) reveal (e, 2);
                             sum(3)
(%o3)                        ------
                             sum(3)
(%i4) reveal (e, 3);
                     expt + negterm + expt
(%o4)               ------------------------
                    product(2) + expt + expt
(%i5) reveal (e, 4);
                       2                 2
                      b  - product(3) + a
(%o5)         ------------------------------------
                         product(2)     product(2)
              2 expt + %e           + %e
(%i6) reveal (e, 5);
                         2            2
                        b  - 2 a b + a
(%o6)              --------------------------
                       sum(2)     2 b     2 a
                   2 %e       + %e    + %e
(%i7) reveal (e, 6);
                          2            2
                         b  - 2 a b + a
(%o7)               -------------------------
                        b + a     2 b     2 a
                    2 %e      + %e    + %e
@end example

@end deffn

@defvr {Option variable} rmxchar
Default value: @code{]}

@code{rmxchar} is the character drawn on the right-hand side of a matrix.

See also @code{lmxchar}.

@end defvr

@c NEEDS EXAMPLES
@deffn {Function} save (@var{filename}, @var{name_1}, @var{name_2}, @var{name_3}, ...)
@deffnx {Function} save (@var{filename}, values, functions, labels, ...)
@deffnx {Function} save (@var{filename}, [@var{m}, @var{n}])
@deffnx {Function} save (@var{filename}, @var{name_1}=@var{expr_1}, ...)
@deffnx {Function} save (@var{filename}, all)
@c @defunx save (@var{filename}, @var{name_1}=@var{expr_1}, @var{name_2}=@var{expr_2}, ...)
@c PRECEDING @defunx IS LONGER THAN 1 LINE, CAUSES cl-info.lisp TO STUMBLE; WORK AROUND IT
Stores the current values of @var{name_1}, @var{name_2}, @var{name_3}, ..., in @var{filename}.
The arguments are the names of variables, functions, or other objects.
If a name has no value or function associated with it, it is ignored.
@code{save} returns @var{filename}.

@code{save} stores data in the form of Lisp expressions.
The data stored by @code{save} may be recovered by @code{load (@var{filename})}.

The global flag @code{file_output_append} governs
whether @code{save} appends or truncates the output file.
When @code{file_output_append} is @code{true},
@code{save} appends to the output file.
Otherwise, @code{save} truncates the output file.
In either case, @code{save} creates the file if it does not yet exist.

The special form @code{save (@var{filename}, values, functions, labels, ...)}
stores the items named by @code{values}, @code{functions}, @code{labels}, etc.
The names may be any specified by the variable @code{infolists}.
@code{values} comprises all user-defined variables.

The special form @code{save (@var{filename}, [@var{m}, @var{n}])} stores the values of
input and output labels @var{m} through @var{n}.
Note that @var{m} and @var{n} must be literal integers.
Input and output labels may also be stored one by one, e.g., @code{save ("foo.1", %i42, %o42)}.
@code{save (@var{filename}, labels)} stores all input and output labels.
When the stored labels are recovered, they clobber existing labels.

The special form @code{save (@var{filename}, @var{name_1}=@var{expr_1}, @var{name_2}=@var{expr_2}, ...)}
stores the values of @var{expr_1}, @var{expr_2}, ...,
with names @var{name_1}, @var{name_2}, ....
It is useful to apply this form to input and output labels, e.g., @code{save ("foo.1", aa=%o88)}.
The right-hand side of the equality in this form may be any expression, which is evaluated.
This form does not introduce the new names into the current Maxima environment,
but only stores them in @var{filename}.

These special forms and the general form of @code{save} may be mixed at will.
For example, @code{save (@var{filename}, aa, bb, cc=42, functions, [11, 17])}.

The special form @code{save (@var{filename}, all)} stores the current state of Maxima.
This includes all user-defined variables, functions, arrays, etc., as well
as some automatically defined items.
The saved items include system variables,
such as @code{file_search_maxima} or @code{showtime}, if they have been assigned new values by the user;
see @code{myoptions}.

@code{save} quotes its arguments. 
@var{filename} must be a string, not a string variable.
The first and last labels to save, if specified, must be integers.
The quote-quote operator @code{'@w{}'} evaluates a string variable to its string value,
e.g., @code{s: "foo.1"$ save (''s, all)$},
and integer variables to their integer values, e.g., @code{m: 5$ n: 12$ save ("foo.1", [''m, ''n])$}.

@c ANY USE FOR THE FOLLOWING ???
@c The following device constructs a list of variables to save and saves them.
@c 
@c @example
@c s: "foo.1"$
@c l: ['aa, 'bb, 'cc, 'dd]$
@c apply (save, append ([s], l))$
@c @end example
@end deffn

@c NEEDS MORE WORK !!!
@defvr {Option variable} savedef
Default value: @code{true}

When @code{savedef} is @code{true}, the Maxima version of a
user function is preserved when the function is translated.
This permits the definition to be displayed by @code{dispfun} and allows the function to
be edited.

When @code{savedef} is @code{false}, the names of translated functions are
removed from the @code{functions} list.

@end defvr

@c THIS FUNCTION IS IN THE SHARE PACKAGE itensor.lisp
@c MOVE THIS DESCRIPTION TO Itensor.texi
@deffn {Function} show (@var{expr})
Displays @code{expr} with the indexed objects in it shown
having covariant indices as subscripts, contravariant indices as
superscripts.  The derivative indices are displayed as subscripts,
separated from the covariant indices by a comma.

@end deffn

@deffn {Function} showratvars (@var{expr})
Returns a list of the canonical rational expression (CRE) variables in expression @code{expr}.

See also @code{ratvars}.

@end deffn

@defvr {Option variable} stardisp
Default value: @code{false}

When @code{stardisp} is @code{true}, multiplication is
displayed with an asterisk @code{*} between operands.

@end defvr

@c NEEDS CLARIFICATION AND EXAMPLES
@deffn {Function} string (@var{expr})
Converts @code{expr} to Maxima's linear notation
just as if it had been typed in.

The return value of @code{string} is a string,
and thus it cannot be used in a computation.

@end deffn

@c SHOULD BE WRITTEN WITH LEADING ? BUT THAT CONFUSES CL-INFO SO WORK AROUND
@c @defvr {Lisp variable} ?stringdisp
@defvr {Lisp variable} stringdisp
Default value: @code{false}

When @code{?stringdisp} is @code{true},
strings are displayed enclosed in double quote marks.
Otherwise,
quote marks are not displayed.

@code{?stringdisp} is always @code{true} when displaying a function definition.

@code{?stringdisp} is a Lisp variable,
so it must be written with a leading question mark @code{?}.

Examples:

@c ===beg===
@c ?stringdisp: false$
@c "This is an example string.";
@c foo () := print ("This is a string in a function definition.");
@c ?stringdisp: true$
@c "This is an example string.";
@c ===end===
@example
(%i1) ?stringdisp: false$
(%i2) "This is an example string.";
(%o2)              This is an example string.
(%i3) foo () := print ("This is a string in a function definition.");
(%o3) foo() := 
              print("This is a string in a function definition.")
(%i4) ?stringdisp: true$
(%i5) "This is an example string.";
(%o5)             "This is an example string."
@end example

@end defvr

@deffn {Function} stringout (@var{filename}, @var{expr_1}, @var{expr_2}, @var{expr_3}, ...)
@deffnx {Function} stringout (@var{filename}, [@var{m}, @var{n}])
@deffnx {Function} stringout (@var{filename}, input)
@deffnx {Function} stringout (@var{filename}, functions)
@deffnx {Function} stringout (@var{filename}, values)

@code{stringout} writes expressions to a file in the same form the
expressions would be typed for input. The file can then be used
as input for the @code{batch} or @code{demo} commands, and it may be edited for
any purpose. @code{stringout} can be executed while @code{writefile} is in progress.

The global flag @code{file_output_append} governs
whether @code{stringout} appends or truncates the output file.
When @code{file_output_append} is @code{true},
@code{stringout} appends to the output file.
Otherwise, @code{stringout} truncates the output file.
In either case, @code{stringout} creates the file if it does not yet exist.

The general form of @code{stringout} writes the values of one or more 
expressions to the output file. Note that if an expression is a
variable, only the value of the variable is written and not the name
of the variable. As a useful special case, the expressions may be
input labels (@code{%i1}, @code{%i2}, @code{%i3}, ...) or output labels (@code{%o1}, @code{%o2}, @code{%o3}, ...).

If @code{grind} is @code{true}, @code{stringout} formats the output using the @code{grind}
format. Otherwise the @code{string} format is used. See @code{grind} and @code{string}.

The special form @code{stringout (@var{filename}, [@var{m}, @var{n}])} writes the
values of input labels m through n, inclusive. 

The special form @code{stringout (@var{filename}, input)} writes all
input labels to the file.

The special form @code{stringout (@var{filename}, functions)} writes all
user-defined functions (named by the global list @code{functions}) to the file.

The special form @code{stringout (@var{filename}, values)} writes all
user-assigned variables (named by the global list @code{values})
to the file. Each variable is printed as an
assignment statement, with the name of the variable, a colon, and its
value. Note that the general form of @code{stringout} does not print 
variables as assignment statements.

@end deffn

@deffn {Function} tex (@var{expr})
@deffnx {Function} tex (@var{label})
@deffnx {Function} tex (@var{expr}, @var{filename})
@deffnx {Function} tex (@var{label}, @var{filename})

Prints a representation of an expression
suitable for the TeX document preparation system.
The result is a fragment of a document,
which can be copied into a larger document
but not processed by itself.

@code{tex (@var{expr})} prints a TeX representation of @var{expr} on the console.

@code{tex (@var{label})} prints a TeX representation of the expression named by @var{label}
and assigns it an equation label (to be displayed to the left of the expression).
The TeX equation label is the same as the Maxima label.

@code{tex (@var{expr}, @var{filename})} appends a TeX representation of @var{expr}
to the file @var{filename}.
@code{tex} quotes the @var{filename} argument; quote-quote @code{''} forces evaluation of the argument.

@code{tex (@var{label}, @var{filename})} appends a TeX representation of the
expression named by @var{label}, with an equation label, to the file @var{filename}.
@code{tex} quotes the @var{filename} argument; quote-quote @code{''} forces evaluation of the argument.

@code{tex} evaluates its argument after testing it to see if it is a label.
Quote-quote @code{''} forces evaluation of the argument, thereby defeating the test
and preventing the label.

See also @code{texput}.

Examples:

@example
(%i1) integrate (1/(1+x^3), x);
                                    2 x - 1
                  2            atan(-------)
             log(x  - x + 1)        sqrt(3)    log(x + 1)
(%o1)      - --------------- + ------------- + ----------
                    6             sqrt(3)          3
(%i2) tex (%o1);
$$-@{@{\log \left(x^2-x+1\right)@}\over@{6@}@}+@{@{\arctan \left(@{@{2\,x-1
 @}\over@{\sqrt@{3@}@}@}\right)@}\over@{\sqrt@{3@}@}@}+@{@{\log \left(x+1\right)
 @}\over@{3@}@}\leqno@{\tt (\%o1)@}$$
(%o2)                          (\%o1)
(%i3) tex (integrate (sin(x), x));
$$-\cos x$$
(%o3)                           false
(%i4) tex (%o1, "foo.tex");
(%o4)                          (\%o1)
@end example

@end deffn

@deffn {Function} texput (@var{a}, @var{s})
@deffnx {Function} texput (@var{a}, @var{s}, @var{operator_type})
@deffnx {Function} texput (@var{a}, [@var{s_1}, @var{s_2}], matchfix)
@deffnx {Function} texput (@var{a}, [@var{s_1}, @var{s_2}, @var{s_3}], matchfix)

Set the TeX output for the atom @var{a},
which can be a symbol or the name of an operator.

@code{texput (@var{a}, @var{s})} causes the @code{tex} function
to interpolate the string @var{s} into the TeX output in place of @var{a}.

@code{texput (@var{a}, @var{s}, @var{operator_type})},
where @var{operator_type} is @code{prefix}, @code{infix}, or @code{postfix}
causes the @code{tex} function to interpolate @var{s} into the TeX output in place of @var{a},
and to place the interpolated text in the appropriate position.

@code{texput (@var{a}, [@var{s_1}, @var{s_2}], matchfix)}
causes the @code{tex} function to interpolate @var{s_1} and @var{s_2} into the TeX output
on either side of the arguments of @var{a}.
The arguments (if more than one) are separated by commas.

@code{texput (@var{a}, [@var{s_1}, @var{s_2}, @var{s_3}], matchfix)}
causes the @code{tex} function to interpolate @var{s_1} and @var{s_2} into the TeX output
on either side of the arguments of @var{a},
with @var{s_3} separating the arguments.

Examples:

@c ===beg===
@c texput (me,"\\mu_e");
@c tex (me);
@c texput (lcm, "\\mathrm{lcm}");
@c tex (lcm (a, b));
@c prefix ("grad");
@c texput ("grad", " \\nabla ", prefix);
@c tex (grad f);
@c infix ("~");
@c texput ("~", " \\times ", infix);
@c tex (a ~ b);
@c postfix ("@");
@c texput ("@", "!!", postfix);
@c tex (x @);
@c matchfix ("<<", ">>");
@c texput ("<<", [" \\langle ", " \\rangle "], matchfix);
@c tex (<<a>>);
@c tex (<<a, b>>);
@c texput ("<<", [" \\langle ", " \\rangle ", " \\, | \\,"], matchfix);
@c tex (<<a>>);
@c tex (<<a, b>>);
@c ===end===
@example
(%i1) texput (me,"\\mu_e");
(%o1)                         \mu_e
(%i2) tex (me);
$$\mu_e$$
(%o2)                         false
(%i3) texput (lcm, "\\mathrm@{lcm@}");
(%o3)                     \mathrm@{lcm@}
(%i4) tex (lcm (a, b));
$$\mathrm@{lcm@}\left(a , b\right)$$
(%o4)                         false
(%i5) prefix ("grad");
(%o5)                         grad
(%i6) texput ("grad", " \\nabla ", prefix);
(%o6)                          180
(%i7) tex (grad f);
$$ \nabla f$$
(%o7)                         false
(%i8) infix ("~");
(%o8)                           ~
(%i9) texput ("~", " \\times ", infix);
(%o9)                          180
(%i10) tex (a ~ b);
$$a \times b$$
(%o10)                        false
(%i11) postfix ("@@");
(%o11)                          @@
(%i12) texput ("@@", "!!", postfix);
(%o12)                         160
(%i13) tex (x @@);
$$x!!$$
(%o13)                        false
(%i14) matchfix ("<<", ">>");
(%o14)                         <<
(%i15) texput ("<<", [" \\langle ", " \\rangle "], matchfix);
(%o15)              \langle ( \rangle , false)
(%i16) tex (<<a>>);
$$ \langle a \rangle $$
(%o16)                        false
(%i17) tex (<<a, b>>);
$$ \langle a , b \rangle $$
(%o17)                        false
(%i18) texput ("<<", [" \\langle ", " \\rangle ", " \\, | \\,"], matchfix);
(%o18)            \langle ( \rangle ,  \, | \,)
(%i19) tex (<<a>>);
$$ \langle a \rangle $$
(%o19)                        false
(%i20) tex (<<a, b>>);
$$ \langle a \, | \,b \rangle $$
(%o20)                        false
@end example

@end deffn

@c NEEDS CLARIFICATION
@deffn {Function} system (@var{command})
Executes @var{command} as a separate process.
The command is passed to the default shell for execution.
@code{system} is not supported by all operating
systems, but generally exists in Unix and Unix-like environments.

Supposing @code{_hist.out}
is a list of frequencies which you wish to plot as a bar graph
using @code{xgraph}. 

@example
(%i1) (with_stdout("_hist.out",
           for i:1 thru length(hist) do (
             print(i,hist[i]))),
       system("xgraph -bar -brw .7 -nl < _hist.out"));
@end example

In order to make the plot be done in the background (returning control to Maxima)
and remove the temporary file after it is done do:

@example
system("(xgraph -bar -brw .7 -nl < _hist.out;  rm -f _hist.out)&")
@end example

@end deffn

@defvr {Option variable} ttyoff
Default value: @code{false}

When @code{ttyoff} is @code{true}, output expressions are not displayed.
Output expressions are still computed and assigned labels. See @code{labels}.

Text printed by built-in Maxima functions, such as error messages and the output of @code{describe},
is not affected by @code{ttyoff}.

@end defvr

@deffn {Function} with_stdout (@var{filename}, @var{expr_1}, @var{expr_2}, @var{expr_3}, ...)
Opens @var{filename} and then evaluates @var{expr_1}, @var{expr_2}, @var{expr_3}, ....
The values of the arguments are not stored in @var{filename},
but any printed output generated by evaluating the arguments
(from @code{print}, @code{display}, @code{disp}, or @code{grind}, for example)
goes to @var{filename} instead of the console.

The global flag @code{file_output_append} governs
whether @code{with_stdout} appends or truncates the output file.
When @code{file_output_append} is @code{true},
@code{with_stdout} appends to the output file.
Otherwise, @code{with_stdout} truncates the output file.
In either case, @code{with_stdout} creates the file if it does not yet exist.

@code{with_stdout} returns the value of its final argument.

See also @code{writefile}.

@c THIS DOESN'T SEEM VERY IMPORTANT TO MENTION ...
@c Note the binding of display2d to be
@c false, otherwise the printing will have things like "- 3" instead
@c of "-3".
@c
@example
@c THIS EXAMPLE USES SOME UNIX-ISH CONSTRUCTS -- WILL IT WORK IN WINDOWS ???
@c ALSO IT'S SORT OF COMPLICATED AND THE SIMPLER SECOND EXAMPLE ILLUSTRATES with_stdout BETTER !!!
@c mygnuplot (f, var, range, number_ticks) :=
@c  block ([numer:true, display2d:false],
@c  with_stdout("tmp.out",
@c    dx: (range[2]-range[1])/number_ticks,
@c    for x: range[1] thru range[2] step dx
@c       do print (x, at (f, var=x))),
@c  system ("echo \"set data style lines; set title '", f,"' ;plot '/tmp/gnu'
@c ;pause 10 \" | gnuplot"))$
(%i1) with_stdout ("tmp.out", for i:5 thru 10 do print (i, "! yields", i!))$
(%i2) printfile ("tmp.out")$
5 ! yields 120 
6 ! yields 720 
7 ! yields 5040 
8 ! yields 40320 
9 ! yields 362880 
10 ! yields 3628800
@end example

@end deffn

@deffn {Function} writefile (@var{filename})
Begins writing a transcript of the Maxima session to @var{filename}.
All interaction between the user and Maxima is then recorded in this file,
@c FOLLOWING CLAIM PROBABLY NEEDS TO BE QUALIFIED
just as it appears on the console.

As the transcript is printed in the console output format,
it cannot be reloaded into Maxima.
To make a file containing expressions which can be reloaded,
see @code{save} and @code{stringout}.
@code{save} stores expressions in Lisp form, while @code{stringout} stores expressions in Maxima form.

The effect of executing @code{writefile} when @var{filename} already exists
depends on the underlying Lisp implementation;
the transcript file may be clobbered, or the file may be appended.
@code{appendfile} always appends to the transcript file.

It may be convenient to execute @code{playback} after
@code{writefile} to save the display of previous interactions.
As @code{playback} displays only the input and output variables (@code{%i1}, @code{%o1}, etc.),
any output generated by a print statement in a function 
(as opposed to a return value) is not displayed by @code{playback}.

@code{closefile} closes the transcript file opened by @code{writefile} or @code{appendfile}.

@end deffn