doc/info/alt-display.texi

   1 @menu
   2 * Introduction to alt-display::
   3 * Functions and Variables for alt-display::
   4 @end menu
   5
   6 @node Introduction to alt-display, Functions and Variables for alt-display, alt-display-pkg, alt-display-pkg
   7 @section Introduction to alt-display
   8
   9 The @emph{alt-display} package provides a means to change the way that
  10 Maxima displays its output. The @var{*alt-display1d*} and
  11 @var{*alt-display2d*} Lisp hooks were introduced to Maxima in 2002, but
  12 were not easily accessible from the Maxima REPL until the introduction
  13 of this package.
  14
  15 The package provides a general purpose function to define alternative
  16 display functions, and a separate function to set the display
  17 function. The package also provides customized display functions to
  18 produce output in @TeX{}, Texinfo, XML and all three output formats
  19 within Texinfo.
  20
  21 Here is a sample session:
  22
  23 @c (linenum:1,display2d:true,reset_displays());
  24 @example
  25 (%i1) load("alt-display.mac")$
  26 (%i2) set_alt_display(2,tex_display)$
  27
  28 (%i3) x/(x^2+y^2) = 1;
  29 \mbox@{\tt\red(@{\it \%o_3@}) \black@}$$@{@{x@}\over@{y^2+x^2@}@}=1$$
  30
  31 (%i4) set_alt_display(2,mathml_display)$
  32
  33 (%i5) x/(x^2+y^2) = 1;
  34 <math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi>
  35 <mfenced separators=""><msub><mi>%o</mi> <mn>5</mn></msub>
  36 <mo>,</mo><mfrac><mrow><mi>x</mi> </mrow> <mrow><msup><mrow>
  37 <mi>y</mi> </mrow> <mn>2</mn> </msup> <mo>+</mo> <msup><mrow>
  38 <mi>x</mi> </mrow> <mn>2</mn> </msup> </mrow></mfrac> <mo>=</mo>
  39 <mn>1</mn> </mfenced> </math>
  40
  41 (%i6) set_alt_display(2,multi_display_for_texinfo)$
  42
  43 (%i7) x/(x^2+y^2) = 1;
  44
  45 @@iftex
  46 @@tex
  47 \mbox@{\tt\red(@{\it \%o_7@}) \black@}$$@{@{x@}\over@{y^2+x^2@}@}=1$$
  48 @@end tex
  49 @@end iftex
  50 @@ifhtml
  51 @@html
  52
  53 <math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi>
  54 <mfenced separators=""><msub><mi>%o</mi> <mn>7</mn></msub>
  55 <mo>,</mo><mfrac><mrow><mi>x</mi> </mrow> <mrow><msup><mrow>
  56 <mi>y</mi> </mrow> <mn>2</mn> </msup> <mo>+</mo> <msup><mrow>
  57 <mi>x</mi> </mrow> <mn>2</mn> </msup> </mrow></mfrac> <mo>=</mo>
  58 <mn>1</mn> </mfenced> </math>
  59 @@end html
  60 @@end ifhtml
  61 @@ifinfo
  62 @@example
  63 (%o7) x/(y^2+x^2) = 1
  64 @@end example
  65 @@end ifinfo
  66 @end example
  67
  68 If the alternative display function causes an error, the error is
  69 trapped and the display function is reset to the default display. In the
  70 following example, the @code{error} function is set to display the
  71 output. This throws an error, which is handled by resetting the
  72 2d-display to the default.
  73
  74 @example
  75 (%i8) set_alt_display(2,?error)$
  76
  77 (%i9) x;
  78
  79 Error in *alt-display2d*.
  80 Messge: Condition designator ((MLABEL) $%O9 $X) is not of type
  81         (OR SYMBOL STRING FUNCTION).
  82 *alt-display2d* reset to nil.
  83  -- an error. To debug this try: debugmode(true);
  84
  85 (%i10) x;
  86 (%o10)                                 x
  87 @end example
  88
  89 @node Functions and Variables for alt-display,  , Introduction to alt-display, alt-display-pkg
  90 @section Functions and Variables for alt-display
  91
  92 @anchor{alt_display_output_type}
  93 @deffn {Function} alt_display_output_type (@var{form})
  94
  95 Determine the type of output to be printed. @var{Form} must be a lisp
  96 form suitable for printing via Maxima's built-in @code{displa}
  97 function. At present, this function returns one of three values:
  98 @var{text}, @var{label} or @var{unknown}.
  99
 100 An example where @code{alt_display_output_type} is used. In
 101 @code{my_display}, a text form is printed between a pair of tags
 102 @verb{|TEXT;>>|} and @verb{|<<TEXT;|} while a label form is printed between
 103 a pair tags @verb{|OUT;>>|} and @verb{|<<OUT;|} in addition to the usual
 104 output label.
 105
 106 The function @mref{set_prompt} also ensures that input labels are
 107 printed between matching @verb{|PROMPT;>>|} and @verb{|<<PROMPT;|} tags.
 108
 109 Thanks to
 110 @url{https://sourceforge.net/p/maxima/mailman/maxima-discuss/thread/7792c096-7e07-842d-0c3a-b2f039ef1f15%40gmail.com/#msg37235035,Eric
 111 Stemmler}.
 112
 113 @verbatim
 114 (%i1) (load("mactex-utilities"), load("alt-display.mac")) $
 115
 116 (%i2) define_alt_display(my_display(form),
 117 block([type,txttmplt,labtmplt],
 118 txttmplt:"~%TEXT;>>~%~a~%<<TEXT;~%",
 119 labtmplt:"~%OUT;>>~%(~a) ~a~a~a~%<<OUT;~%",
 120 type:alt_display_output_type(form),
 121 if type='text then
 122    printf(true,txttmplt,first(form))
 123 else if type='label then
 124      printf(true,labtmplt,first(form),"$$",tex1(second(form)),"$$")
 125 else
 126      block([alt_display1d:false, alt_display2d:false], displa(form)))) $
 127
 128 (%i3) (set_prompt('prefix, "PROMPT;>>",'suffix, "<<PROMPT;"),
 129       set_alt_display(1,my_display)) $
 130
 131 PROMPT;>>(%i4) <<PROMPT;integrate(x^n,x);
 132 PROMPT;>>
 133 TEXT;>>
 134 Is n equal to -1?
 135 <<TEXT;
 136 <<PROMPT;
 137 n;
 138
 139 OUT;>>
 140 (%o4) $$\frac{x^{n+1}}{n+1}$$
 141 <<OUT;
 142 PROMPT;>>(%i5) <<PROMPT;
 143 @end verbatim
 144
 145 @opencatbox{Categories:}
 146 @category{Package alt-display}
 147 @closecatbox
 148
 149 @end deffn
 150
 151
 152 @anchor{define_alt_display}
 153 @deffn {Function} define_alt_display (@var{function}(@var{input}), @var{expr})
 154 This function is similar to @code{define}: it evaluates its arguments
 155 and expands into a function definition. The @var{function} is a
 156 function of a single input @var{input}. For convenience, a substitution
 157 is applied to @var{expr} after evaluation, to provide easy access to
 158 Lisp variable names.
 159
 160 Set a time-stamp on each prompt:
 161 @example
 162 (%i1) load("alt-display.mac")$
 163
 164 (%i2) display2d: false$
 165
 166 (%i3) define_alt_display(time_stamp(x),
 167                 block([alt_display1d:false,alt_display2d:false],
 168                       prompt_prefix:printf(false,"~a~%",timedate()),
 169                       displa(x)));
 170
 171 (%o3) time_stamp(x):=block(
 172                  [\*alt\-display1d\*:false,
 173                   \*alt\-display2d\*:false],
 174                  \*prompt\-prefix\*
 175                   :printf(false,"~a~%",timedate()),displa(x))
 176 (%i4) set_alt_display(1,time_stamp);
 177
 178 (%o4) done
 179 2017-11-27 16:15:58-06:00
 180 (%i5)
 181 @end example
 182
 183 The input line @code{%i3} defines @code{time_stamp} using
 184 @code{define_alt_display}. The output line @code{%o3} shows that the
 185 Maxima variable names @code{alt_display1d}, @code{alt_display2d} and
 186 @code{prompt_prefix} have been replaced by their Lisp translations, as
 187 has @code{displa} been replaced by @code{?displa} (the display
 188 function).
 189
 190 The display variables @code{alt_display1d} and @code{alt_display2d} are
 191 both bound to @code{false} in the body of @code{time_stamp} to prevent
 192 an infinite recursion in @code{displa}.
 193
 194 @opencatbox{Categories:}
 195 @category{Package alt-display}
 196 @closecatbox
 197
 198 @end deffn
 199
 200 @anchor{info_display}
 201 @deffn {Function} info_display (@var{form})
 202 This is an alias for the default 1-d display function. It may be used as
 203 an alternative 1-d or 2-d display function.
 204
 205 @example
 206 (%i1) load("alt-display.mac")$
 207
 208 (%i2) set_alt_display(2,info_display);
 209
 210 (%o2) done
 211 (%i3) x/y;
 212
 213 (%o3) x/y
 214 @end example
 215
 216 @opencatbox{Categories:}
 217 @category{Package alt-display}
 218 @closecatbox
 219
 220 @end deffn
 221
 222 @anchor{mathml_display}
 223 @deffn {Function} mathml_display (@var{form})
 224 Produces MathML output.
 225
 226 @example
 227 (%i1) load("alt-display.mac")$
 228
 229 (%i2) set_alt_display(2,mathml_display);
 230 <math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi>
 231  <mfenced separators=""><msub><mi>%o</mi> <mn>2</mn></msub>
 232  <mo>,</mo><mi>done</mi> </mfenced> </math>
 233 @end example
 234
 235 @opencatbox{Categories:}
 236 @category{Package alt-display}
 237 @closecatbox
 238
 239 @end deffn
 240
 241 @anchor{tex_display}
 242 @deffn {Function} tex_display (@var{form})
 243 Produces TeX output.
 244
 245 @example
 246 (%i2) set_alt_display(2,tex_display);
 247 \mbox@{\tt\red(@{\it \%o_2@}) \black@}$$\mathbf@{done@}$$
 248 (%i3) x/(x^2+y^2);
 249 \mbox@{\tt\red(@{\it \%o_3@}) \black@}$$@{@{x@}\over@{y^2+x^2@}@}$$
 250 @end example
 251
 252 @opencatbox{Categories:}
 253 @category{Package alt-display}
 254 @closecatbox
 255
 256 @end deffn
 257
 258 @anchor{multi_display_for_texinfo}
 259 @deffn {Function} multi_display_for_texinfo (@var{form})
 260 Produces Texinfo output using all three display functions.
 261
 262 @example
 263 (%i2) set_alt_display(2,multi_display_for_texinfo)$
 264
 265 (%i3) x/(x^2+y^2);
 266
 267 @@iftex
 268 @@tex
 269 \mbox@{\tt\red(@{\it \%o_3@}) \black@}$$@{@{x@}\over@{y^2+x^2@}@}$$
 270 @@end tex
 271 @@end iftex
 272 @@ifhtml
 273 @@html
 274
 275    <math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi>
 276    <mfenced separators=""><msub><mi>%o</mi> <mn>3</mn></msub>
 277    <mo>,</mo><mfrac><mrow><mi>x</mi> </mrow> <mrow><msup><mrow>
 278    <mi>y</mi> </mrow> <mn>2</mn> </msup> <mo>+</mo> <msup><mrow>
 279    <mi>x</mi> </mrow> <mn>2</mn> </msup> </mrow></mfrac> </mfenced> </math>
 280 @@end html
 281 @@end ifhtml
 282 @@ifinfo
 283 @@example
 284 (%o3) x/(y^2+x^2)
 285 @@end example
 286 @@end ifinfo
 287 @end example
 288
 289 @opencatbox{Categories:}
 290 @category{Package alt-display}
 291 @closecatbox
 292
 293 @end deffn
 294
 295 @anchor{reset_displays}
 296 @deffn {Functions} reset_displays ()
 297 Resets the prompt prefix and suffix to the empty string, and sets both
 298 1-d and 2-d display functions to the default.
 299
 300 @opencatbox{Categories:}
 301 @category{Package alt-display}
 302 @closecatbox
 303
 304 @end deffn
 305
 306 @anchor{set_alt_display}
 307 @deffn {Function} set_alt_display (@var{num}, @var{display-function})
 308 The input @var{num} is the display to set; it may be either 1 or 2. The
 309 second input @var{display-function} is the display function to use. The
 310 display function may be either a Maxima function or a @code{lambda}
 311 expression.
 312
 313 Here is an example where the display function is a @code{lambda}
 314 expression; it just displays the result as @TeX{}.
 315 @example
 316 (%i1) load("alt-display.mac")$
 317
 318 (%i2) set_alt_display(2, lambda([form], tex(?caddr(form))))$
 319
 320 (%i3) integrate(exp(-t^2),t,0,inf);
 321 $$@{@{\sqrt@{\pi@}@}\over@{2@}@}$$
 322 @end example
 323
 324 A user-defined display function should take care that it @emph{prints}
 325 its output. A display function that returns a string will appear to
 326 display nothing, nor cause any errors.
 327
 328 @opencatbox{Categories:}
 329 @category{Package alt-display}
 330 @closecatbox
 331
 332 @end deffn
 333
 334 @anchor{set_prompt}
 335 @deffn {Function} set_prompt (@var{fix}, @var{expr})
 336 Set the prompt prefix or suffix to @var{expr}. The input @var{fix} must
 337 evaluate to one of @code{prefix}, @code{suffix}, @code{general},
 338 @code{prolog} or @code{epilog}. The input @var{expr} must evaluate to
 339 either a string or @code{false}; if @code{false}, the @var{fix} is reset
 340 to the default value.
 341
 342 @example
 343 (%i1) load("alt-display.mac")$
 344 (%i2) set_prompt('prefix,printf(false,"It is now: ~a~%",timedate()))$
 345
 346 It is now: 2014-01-07 15:23:23-05:00
 347 (%i3)
 348 @end example
 349
 350 The following example shows the effect of each option, except
 351 @code{prolog}. Note that the @code{epilog} prompt is printed as Maxima
 352 closes down. The @code{general} is printed between the end of input and
 353 the output, unless the input line ends in @code{$}.
 354
 355 Here is an example to show where the prompt strings are placed.
 356
 357 @example
 358 (%i1) load("alt-display.mac")$
 359
 360 (%i2) set_prompt(prefix, "<<prefix>> ", suffix, "<<suffix>> ",
 361                  general, printf(false,"<<general>>~%"),
 362                  epilog, printf(false,"<<epilog>>~%"));
 363
 364 (%o2)                                done
 365 <<prefix>> (%i3) <<suffix>> x/y;
 366 <<general>>
 367                                        x
 368 (%o3)                                  -
 369                                        y
 370 <<prefix>> (%i4) <<suffix>> quit();
 371 <<general>>
 372 <<epilog>>
 373 @end example
 374
 375 Here is an example that shows how to colorize the input and output when
 376 Maxima is running in a terminal or terminal emulator like
 377 Emacs@footnote{Readers using the @code{info} reader in @code{Emacs} will
 378 see the actual prompt strings; other readers will see the colorized
 379 output}.
 380
 381 @ifinfo
 382 @c  (%i2) set_prompt('prefix,"\e[1;31m",'suffix,"\e[0;32m",'general,"\e[1;34m",'epilog,"\e[00;m")$
 383 @example
 384 (%i1) load("alt-display.mac")$
 385
 386 (%i2) cs(s) := printf(false,"~a[~am",ascii(27),s)$
 387
 388 (%i3) set_prompt(prefix,cs("1;31"),suffix,cs("0;32"),general,cs("1;34"),epilog,cs("00;"));
 389 (%o3)                                done
 390 \e[1;31m(%i4)\e[0;32m integrate(exp(-x^2),x,0,inf);\e[1;34m
 391                                    sqrt(%pi)
 392 (%o4)                              ---------
 393                                        2
 394 \e[1;31m(%i5)\e[00;m
 395 @end example
 396 @end ifinfo
 397 @ifnotinfo
 398 @figure{color_terminal}
 399 @end ifnotinfo
 400
 401 Each prompt string starts with the ASCII escape character (27) followed
 402 by an open square bracket (91); each string ends with a lower-case m
 403 (109). The webpages
 404 @url{https://misc.flogisoft.com/bash/tip_colors_and_formatting} and
 405 @url{https://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html} provide
 406 information on how to use control strings to set the terminal colors.
 407
 408 @opencatbox{Categories:}
 409 @category{Package alt-display}
 410 @closecatbox
 411
 412 @end deffn
 413
 414 @c Local Variables:
 415 @c mode: texinfo
 416 @c TeX-master: "include-maxima"
 417 @c End: