doc/info/Help.texi

@menu
* Documentation::
* Functions and Variables for Help::
@end menu

@c -----------------------------------------------------------------------------
@node Documentation, Functions and Variables for Help, Help, Help
@section Documentation
@c -----------------------------------------------------------------------------

@c SHOULD TALK ABOUT OTHER FORMS OF DOCUMENTATION ASIDE FROM ON-LINE MANUAL.

The Maxima on-line user's manual can be viewed in different forms.  From the
Maxima interactive prompt, the user's manual is viewed as plain text by the
@mref{?} command (i.e., the @mref{describe} function).  The user's manual is
viewed as @code{info} hypertext by the @code{info} viewer program and as a
web page by any ordinary web browser.

@mref{example} displays examples for many Maxima functions.  For example,

@example
(%i1) example (integrate);
@end example

yields

@example
(%i2) test(f):=block([u],u:integrate(f,x),ratsimp(f-diff(u,x)))
(%o2) test(f) := block([u], u : integrate(f, x),
                                         ratsimp(f - diff(u, x)))
(%i3) test(sin(x))
(%o3)                           0
(%i4) test(1/(x+1))
(%o4)                           0
(%i5) test(1/(x^2+1))
(%o5)                           0
@end example

and additional output.

@opencatbox
@category{Console interaction}
@closecatbox

@c -----------------------------------------------------------------------------
@node Functions and Variables for Help,  , Documentation, Help
@section Functions and Variables for Help
@c -----------------------------------------------------------------------------

@c -----------------------------------------------------------------------------
@anchor{apropos}
@deffn {Function} apropos (@var{string})

Searches for Maxima names which have @var{string} appearing anywhere within
them.  Thus, @code{apropos (exp)} returns a list of all the flags and functions
which have @code{exp} as part of their names, such as @code{expand}, @code{exp},
and @code{exponentialize}.  Thus if you can only remember part of the name of
something you can use this command to find the rest of the name.  Similarly, you
could say @code{apropos (tr_)} to find a list of many of the switches relating
to the translator, most of which begin with @code{tr_}.

@code{apropos("")} returns a list with all Maxima names.

@code{apropos} returns the empty list @code{[]}, if no name is found.

Example:

Show all Maxima symbols which have @code{"gamma"} in the name:

@c ===beg===
@c apropos("gamma");
@c ===end===
@example
@group
(%i1) apropos("gamma");
(%o1) [%gamma, gamma, gammalim, gamma_expand, gamma_incomplete_lower,
gamma_incomplete, gamma_incomplete_generalized,
gamma_incomplete_regularized, Gamma, log_gamma, makegamma,
prefer_gamma_incomplete, gamma-incomplete,
gamma_incomplete_generalized_regularized]
@end group
@end example

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

@c -----------------------------------------------------------------------------
@anchor{demo}
@deffn {Function} demo (@var{filename})

Evaluates Maxima expressions in @var{filename} and displays the results.
@code{demo} pauses after evaluating each expression and continues after the
user enters a carriage return.  (If running in Xmaxima, @code{demo} may need
to see a semicolon @code{;} followed by a carriage return.)

@code{demo} searches the list of directories @mref{file_search_demo} to find
@code{filename}.  If the file has the suffix @code{dem}, the suffix may be
omitted.  See also @mrefdot{file_search}

@code{demo} evaluates its argument.
@code{demo} returns the name of the demonstration file.

Example:

@example
(%i1) demo ("disol");

batching /home/wfs/maxima/share/simplification/disol.dem
 At the _ prompt, type ';' followed by enter to get next demo
(%i2)                      load("disol")

_
(%i3)           exp1 : a (e (g + f) + b (d + c))
(%o3)               a (e (g + f) + b (d + c))

_
(%i4)                disolate(exp1, a, b, e)
(%t4)                         d + c

(%t5)                         g + f

(%o5)                   a (%t5 e + %t4 b)

_
@end example

@opencatbox
@category{Help}
@category{Console interaction}
@category{File input}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{describe}
@fnindex Help
@deffn  {Function} describe @
@fname{describe} (@var{string}) @
@fname{describe} (@var{string}, exact) @
@fname{describe} (@var{string}, inexact)

