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

@c -----------------------------------------------------------------------------
@node Documentation, Functions and Variables for 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{Categories:}
@category{Console interaction}
@closecatbox

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

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

Searches for Maxima names which have @var{name} appearing anywhere
within them; @var{name} must be a string or symbol. 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}. So, if you can only remember part of the name
of a Maxima command or variable, you can use this command to find the
rest of the name. Similarly, you can type @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 apropos(gamma);
@c length(apropos(""));
@c ===end===
@example
@group
(%i1) apropos("gamma");
(%o1) [%gamma, Gamma, gamma_expand, gammalim, makegamma, 
prefer_gamma_incomplete, gamma, gamma-incomplete, gamma_incomplete, 
gamma_incomplete_generalized, gamma_incomplete_generalized_regularized, 
gamma_incomplete_lower, gamma_incomplete_regularized, log_gamma]
@end group

The same example, using the symbol @code{gamma}, rather than the string:
@group
(%i2) apropos(gamma);
(%o2) [%gamma, Gamma, gamma_expand, gammalim, makegamma, 
prefer_gamma_incomplete, gamma, gamma-incomplete, gamma_incomplete, 
gamma_incomplete_generalized, gamma_incomplete_generalized_regularized, 
gamma_incomplete_lower, gamma_incomplete_regularized, log_gamma]
@end group

The number of symbols in the current Maxima session. This will vary.
@group
(%i3) length(apropos(""));
(%o3)                                2338
@end group
@end example

@opencatbox{Categories:}
@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{Categories:}
@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}.

To display the topics using a browser see @ref{output_format_for_help}.
Also see @ref{browser} and @ref{url_base} to configure how to display
the HTML files.

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{Categories:}
@category{Help}
@category{Console interaction}
@closecatbox
@end deffn

@anchor{output_format_for_help}
@defvr {Option variable} output_format_for_help
Default value: @code{text}

@code{output_format_for_help} controls how @code{describe} displays
help.

@code{output_format_for_help} can be set to one of the following
values:
@table @code
@item text
Help is displayed as plain text sent to a terminal.  This is the default.
@item html
Help is displayed using a browser to display the HTML version of the
manual.
@item frontend
Help is displayed using the frontend's help system.  If no frontend is
running then an error is signaled.  For example, wxMaxima and xmaxima
are some frontends for maxima.
@end table

Any other value is a error.


See also @mrefcomma{browser} and @mrefdot{url_base}

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

@anchor{browser}
@defvr {Option variable} browser

This specifies the command to use to open an HTML file.  This is a
format string of the form @code{<cmd> ~A} where @code{~A} is replaced
by the URL of the HTML file and @code{<cmd>} is some program that
takes an arg and opens up a browser to the given URL.

On windows, the default setting is @code{"start ~A"},
which uses the default browser to display the html file.  You may replace
it with e.g. @code{start firefox ~A}, @code{start chrome ~A} or @code{start iexplore ~A}
if you want to use Firefox, Chrome, or Internet Explorer
instead of the default browser.

On other OSes, the user's default browser should be used
automatically (using @code{xdg-open} on Linux/Unix and @code{open} on MacOS).
You can also set the @code{browser} variable to use
a non default browser, e.g.
@code{browser:"firefox '~A'";} or @code{browser:"chromium '~A'";}

See also @mrefcomma{output_format_for_help} and @mrefdot{url_base}

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

@anchor{url_base}
@defvr {Option variable} url_base

When displaying help using a browser, @code{url_base} defines the URL
to use.  It defaults to a @code{file://} path pointing to the
directory containing the html files for documentation.  However, you
could use @code{http://localhost:8080/} or some other URL that has the HTML
help files.  But this requires those URLs to have exactly the same
HTML files in the info directory because a table is needed to
translate a topic to the appropriate location in an html file.

See also @ref{output_format_for_help} and @mrefdot{browser}

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

@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{Categories:}
@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{Categories:}
@category{Help}
@category{Global variables}
@closecatbox
@end defvr