doc/info/Help.texi

   1 @menu
   2 * Documentation::
   3 * Functions and Variables for Help::
   4 @end menu
   5
   6 @c -----------------------------------------------------------------------------
   7 @node Documentation, Functions and Variables for Help, , Help
   8 @section Documentation
   9 @c -----------------------------------------------------------------------------
  10
  11 @c SHOULD TALK ABOUT OTHER FORMS OF DOCUMENTATION ASIDE FROM ON-LINE MANUAL.
  12
  13 The Maxima on-line user's manual can be viewed in different forms.  From the
  14 Maxima interactive prompt, the user's manual is viewed as plain text by the
  15 @mref{?} command (i.e., the @mref{describe} function).  The user's manual is
  16 viewed as @code{info} hypertext by the @code{info} viewer program and as a
  17 web page by any ordinary web browser.
  18
  19 @mref{example} displays examples for many Maxima functions.  For example,
  20
  21 @example
  22 (%i1) example (integrate);
  23 @end example
  24
  25 yields
  26
  27 @example
  28 (%i2) test(f):=block([u],u:integrate(f,x),ratsimp(f-diff(u,x)))
  29 (%o2) test(f) := block([u], u : integrate(f, x),
  30                                          ratsimp(f - diff(u, x)))
  31 (%i3) test(sin(x))
  32 (%o3)                           0
  33 (%i4) test(1/(x+1))
  34 (%o4)                           0
  35 (%i5) test(1/(x^2+1))
  36 (%o5)                           0
  37 @end example
  38
  39 and additional output.
  40
  41 @opencatbox{Categories:}
  42 @category{Console interaction}
  43 @closecatbox
  44
  45 @c -----------------------------------------------------------------------------
  46 @node Functions and Variables for Help,  , Documentation, Help
  47 @section Functions and Variables for Help
  48 @c -----------------------------------------------------------------------------
  49
  50 @c -----------------------------------------------------------------------------
  51 @anchor{apropos}
  52 @deffn {Function} apropos (@var{name})
  53
  54 Searches for Maxima names which have @var{name} appearing anywhere
  55 within them; @var{name} must be a string or symbol. Thus, @code{apropos
  56 (exp)} returns a list of all the flags and functions which have
  57 @code{exp} as part of their names, such as @code{expand}, @code{exp},
  58 and @code{exponentialize}. So, if you can only remember part of the name
  59 of a Maxima command or variable, you can use this command to find the
  60 rest of the name. Similarly, you can type @code{apropos (tr_)} to find
  61 a list of many of the switches relating to the translator, most of which
  62 begin with @code{tr_}.
  63
  64 @code{apropos("")} returns a list with all Maxima names.
  65
  66 @code{apropos} returns the empty list @code{[]}, if no name is found.
  67
  68 Example:
  69
  70 Show all Maxima symbols which have @code{gamma} in the name:
  71
  72 @c ===beg===
  73 @c apropos("gamma");
  74 @c apropos(gamma);
  75 @c length(apropos(""));
  76 @c ===end===
  77 @example
  78 @group
  79 (%i1) apropos("gamma");
  80 (%o1) [%gamma, Gamma, gamma_expand, gammalim, makegamma,
  81 prefer_gamma_incomplete, gamma, gamma-incomplete, gamma_incomplete,
  82 gamma_incomplete_generalized, gamma_incomplete_generalized_regularized,
  83 gamma_incomplete_lower, gamma_incomplete_regularized, log_gamma]
  84 @end group
  85
  86 The same example, using the symbol @code{gamma}, rather than the string:
  87 @group
  88 (%i2) apropos(gamma);
  89 (%o2) [%gamma, Gamma, gamma_expand, gammalim, makegamma,
  90 prefer_gamma_incomplete, gamma, gamma-incomplete, gamma_incomplete,
  91 gamma_incomplete_generalized, gamma_incomplete_generalized_regularized,
  92 gamma_incomplete_lower, gamma_incomplete_regularized, log_gamma]
  93 @end group
  94
  95 The number of symbols in the current Maxima session. This will vary.
  96 @group
  97 (%i3) length(apropos(""));
  98 (%o3)                                2338
  99 @end group
 100 @end example
 101
 102 @opencatbox{Categories:}
 103 @category{Help}
 104 @closecatbox
 105 @end deffn
 106
 107 @c -----------------------------------------------------------------------------
 108 @anchor{demo}
 109 @deffn {Function} demo (@var{filename})
 110
 111 Evaluates Maxima expressions in @var{filename} and displays the results.
 112 @code{demo} pauses after evaluating each expression and continues after the
 113 user enters a carriage return.  (If running in Xmaxima, @code{demo} may need
 114 to see a semicolon @code{;} followed by a carriage return.)
 115
 116 @code{demo} searches the list of directories @mref{file_search_demo} to find
 117 @code{filename}.  If the file has the suffix @code{dem}, the suffix may be
 118 omitted.  See also @mrefdot{file_search}
 119
 120 @code{demo} evaluates its argument.
 121 @code{demo} returns the name of the demonstration file.
 122
 123 Example:
 124
 125 @example
 126 (%i1) demo ("disol");
 127
 128 batching /home/wfs/maxima/share/simplification/disol.dem
 129  At the _ prompt, type ';' followed by enter to get next demo
 130 (%i2)                      load("disol")
 131
 132 _
 133 (%i3)           exp1 : a (e (g + f) + b (d + c))
 134 (%o3)               a (e (g + f) + b (d + c))
 135
 136 _
 137 (%i4)                disolate(exp1, a, b, e)
 138 (%t4)                         d + c
 139
 140 (%t5)                         g + f
 141
 142 (%o5)                   a (%t5 e + %t4 b)
 143
 144 _
 145 @end example
 146
 147 @opencatbox{Categories:}
 148 @category{Help}
 149 @category{Console interaction}
 150 @category{File input}
 151 @closecatbox
 152 @end deffn
 153
 154 @c -----------------------------------------------------------------------------
 155 @anchor{describe}
 156 @fnindex Help
 157 @deffn  {Function} describe @
 158 @fname{describe} (@var{string}) @
 159 @fname{describe} (@var{string}, exact) @
 160 @fname{describe} (@var{string}, inexact)
 161
 162 @code{describe(@var{string})} is equivalent to
 163 @code{describe(@var{string}, exact)}.
 164
 165 @code{describe(@var{string}, exact)} finds an item with title equal
 166 (case-insensitive) to @var{string}, if there is any such item.
 167
 168 @code{describe(@var{string}, inexact)} finds all documented items which contain
 169 @var{string} in their titles.  If there is more than one such item, Maxima asks
 170 the user to select an item or items to display.
 171
 172 At the interactive prompt, @code{? foo} (with a space between @code{?} and
 173 @code{foo}) is equivalent to @code{describe("foo", exact)}, and @code{?? foo}
 174 is equivalent to @code{describe("foo", inexact)}.
 175
 176 @code{describe("", inexact)} yields a list of all topics documented in the
 177 on-line manual.
 178
 179 @code{describe} quotes its argument.  @code{describe} returns @code{true} if
 180 some documentation is found, otherwise @code{false}.
 181
 182 To display the topics using a browser see @ref{output_format_for_help}.
 183 Also see @ref{browser} and @ref{url_base} to configure how to display
 184 the HTML files.
 185
 186 See also @ref{Documentation}.
 187
 188 Example:
 189
 190 @example
 191 (%i1) ?? integ
 192  0: Functions and Variables for Elliptic Integrals
 193  1: Functions and Variables for Integration
 194  2: Introduction to Elliptic Functions and Integrals
 195  3: Introduction to Integration
 196  4: askinteger  (Functions and Variables for Simplification)
 197  5: integerp  (Functions and Variables for Miscellaneous Options)
 198  6: integer_partitions  (Functions and Variables for Sets)
 199  7: integrate  (Functions and Variables for Integration)
 200  8: integrate_use_rootsof  (Functions and Variables for
 201     Integration)
 202  9: integration_constant_counter  (Functions and Variables for
 203     Integration)
 204  10: nonnegintegerp  (Functions and Variables for linearalgebra)
 205 Enter space-separated numbers, `all' or `none': 7 8
 206
 207  -- Function: integrate (<expr>, <x>)
 208  -- Function: integrate (<expr>, <x>, <a>, <b>)
 209      Attempts to symbolically compute the integral of <expr> with
 210      respect to <x>.  `integrate (<expr>, <x>)' is an indefinite
 211      integral, while `integrate (<expr>, <x>, <a>, <b>)' is a
 212      definite integral, [...]
 213
 214  -- Option variable: integrate_use_rootsof
 215      Default value: `false'
 216
 217      When `integrate_use_rootsof' is `true' and the denominator of
 218      a rational function cannot be factored, `integrate' returns
 219      the integral in a form which is a sum over the roots (not yet
 220      known) of the denominator.
 221      [...]
 222 @end example
 223
 224 In this example, items 7 and 8 were selected (output is shortened as indicated
 225 by @code{[...]}).  All or none of the items could have been selected by entering
 226 @code{all} or @code{none}, which can be abbreviated @code{a} or @code{n},
 227 respectively.
 228
 229 @opencatbox{Categories:}
 230 @category{Help}
 231 @category{Console interaction}
 232 @closecatbox
 233 @end deffn
 234
 235 @anchor{output_format_for_help}
 236 @defvr {Option variable} output_format_for_help
 237 Default value: @code{text}
 238
 239 @code{output_format_for_help} controls how @code{describe} displays
 240 help.
 241
 242 @code{output_format_for_help} can be set to one of the following
 243 values:
 244 @table @code
 245 @item text
 246 Help is displayed as plain text sent to a terminal.  This is the default.
 247 @item html
 248 Help is displayed using a browser to display the HTML version of the
 249 manual.
 250 @item frontend
 251 Help is displayed using the frontend's help system.  If no frontend is
 252 running then an error is signaled.  For example, wxMaxima and xmaxima
 253 are some frontends for maxima.
 254 @end table
 255
 256 Any other value is a error.
 257
 258
 259 See also @mrefcomma{browser} and @mrefdot{url_base}
 260
 261 @opencatbox{Categories:}
 262 @category{Help}
 263 @category{Global variables}
 264 @closecatbox
 265 @end defvr
 266
 267 @anchor{browser}
 268 @defvr {Option variable} browser
 269
 270 This specifies the command to use to open an HTML file.  This is a
 271 format string of the form @code{<cmd> ~A} where @code{~A} is replaced
 272 by the URL of the HTML file and @code{<cmd>} is some program that
 273 takes an arg and opens up a browser to the given URL.
 274
 275 On windows, the default setting is @code{"start ~A"},
 276 which uses the default browser to display the html file.  You may replace
 277 it with e.g. @code{start firefox ~A}, @code{start chrome ~A} or @code{start iexplore ~A}
 278 if you want to use Firefox, Chrome, or Internet Explorer
 279 instead of the default browser.
 280
 281 On other OSes, the user's default browser should be used
 282 automatically (using @code{xdg-open} on Linux/Unix and @code{open} on MacOS).
 283 You can also set the @code{browser} variable to use
 284 a non default browser, e.g.
 285 @code{browser:"firefox '~A'";} or @code{browser:"chromium '~A'";}
 286
 287 See also @mrefcomma{output_format_for_help} and @mrefdot{url_base}
 288
 289 @opencatbox{Categories:}
 290 @category{Help}
 291 @category{Global variables}
 292 @closecatbox
 293 @end defvr
 294
 295 @anchor{url_base}
 296 @defvr {Option variable} url_base
 297
 298 When displaying help using a browser, @code{url_base} defines the URL
 299 to use.  It defaults to a @code{file://} path pointing to the
 300 directory containing the html files for documentation.  However, you
 301 could use @code{http://localhost:8080/} or some other URL that has the HTML
 302 help files.  But this requires those URLs to have exactly the same
 303 HTML files in the info directory because a table is needed to
 304 translate a topic to the appropriate location in an html file.
 305
 306 See also @ref{output_format_for_help} and @mrefdot{browser}
 307
 308 @opencatbox{Categories:}
 309 @category{Help}
 310 @category{Global variables}
 311 @closecatbox
 312 @end defvr
 313
 314 @c -----------------------------------------------------------------------------
 315 @anchor{example}
 316 @deffn  {Function} example @
 317 @fname{example} (@var{topic}) @
 318 @fname{example} ()
 319
 320 @code{example (@var{topic})} displays some examples of @var{topic}, which is a
 321 symbol or a string.  To get examples for operators like @code{if}, @code{do},
 322 or @code{lambda} the argument must be a string, e.g. @code{example ("do")}.
 323 @code{example} is not case sensitive.  Most topics are function names.
 324
 325 @code{example ()} returns the list of all recognized topics.
 326
 327 The name of the file containing the examples is given by the global option
 328 variable @mrefcomma{manual_demo} which defaults to @code{"manual.demo"}.
 329
 330 @code{example} quotes its argument.  @code{example} returns @code{done} unless
 331 no examples are found or there is no argument, in which case @code{example}
 332 returns the list of all recognized topics.
 333
 334 Examples:
 335
 336 @c ===beg===
 337 @c example(append);
 338 @c example("lambda");
 339 @c ===end===
 340 @example
 341 @group
 342 (%i1) example(append);
 343 (%i2) append([y+x,0,-3.2],[2.5e+20,x])
 344 (%o2)             [y + x, 0, - 3.2, 2.5e+20, x]
 345 (%o2)                         done
 346 @end group
 347 (%i3) example("lambda");
 348 (%i4) lambda([x,y,z],x^2+y^2+z^2)
 349                                     2    2    2
 350 (%o4)            lambda([x, y, z], x  + y  + z )
 351 (%i5) %(1,2,a)
 352                               2
 353 (%o5)                        a  + 5
 354 (%i6) 1+2+a
 355 (%o6)                         a + 3
 356 (%o6)                         done
 357 @end example
 358
 359 @opencatbox{Categories:}
 360 @category{Help}
 361 @category{Console interaction}
 362 @closecatbox
 363 @end deffn
 364
 365 @c -----------------------------------------------------------------------------
 366 @anchor{manual_demo}
 367 @defvr {Option variable} manual_demo
 368 Default value: @code{"manual.demo"}
 369
 370 @code{manual_demo} specifies the name of the file containing the examples for
 371 the function @code{example}.  See @mrefdot{example}
 372
 373 @opencatbox{Categories:}
 374 @category{Help}
 375 @category{Global variables}
 376 @closecatbox
 377 @end defvr
 378