doc/info/Miscellaneous.texi

   1 @menu
   2 * Introduction to Miscellaneous Options::
   3 * Share::
   4 * Functions and Variables for Miscellaneous Options::
   5 @end menu
   6
   7 @c -----------------------------------------------------------------------------
   8 @node Introduction to Miscellaneous Options, Share, Miscellaneous Options, Miscellaneous Options
   9 @section Introduction to Miscellaneous Options
  10 @c -----------------------------------------------------------------------------
  11
  12 In this section various options are discussed which have a global effect
  13 on the operation of Maxima.  Also various lists such as the list of all
  14 user defined functions, are discussed.
  15
  16 @c -----------------------------------------------------------------------------
  17 @node Share, Functions and Variables for Miscellaneous Options, Introduction to Miscellaneous Options, Miscellaneous Options
  18 @section Share
  19 @c -----------------------------------------------------------------------------
  20
  21 The Maxima "share" directory contains programs and other files
  22 of interest to Maxima users, but not part of the core implementation of Maxima.
  23 These programs are typically loaded via @code{load} or @code{setup_autoload}.
  24
  25 @code{:lisp *maxima-sharedir*} displays the location of the share directory
  26 within the user's file system.
  27
  28 @c FIXME FIXME FIXME -- WE REALLY NEED AN UP-TO-DATE LIST OF SHARE PACKAGES !!
  29 @code{printfile ("share.usg")} prints an out-of-date list of share packages.
  30 Users may find it more informative to browse the share directory using a file
  31 system browser.
  32
  33 @c -----------------------------------------------------------------------------
  34 @node Functions and Variables for Miscellaneous Options,  , Share, Miscellaneous Options
  35 @section Functions and Variables for Miscellaneous Options
  36 @c -----------------------------------------------------------------------------
  37
  38 @c After studying src/compar.lisp, it appears that askexp would
  39 @c work as advertised, except that it doesn't appear to be possible
  40 @c to open a break prompt with ^A or any other character.
  41 @c What should we do about askexp ???
  42
  43 @c -----------------------------------------------------------------------------
  44 @anchor{askexp}
  45 @defvr {System variable} askexp
  46
  47 When @code{asksign} is called,
  48 @code{askexp} is the expression @code{asksign} is testing.
  49
  50 At one time, it was possible for a user to inspect @code{askexp}
  51 by entering a Maxima break with control-A.
  52
  53 @opencatbox{Categories:}
  54 @category{Declarations and inferences}
  55 @closecatbox
  56 @end defvr
  57
  58 @c -----------------------------------------------------------------------------
  59 @anchor{genindex}
  60 @defvr {Option variable} genindex
  61 Default value: @code{i}
  62
  63 @code{genindex} is the alphabetic prefix used to generate the
  64 next variable of summation when necessary.
  65
  66 @opencatbox{Categories:}
  67 @category{Sums and products}
  68 @closecatbox
  69 @end defvr
  70
  71 @anchor{gensumnum}
  72 @defvr {Option variable} gensumnum
  73 Default value: 0
  74
  75 @code{gensumnum} is the numeric suffix used to generate the next variable
  76 of summation.  If it is set to @code{false} then the index will consist only
  77 of @code{genindex} with no numeric suffix.
  78
  79 @opencatbox{Categories:}
  80 @category{Sums and products}
  81 @closecatbox
  82 @end defvr
  83
  84 @c -----------------------------------------------------------------------------
  85 @anchor{gensym}
  86 @deffn  {Function} gensym @
  87 @fname{gensym} () @
  88 @fname{gensym} (@var{x})
  89
  90 @code{gensym()} creates and returns a fresh symbol.
  91
  92 The name of the new symbol is the concatenation of a prefix, which defaults to
  93 "g", and a suffix, which is an integer that defaults to the value of an internal
  94 counter.
  95
  96 If @var{x} is supplied, and is a string, then that string is used as a prefix
  97 instead of "g" for this call to gensym only.
  98
  99 If @var{x} is supplied, and is a nonnegative integer, then that integer, instead
 100 of the value of the internal counter, is used as the suffix for this call to
 101 gensym only.
 102
 103 If and only if no explicit suffix is supplied, the internal counter is
 104 incremented after it is used.
 105
 106 Examples:
 107
 108 @c ===beg===
 109 @c gensym();
 110 @c gensym("new");
 111 @c gensym(123);
 112 @c ===end===
 113 @example
 114 (%i1) gensym();
 115 (%o1)                         g887
 116 (%i2) gensym("new");
 117 (%o2)                        new888
 118 (%i3) gensym(123);
 119 (%o3)                         g123
 120 @end example
 121 @end deffn
 122
 123 @c STILL EXISTS, NEEDS CLARIFICATION !!!
 124
 125 @c -----------------------------------------------------------------------------
 126 @anchor{packagefile}
 127 @defvr {Option variable} packagefile
 128 Default value: @code{false}
 129
 130 Package designers who use @mref{save} or @mref{translate} to create packages
 131 (files) for others to use may want to set @code{packagefile: true} to prevent
 132 information from being added to Maxima's information-lists (e.g.
 133 @mrefcomma{values} @mref{functions}) except where necessary when the file is
 134 loaded in.  In this way, the contents of the package will not get in the user's
 135 way when he adds his own data.  Note that this will not solve the problem of
 136 possible name conflicts.  Also note that the flag simply affects what is output
 137 to the package file.  Setting the flag to @code{true} is also useful for
 138 creating Maxima init files.
 139
 140 @opencatbox{Categories:}
 141 @category{Translation flags and variables}
 142 @closecatbox
 143 @end defvr
 144
 145
 146 @c NEEDS EXAMPLES
 147
 148 @c -----------------------------------------------------------------------------
 149 @anchor{remvalue}
 150 @deffn  {Function} remvalue @
 151 @fname{remvalue} (@var{name_1}, @dots{}, @var{name_n}) @
 152 @fname{remvalue} remvalue (all)
 153
 154 Removes the values of user variables @var{name_1}, @dots{}, @var{name_n}
 155 (which can be subscripted) from the system.
 156
 157 @code{remvalue (all)} removes the values of all variables in @code{values},
 158 the list of all variables given names by the user
 159 (as opposed to those which are automatically assigned by Maxima).
 160
 161 See also @mrefdot{values}
 162
 163 @opencatbox{Categories:}
 164 @category{Evaluation}
 165 @closecatbox
 166 @end deffn
 167
 168 @c NEEDS EXAMPLES
 169
 170 @c -----------------------------------------------------------------------------
 171 @anchor{rncombine}
 172 @deffn {Function} rncombine (@var{expr})
 173
 174 Transforms @var{expr} by combining all terms of @var{expr} that have
 175 identical denominators or denominators that differ from each other by
 176 numerical factors only.  This is slightly different from the behavior
 177 of @mrefcomma{combine} which collects terms that have identical denominators.
 178
 179 Setting @code{pfeformat: true} and using @code{combine} yields results similar
 180 to those that can be obtained with @code{rncombine}, but @code{rncombine} takes
 181 the additional step of cross-multiplying numerical denominator factors.
 182 This results in neater forms, and the possibility of recognizing some
 183 cancellations.
 184
 185 @code{load("rncomb")} loads this function.
 186
 187 @opencatbox{Categories:}
 188 @category{Expressions}
 189 @closecatbox
 190 @end deffn
 191
 192 @c -----------------------------------------------------------------------------
 193 @anchor{setup_autoload}
 194 @deffn {Function} setup_autoload (@var{filename}, @var{function_1}, @dots{}, @var{function_n})
 195
 196 Specifies that if any of @var{function_1}, @dots{}, @var{function_n} are
 197 referenced and not yet defined, @var{filename} is loaded via @code{load}.
 198 @var{filename} usually contains definitions for the functions specified,
 199 although that is not enforced.
 200
 201 @code{setup_autoload} does not work for @mrefdot{memoizing functions}
 202
 203 @code{setup_autoload} quotes its arguments.
 204
 205 Example:
 206
 207 @c EXAMPLE GENERATED FROM FOLLOWING INPUT
 208 @c legendre_p (1, %pi);
 209 @c setup_autoload ("specfun.mac", legendre_p, ultraspherical);
 210 @c ultraspherical (2, 1/2, %pi);
 211 @c legendre_p (1, %pi);
 212 @c legendre_q (1, %pi);
 213 @example
 214 (%i1) legendre_p (1, %pi);
 215 (%o1)                  legendre_p(1, %pi)
 216 (%i2) setup_autoload ("specfun.mac", legendre_p, ultraspherical);
 217 (%o2)                         done
 218 (%i3) ultraspherical (2, 1/2, %pi);
 219 Warning - you are redefining the Macsyma function ultraspherical
 220 Warning - you are redefining the Macsyma function legendre_p
 221                             2
 222                  3 (%pi - 1)
 223 (%o3)            ------------ + 3 (%pi - 1) + 1
 224                       2
 225 (%i4) legendre_p (1, %pi);
 226 (%o4)                          %pi
 227 (%i5) legendre_q (1, %pi);
 228                               %pi + 1
 229                       %pi log(-------)
 230                               1 - %pi
 231 (%o5)                 ---------------- - 1
 232                              2
 233 @end example
 234
 235 @opencatbox{Categories:}
 236 @category{Function definition}
 237 @category{File input}
 238 @closecatbox
 239 @end deffn
 240
 241 @c RECOMMEND CUTTING THIS ITEM AND CUTTING $tcl_output IN src/plot.lisp
 242 @c THIS REALLY, REALLY SEEMS LIKE CRUFT:
 243 @c $tcl_output IS NEVER CALLED WITHIN MAXIMA SOURCE,
 244 @c AND THIS EXTREMELY NARROW, LIMITED FUNCTIONALITY ISN'T USEFUL TO USERS
 245 @c AND IT'S BROKEN: INCORRECT OUTPUT FOR CLISP, DIES ON GCL
 246
 247 @c -----------------------------------------------------------------------------
 248 @anchor{tcl_output}
 249 @deffn  {Function} tcl_output @
 250 @fname{tcl_output} (@var{list}, @var{i0}, @var{skip}) @
 251 @fname{tcl_output} (@var{list}, @var{i0}) @
 252 @fname{tcl_output} ([@var{list_1}, @dots{}, @var{list_n}], @var{i})
 253
 254 Prints elements of a list enclosed by curly braces @code{@{ @}},
 255 suitable as part of a program in the Tcl/Tk language.
 256
 257 @code{tcl_output (@var{list}, @var{i0}, @var{skip})}
 258 prints @var{list}, beginning with element @var{i0} and printing elements
 259 @code{@var{i0} + @var{skip}}, @code{@var{i0} + 2 @var{skip}}, etc.
 260
 261 @code{tcl_output (@var{list}, @var{i0})}
 262 is equivalent to @code{tcl_output (@var{list}, @var{i0}, 2)}.
 263
 264 @code{tcl_output ([@var{list_1}, ..., @var{list_n}], @var{i})}
 265 prints the @var{i}'th elements of @var{list_1}, @dots{}, @var{list_n}.
 266
 267 Examples:
 268 @c EXAMPLE INPUT
 269 @c tcl_output ([1, 2, 3, 4, 5, 6], 1, 3)$
 270 @c tcl_output ([1, 2, 3, 4, 5, 6], 2, 3)$
 271 @c tcl_output ([3/7, 5/9, 11/13, 13/17], 1)$
 272 @c tcl_output ([x1, y1, x2, y2, x3, y3], 2)$
 273 @c tcl_output ([[1, 2, 3], [11, 22, 33]], 1)$
 274
 275 @c EXAMPLE OUTPUT: CLISP
 276 @c OUTPUT IS OK FOR FIRST TWO, BROKEN FOR OTHERS
 277 @c GCL OUTPUT: SAME FOR FIRST TWO
 278 @c GCL FAILS ON OTHERS (IN EACH CASE COMPLAINING ELEMENTS ARE "not of type (OR RATIONAL LISP:FLOAT)")
 279 @example
 280 (%i1) tcl_output ([1, 2, 3, 4, 5, 6], 1, 3)$
 281
 282  @{1.000000000     4.000000000
 283  @}
 284 (%i2) tcl_output ([1, 2, 3, 4, 5, 6], 2, 3)$
 285
 286  @{2.000000000     5.000000000
 287  @}
 288 (%i3) tcl_output ([3/7, 5/9, 11/13, 13/17], 1)$
 289
 290  @{((RAT SIMP) 3 7) ((RAT SIMP) 11 13)
 291  @}
 292 (%i4) tcl_output ([x1, y1, x2, y2, x3, y3], 2)$
 293
 294  @{$Y1 $Y2 $Y3
 295  @}
 296 (%i5) tcl_output ([[1, 2, 3], [11, 22, 33]], 1)$
 297
 298  @{SIMP 1.000000000     11.00000000
 299  @}
 300 @end example
 301 @end deffn
 302