@menu
* Introduction to Miscellaneous Options::  
* Share::                       
* Functions and Variables for Miscellaneous Options::  
@end menu

@c -----------------------------------------------------------------------------
@node Introduction to Miscellaneous Options, Share, Miscellaneous Options, Miscellaneous Options
@section Introduction to Miscellaneous Options
@c -----------------------------------------------------------------------------

In this section various options are discussed which have a global effect
on the operation of Maxima.  Also various lists such as the list of all
user defined functions, are discussed.

@c -----------------------------------------------------------------------------
@node Share, Functions and Variables for Miscellaneous Options, Introduction to Miscellaneous Options, Miscellaneous Options
@section Share
@c -----------------------------------------------------------------------------

The Maxima "share" directory contains programs and other files 
of interest to Maxima users, but not part of the core implementation of Maxima.
These programs are typically loaded via @code{load} or @code{setup_autoload}.

@code{:lisp *maxima-sharedir*} displays the location of the share directory
within the user's file system.

@c FIXME FIXME FIXME -- WE REALLY NEED AN UP-TO-DATE LIST OF SHARE PACKAGES !!
@code{printfile ("share.usg")} prints an out-of-date list of share packages.
Users may find it more informative to browse the share directory using a file
system browser.

@c -----------------------------------------------------------------------------
@node Functions and Variables for Miscellaneous Options,  , Share, Miscellaneous Options
@section Functions and Variables for Miscellaneous Options
@c -----------------------------------------------------------------------------

@c After studying src/compar.lisp, it appears that askexp would
@c work as advertised, except that it doesn't appear to be possible
@c to open a break prompt with ^A or any other character.
@c What should we do about askexp ???

@c -----------------------------------------------------------------------------
@anchor{askexp}
@defvr {System variable} askexp

When @code{asksign} is called,
@code{askexp} is the expression @code{asksign} is testing.

At one time, it was possible for a user to inspect @code{askexp}
by entering a Maxima break with control-A.

@opencatbox
@category{Declarations and inferences}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{genindex}
@defvr {Option variable} genindex
Default value: @code{i}

@code{genindex} is the alphabetic prefix used to generate the
next variable of summation when necessary.

@opencatbox
@category{Sums and products}
@closecatbox
@end defvr

@anchor{gensumnum}
@defvr {Option variable} gensumnum
Default value: 0

@code{gensumnum} is the numeric suffix used to generate the next variable
of summation.  If it is set to @code{false} then the index will consist only
of @code{genindex} with no numeric suffix.

@opencatbox
@category{Sums and products}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{gensym}
@deffn  {Function} gensym ()
@deffnx {Function} gensym (@var{x})

@code{gensym()} creates and returns a fresh symbol.

The name of the new-symbol is the concatenation of a prefix, which defaults to 
"g", and a suffix, which is the decimal representation of a number that defaults
to the value of a Lisp internal counter.

If @var{x} is supplied, and is a string, then that string is used as a prefix 
instead of "g" for this call to gensym only.

If @var{x} is supplied, and is an integer, then that integer, instead of the 
value of the internal Lisp integer, is used as the suffix for this call to 
gensym only.

If and only if no explicit suffix is supplied, the Lisp internal integer is 
incremented after it is used.

Examples:

@c ===beg===
@c gensym();
@c gensym("new");
@c gensym(123);
@c ===end===
@example
(%i1) gensym();
(%o1)                         g887
(%i2) gensym("new");
(%o2)                        new888
(%i3) gensym(123);
(%o3)                         g123
@end example
@end deffn

@c STILL EXISTS, NEEDS CLARIFICATION !!!

@c -----------------------------------------------------------------------------
@anchor{packagefile}
@defvr {Option variable} packagefile
Default value: @code{false}

Package designers who use @mref{save} or @mref{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.
@mrefcomma{values} @mref{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.

@opencatbox
@category{Translation flags and variables}
@closecatbox
@end defvr


@c NEEDS EXAMPLES

@c -----------------------------------------------------------------------------
@anchor{remvalue}
@deffn  {Function} remvalue (@var{name_1}, @dots{}, @var{name_n})
@deffnx {Function} remvalue (all)

Removes the values of user variables @var{name_1}, @dots{}, @var{name_n}
(which can be subscripted) from the system.

@code{remvalue (all)} removes the values of all variables in @code{values},
the list of all variables given names by the user
(as opposed to those which are automatically assigned by Maxima).

See also @code{values}.

@opencatbox
@category{Evaluation}
@closecatbox
@end deffn

@c NEEDS EXAMPLES

@c -----------------------------------------------------------------------------
@anchor{rncombine}
@deffn {Function} rncombine (@var{expr})

Transforms @var{expr} by combining all terms of @var{expr} that have
identical denominators or denominators that differ from each other by
numerical factors only.  This is slightly different from the behavior
of @code{combine}, which collects terms that have identical denominators.

Setting @code{pfeformat: true} and using @code{combine} yields results similar
to those that can be obtained with @code{rncombine}, but @code{rncombine} takes
the additional step of cross-multiplying numerical denominator factors.
This results in neater forms, and the possibility of recognizing some
cancellations.

@code{load(rncomb)} loads this function.

@opencatbox
@category{Expressions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{setup_autoload}
@deffn {Function} setup_autoload (@var{filename}, @var{function_1}, @dots{}, @var{function_n})

Specifies that if any of @var{function_1}, @dots{}, @var{function_n} are
referenced and not yet defined, @var{filename} is loaded via @code{load}.
@var{filename} usually contains definitions for the functions specified,
although that is not enforced.

@code{setup_autoload} does not work for array functions.

@code{setup_autoload} quotes its arguments.

Example:

@c EXAMPLE GENERATED FROM FOLLOWING INPUT
@c legendre_p (1, %pi);
@c setup_autoload ("specfun.mac", legendre_p, ultraspherical);
@c ultraspherical (2, 1/2, %pi);
@c legendre_p (1, %pi);
@c legendre_q (1, %pi);
@example
(%i1) legendre_p (1, %pi);
(%o1)                  legendre_p(1, %pi)
(%i2) setup_autoload ("specfun.mac", legendre_p, ultraspherical);
(%o2)                         done
(%i3) ultraspherical (2, 1/2, %pi);
Warning - you are redefining the Macsyma function ultraspherical
Warning - you are redefining the Macsyma function legendre_p
                            2
                 3 (%pi - 1)
(%o3)            ------------ + 3 (%pi - 1) + 1
                      2
(%i4) legendre_p (1, %pi);
(%o4)                          %pi
(%i5) legendre_q (1, %pi);
                              %pi + 1
                      %pi log(-------)
                              1 - %pi
(%o5)                 ---------------- - 1
                             2
@end example

@opencatbox
@category{Function definition} @category{File input}
@closecatbox
@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

@c -----------------------------------------------------------------------------
@anchor{tcl_output}
@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}, @dots{}, @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}, @dots{}, @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