@code{describe(@var{string})} is equivalent to
@code{describe(@var{string}, exact)}.

@code{describe(@var{string}, exact)} finds an item with title equal
(case-insensitive) to @var{string}, if there is any such item.

@code{describe(@var{string}, inexact)} finds all documented items which contain
@var{string} in their titles.  If there is more than one such item, Maxima asks
the user to select an item or items to display.

At the interactive prompt, @code{? foo} (with a space between @code{?} and
@code{foo}) is equivalent to @code{describe("foo", exact)}, and @code{?? foo}
is equivalent to @code{describe("foo", inexact)}.

@code{describe("", inexact)} yields a list of all topics documented in the
on-line manual.

@code{describe} quotes its argument.  @code{describe} returns @code{true} if
some documentation is found, otherwise @code{false}.

See also @ref{Documentation}.

Example:

@example
(%i1) ?? integ
 0: Functions and Variables for Elliptic Integrals
 1: Functions and Variables for Integration
 2: Introduction to Elliptic Functions and Integrals
 3: Introduction to Integration
 4: askinteger  (Functions and Variables for Simplification)
 5: integerp  (Functions and Variables for Miscellaneous Options)
 6: integer_partitions  (Functions and Variables for Sets)
 7: integrate  (Functions and Variables for Integration)
 8: integrate_use_rootsof  (Functions and Variables for
    Integration)
 9: integration_constant_counter  (Functions and Variables for
    Integration)
 10: nonnegintegerp  (Functions and Variables for linearalgebra)
Enter space-separated numbers, `all' or `none': 7 8

 -- Function: integrate (<expr>, <x>)
 -- Function: integrate (<expr>, <x>, <a>, <b>)
     Attempts to symbolically compute the integral of <expr> with
     respect to <x>.  `integrate (<expr>, <x>)' is an indefinite
     integral, while `integrate (<expr>, <x>, <a>, <b>)' is a
     definite integral, [...]

 -- Option variable: integrate_use_rootsof
     Default value: `false'

     When `integrate_use_rootsof' is `true' and the denominator of
     a rational function cannot be factored, `integrate' returns
     the integral in a form which is a sum over the roots (not yet
     known) of the denominator.
     [...]
@end example

In this example, items 7 and 8 were selected (output is shortened as indicated
by @code{[...]}).  All or none of the items could have been selected by entering
@code{all} or @code{none}, which can be abbreviated @code{a} or @code{n},
respectively.

@opencatbox
@category{Help}
@category{Console interaction}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{example}
@deffn  {Function} example @
@fname{example} (@var{topic}) @
@fname{example} ()

@code{example (@var{topic})} displays some examples of @var{topic}, which is a
symbol or a string.  To get examples for operators like @code{if}, @code{do},
or @code{lambda} the argument must be a string, e.g. @code{example ("do")}.
@code{example} is not case sensitive.  Most topics are function names.

@code{example ()} returns the list of all recognized topics.

The name of the file containing the examples is given by the global option
variable @mrefcomma{manual_demo} which defaults to @code{"manual.demo"}.

@code{example} quotes its argument.  @code{example} returns @code{done} unless
no examples are found or there is no argument, in which case @code{example}
returns the list of all recognized topics.

Examples:

@c ===beg===
@c example(append);
@c example("lambda");
@c ===end===
@example
@group
(%i1) example(append);
(%i2) append([y+x,0,-3.2],[2.5e+20,x])
(%o2)             [y + x, 0, - 3.2, 2.5e+20, x]
(%o2)                         done
@end group
(%i3) example("lambda");
(%i4) lambda([x,y,z],x^2+y^2+z^2)
                                    2    2    2
(%o4)            lambda([x, y, z], x  + y  + z )
(%i5) %(1,2,a)
                              2
(%o5)                        a  + 5
(%i6) 1+2+a
(%o6)                         a + 3
(%o6)                         done
@end example

@opencatbox
@category{Help}
@category{Console interaction}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{manual_demo}
@defvr {Option variable} manual_demo
Default value: @code{"manual.demo"}

@code{manual_demo} specifies the name of the file containing the examples for
the function @code{example}.  See @mrefdot{example}

@opencatbox
@category{Help}
@category{Global variables}
@closecatbox
@end defvr