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

@c -----------------------------------------------------------------------------
@node Documentation, Functions and Variables for 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). Command
@mref{?} can also display its result in a Web browser, if the variable
@mref{output_format_for_help} is set to "html"; furthermore, the HTML
page shown can be the official documentation in Maxima's website, as
explained in @mrefdot{url_base} The user's manual can be viewed as
@code{info} hypertext with the @code{info} viewer program, or as Web
pages 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, Help
@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 Web browser see @mrefdot{output_format_for_help}
Also see @mref{browser} and @mref{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 Web browser to display the HTML version of the
manual.
@item frontend
When Maxima is being run from a graphical interface (for example,
wxMaxima or xmaxima), lets that program decide how to display the help
results. If no frontend is running then an error is signaled.
@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{"browser_command"} that corresponds to a
valid command that when given a URL as argument, as in
@code{'browser_command URL'}, it will open up a browser to the given URL.

The default setting is @code{"start"} on Windows, @code{"xdg-open"} on
Linux/Unix, and @code{"open"} on MacOS, all of which will open the default Web
browser. In other systems, the default value of @code{browser} is set as
@code{"firefox"}, which will open the Firefox browser if it is
installed (if it is not installed, the user should change the value of
@code{browser} to some other valid browser).

You may replace the default value of @code{browser} with other valid browser
in your system, e.g. @code{"chrome"} or @code{"iexplore"}.

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; something such as,
@code{file:///home/user/.local/share/maxima/5.48.1/doc/html"}. However,
you could change the value of @code{url_base} to any valid URL that has
the HTML help files of the manual. For instance to see the official
manual in Maxima's website instead of the local copy in your disk, set
@code{url_base} to @code{"https://maxima.sourceforge.io/docs/manual"}.

But keep in mind that the URL to where @code{url_base} points must have
exactly the same HTML files as in the Maxima version that you are using,
otherwise the help topics you are searching might not be found.

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

