This file documents Imaxima.

Copyright (C) 2002, 2003, 2004 Jesper Harder Copyright (C) 2004, 2007,
2008 Yasuaki Honda Copyright (C) 2020, 2021 Leo Butler

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Imaxima
*******

Imaxima is a package for displaying the output from the computer algebra
system Maxima as images typeset by TeX.

This manual documents imaxima version 5.46.0.  You can download the
latest version of imaxima from the Maxima website
(http://maxima.sourceforge.net/).

Since version 1.0b, imaxima and imath supports inline graphs.

Send suggestions and bug reports to the Maxima email list
<maxima-discuss@lists.sourceforge.net> or the Maxima bug tracker
(https://sourceforge.net/p/maxima/bugs/).

1 Installation
**************

Install imaxima by unpacking the tarball and doing the usual incantation

     ./configure
     make
     make install

and put

     (autoload 'imaxima "imaxima" "Image support for Maxima." t)

in your '.emacs' file.

If you use Interactive Math minor mode, put

     (autoload 'imath-mode "imath" "Interactive Math minor mode." t)

in your '.emacs' file.

To do line breaking imaxima requires the LaTeX package 'breqn'.  This
package is currently distributed from its CTAN webpage
(https://ctan.org/pkg/breqn) as breqn.tds.zip
(http://mirrors.ctan.org/install/macros/latex/contrib/breqn.tds.zip).

The files in 'breqn' must be installed in a place where TeX can find
them.  In a typical LaTeX installation you should put the '*.sty' and
'*.sym' files in

     /usr/share/texmf/tex/latex/breqn/

and the documentation files in

     /usr/share/texmf/doc/latex/breqn/.

The files can also be installed in a number of other places--consult
your TeX documentation for details.

Now run 'texhash' after installing the files.  You can use the command
'kpsewhich' to verify that TeX is able to find the files, e.g.

     kpsewhich breqn.sty

To get the best image quality a fairly recent version of Ghostscript is
recommended.  See Miscellaneous, for options suitable for using
older versions of Ghostscript or not using Ghostscript at all

1.1 Manual installation
=======================

If you cannot use 'make', the manual steps required for installation are

   * Byte compile 'imaxima.el' and 'imath.el'.
   * Place the files 'imaxima.el', 'imaxima.elc', 'imath.el',
     'imath.elc', 'imaxima-autoconf-variables.el' and 'imaxima.lisp' in
     Emacs' 'load-path' (see Lisp Libraries (emacs)).
   * Install the TeX files in the way explained above.

2 Usage
*******

To start using imaxima just type 'M-x imaxima'.  The imaxima directory
needs to be on Emacs' 'load-path'.

 -- Function: imaxima
     Starts a Maxima session in an Emacs buffer.

You can turn image generation off by evaluating

     display2d:true

in Maxima.  Output from Maxima is then shown with the usual ASCII
graphics.  To turn images on again, evaluate

     display2d:imaxima

If there is an error in a LaTeX expression you can press 'Mouse-2' (or
'<RET>') on the error message to view the error log and 'Mouse-3' (or
'M-<RET>') to view the LaTeX source file.

 -- User Option: imaxima-use-maxima-mode-flag
     Set to non-'nil' to use the Maxima mode from 'maxima.el'.

     By default 'imaxima.el' uses a very simple mode which doesn't
     provide any custom menus, font-locking or key-bindings.  You can,
     however, combine 'imaxima.el' with the Emacs mode from the Maxima
     distribution to get these features.

 -- Function: imaxima-latex
     Converts the Maxima buffer to a LaTeX document and opens it in
     LaTeX mode.  See imaxima-latex-buffer-name _Note:_ This command
     does not work in XEmacs.

 -- Function: imaxima-to-html
     Converts the Maxima buffer to a HTML document named session.html
     and opens it in HTML mode.  All the PNG files generated by imaxima
     for each output from Maxima are gathered in a folder named
     session-images and referenced from session.html.  _Note:_ This
     command does not work in XEmacs.

 -- Function: imaxima-clean-up
     Delete temporary files created by imaxima and kill the Ghostscript
     process if it is running.  Normally imaxima does this automatically
     when you quit Maxima.  This command is just a convenience if this
     doesn't happen.

 -- Function: imaxima-version
     Display the package name and the version number of the imaxima
     imath package in the mini buffer.  You should make sure the version
     information when you want to make bug reports.

 -- Function: reinit-imaxima
     Initialize the imaxima program.  Sometimes you may encounter
     situations where imaxima does not repond to your input.  This is
     caused by the inconsistency between Emacs Lisp and Maxima.  Such
     situations can be resolved by using this command.  After calling
     this command from the Emacs mini buffer, you should type simple
     Maxima expression such as 1+2; to ensure that the imaxima does
     respond to you now.

 -- Function: imaxima-print-buffer
     Run LaTeX on the current buffer and show output.  See
     imaxima-print-tex-command.  for how LaTeX is run.

3 Inline Graphs
***************

Since version 1.0b, imaxima and imath supports the inline graph display
feature.  That is, if a special graph command (such as wxplot2d,
wxplot3d) is used in the maxima session, the graph generated by the
command is inserted in the maxima session buffer, instead of displaying
in another window.

Before using this feature, you should make sure 'plot2d' works with
Gnuplot by trying:
     (%i1) plot2d(x^2,[x,-5,5],[plot_format,gnuplot]);
If this works fine, then quite likely 'wxplot2d' works, too.

Following commands can be used in a maxima session to draw graphs to be
displayed inline: 'wxplot2d', 'wxplot3d', 'wxdraw2d', 'wxdraw3d',
'wximplicit_plot', and 'wxcontour_plot'.  New in version 1.0d, the
graphics commands 'wxdraw', 'wxjulia' and 'wxmandelbroit' also provide
inline images.

The syntax and capabilities of the wx-prefixed versions of the commands
and their arguments are the same as the ones of the corresponding
original commands.  Hence, 'wxplot2d' draws a graph inline in the
imaxima buffer, while 'plot2d' displays the same graph in a different
window created by Gnuplot.

The wx-prefixed versions of the commands set up arguments so that
Gnuplot is used to draw the graph and writes the graph in extended
postscript format into a temporary file.  Conseqently, use of plot
options such as 'plot_format', 'gnuplot_script_file', 'gnuplot_term',
'ps_file' or their draw counterparts will result in unspecified
behaviour.

The 'wxdraw' family of commands automatically load the draw package
since they call 'draw' internally.  Similarly, 'wxjulia' and
'wxmandelbroit' automatically load the dynamics package.

3.1 Keybindings
===============

Images in the imaxima buffer have a special keymap (see keymaps (emacs)).
By hovering the mouse over the image, one can display
the list of 'hot keys' and a short description of each action pressing a
key triggers.  To activate the keymap, point must be on the image.

  1. l : Copy the LaTeX source to generate the image under point into
     the register stored in imaxima-latex-src-register (default:
     l).  See imaxima-get-latex-src.

  2. g : Have Gnuplot replot the graph/image under point in a separate
     window spawned by Gnuplot.  See imaxima-gnuplot-replot.

  3. s : Forcibly restart the Gnuplot process.  This can be useful if an
     error occurs during plotting.  Some 'plot' examples may only work
     if Gnuplot is restarted.  See imaxima-gnuplot-restart.

3.2 Commands and Options
========================

 -- Command: imaxima-get-latex-src
     When point is over an image, this copies the LaTeX source used by
     imaxima to generate the image into the register named by
     imaxima-latex-src-register.

 -- Command: imaxima-gnuplot-replot
     When point is over an image created by Gnuplot, this command will
     re-execute the Gnuplot script that created the image and display it
     in a separate window spawned by Gnuplot.  Asks for the Gnuplot
     terminal to use.  See imaxima-gnuplot-replot-term.

 -- Command: imaxima-gnuplot-restart
     Forcibly kill the Gnuplot process and buffer, if necessary, and
     then start a new Gnuplot process.

 -- User Option: imaxima-gnuplot-buffer
     The name of the buffer in which imaxima runs its Gnuplot process.
     Default: *imaxima-gnuplot*.

 -- User Option: imaxima-gnuplot-command
     The name of the Gnuplot executable that imaxima runs.  Default:
     gnuplot.

 -- User Option: imaxima-gnuplot-args
     Optional arguments sent to the Gnuplot executable by imaxima.
     Default: "".

 -- User Option: imaxima-latex-src-register
     One can copy the LaTeX source used to generate an image into a
     register by placing point over the image and typing this key.
     Default: 'l'.

 -- User Option: imaxima-gnuplot-replot-term
     The name of the Gnuplot terminal used to display an inline plot in
     an external, Gnuplot-spawned window.  See
     imaxima-gnuplot-replot.

4 Options
*********

All options can be changed in the Emacs customize interface, use 'M-x
customize-group <RET> imaxima <RET>'.

4.1 Appearance
==============

 -- User Option: imaxima-pt-size
     The type size used in LaTeX. This can be '9', '10', '11' or '12'
     pt.

 -- User Option: imaxima-fnt-size
     Default size of font.  Options include 'small', 'normalsize',
     'large', 'Large', 'LARGE', 'huge' or 'Huge' (in non decreasing
     order).

 -- User Option: imaxima-scale-factor
     Scale all images by this factor.  The default is '1.0'.

_Note:_ The options 'imaxima-pt-size', 'imaxima-fnt-size' and
'imaxima-scale-factor' are highly non-orthogonal.

 -- User Option: imaxima-equation-color
     Color used for equations.

 -- User Option: imaxima-label-color
     Color used for output labels (red by default).

 -- User Option: imaxima-bg-color
     Background color used in the imaxima buffer.  'nil' if you don't
     want to change the default color.

 -- User Option: imaxima-fg-color
     Foreground color used in the imaxima buffer.  'nil' if you don't
     want to change the default color.

 -- User Option: imaxima-latex-preamble
     (See options 'imaxima-latex-document-class',
     'imaxima-latex-use-packages', 'imaxima-latex-document-dimensions',
     'imaxima-latex-macros' and 'imaxima-latex-macros-linear'.)  LaTeX
     expression inserted at the start of the document preamble when
     TeX'ing equations.  This can be used to change, say, the document
     font.  E.g.

          \usepackage{concrete}
          \usepackage{euler}

     will use Herman Zapf's Euler math fonts and the accompanying
     Concrete roman fonts.  These are probably better suited as screen
     fonts than the default Computer Modern, which works best at high
     resolutions.

 -- User Option: imaxima-latex-error-face
     Face used for LaTeX errors.  This option is ignored when using
     'maxima.el'.

 -- User Option: imaxima-latex-document-class
     An elisp list (FORMAT-STRING [ARGS]) that provides a valid list of
     inputs to 'format'.  FORMAT-STRING should generate the LaTeX
     document class used to generate all LaTeX documents; ARGS is
     evaluated.  Used by 'imaxima-latex'.

 -- User Option: imaxima-latex-use-packages
     A string that contains all 'usepackage' declarations needed.  This
     is inserted into the LaTeX document after 'imaxima-latex-preamble'.

 -- User Option: imaxima-latex-macros-format-file
     Macros used by 'imaxima-dump-tex' to generate the format file.

 -- User Option: imaxima-latex-macros, imaxima-latex-macros-linear
     A string that defines _imaxima_-specific macros to format fractions
     in regular and linear fashion.

 -- User Option: imaxima-latex-document-dimensions
     A string the contains the document dimensions for 'imaxima-latex'.

 -- User Option: imaxima-create-image-options
     An association list of options that are used by the imaxima
     function 'imaxima-create-image'.  For example, if one is using a
     dark background in emacs, it may be preferable to set this option
     to '(:ascent center)', thereby removing the default mask option.

4.2 Line Breaking
=================

Imaxima usually does a decent job of breaking lines that are too wide to
fit in the buffer (thanks to the 'breqn' LaTeX package).  However, this
doesn't work so well for very long fractions, superscripts and
subscripts.  Imaxima has two ways of dealing with this:

   * Scaling.
   * Rewriting the equation in a "linear" form which can be split over
     several lines.

The following options control how this is done.

 -- User Option: imaxima-max-scale
     Maximum amount of scaling allowed to fit wide equations in the
     buffer.  The default is '0.85', which allows images to be scaled
     down to 85% of the original size.  'nil' disables scaling and 't'
     allows unlimited scaling.

 -- User Option: imaxima-linearize-flag
     Non-'nil' allows fractions, superscripts, subscripts and square
     roots to be linearized to fit in the buffer.  That is

                   b                           a + b         _______
                  a              a            -------       V a + b
                                  b            c + d

     are written as

                                                                    ?
              expt(a,b)   subscript(a,b)   (a + b)/(c + d)   (a + b)

4.3 Miscellaneous
=================

If the required files are in your path, you shouldn't normally need to
change these options.

 -- User Option: imaxima-latex-buffer-name
     The default name of the buffer created by 'imaxima-latex'.  The
     default value is '*imaxima-latex*'.

 -- User Option: imaxima-image-type
     Image type used in the buffer.  PNG, JPEG, TIFF and PostScript are
     supported.  In my opinion PNG gives the best results, but if your
     Emacs wasn't compiled with PNG support you could try one of the
     others.  PostScript doesn't require Ghostscript to be installed.
     XEmacs can not display PostScript images, so this type does not
     work in XEmacs.

 -- User Option: imaxima-gs-program
     Ghostscript executable

 -- User Option: imaxima-gs-options
     Options passed to 'gs' when converting EPS to other image formats.
     Older versions of Ghostscript don't support anti-aliasing.  In that
     case you might have to remove the options '-dTextAlphaBits=4' and
     '-dGraphicsAlphaBits=4'.

 -- User Option: imaxima-cp-program
     The default 'copy' program.

 -- User Option: imaxima-dvips-program
     Dvips executable.

 -- User Option: imaxima-dvips-options
     Command line options passed to 'dvips' when converting EPS files to
     DVI.

 -- User Option: imaxima-tmp-dir
     Directory used for temporary files created by imaxima.  '/tmp' by
     default.

 -- User Option: imaxima-lisp-file
     The Lisp file used to initialize Maxima.

 -- User Option: imaxima-tex-program
     TeX executable.

 -- User Option: imaxima-initex-option
     Option passed to TeX to start it in the "initial" form capable of
     dumping format files.

 -- User Option: imaxima-maxima-program
     Maxima executable.

 -- User Option: imaxima-maxima-options
     Command line arguments passed to Maxima.  If you have Maxima
     versions compiled with different Lisps, you can use this to select
     which one to use.  E.g.  '--lisp=cmucl' will choose the version
     compiled with CMUCL.

 -- User Option: imaxima-startup-hook
     Hook run when starting imaxima.

 -- User Option: imaxima-exit-hook
     Hook run when exiting imaxima.

 -- User Option: imaxima-html-dir
     When imaxima-to-html function is called, the function determines
     the directory into which the session.html file and the
     session-images directory are created.  The default value is "~".

 -- User Option: imaxima-print-tex-file
     Name of the LaTeX file name to be created by
     'imaxima-print-buffer'.  Do not include ".tex" suffix.  This file
     will be stored in the directory 'imaxima-tmp-dir'.

 -- User Option: imaxima-print-tex-command
     Command to run LaTeX on the file created by 'imaxima-print-buffer'.
     In the string '%s' is replaced by the name of the tex file.  e.g.
     "pdflatex %s; xpdf %s"

5 Imath minor mode
******************

The imath minor mode provides a small set of functions to aid insert
math formulas into plain text.

A math formula is written using a Maxima form whose syntax is {maxima a
formula maxima} where a formula is a string which can be accepted as
Maxima command input.  C-c [ inserts a template for a maxima form.

The other way to write a math formula is to use LaTeX form whose syntax
is {latex a formula latex} where a formula is a valid LaTeX commands.
C-c ] inserts a template for a latex form.

Example maxima and latex forms are:
     {maxima integrate(f(x),x) maxima}
     {maxima sum(a[n],n,0,i) maxima}
     {latex  \\int {f\\left(x\\right)}{\\;dx} latex}
     {latex  \\sum_{n=0}^{i}{a_{n}} latex}

Assuming the cursor position is right after a form or in the middle, C-c
!  transforms the form into the formula image using the Imaxima
functionality.

If the resulting image is not what you want, you may want to edit the
formula again.  To do this, place the cursor right after the image and
C-c &.  Then the image is removed and original form appears at the
position.

When saving the buffer into a file, images are discarded.  However,
maxima forms and their corresponding latex forms are kept there in the
text.  If the text is loaded again into Emacs and imath minor mode is
enabled, you can type C-c $ to restore all the images for the forms in
the buffer.

     \C-c[   Compose Maxima form
     \C-c]   Compose Latex form
     \C-c!   Transform a form to an image
     \C-c$   Transform all forms to images
     \C-c&   Remove the image to restore the original form text

You can export the imath mode buffer contents into HTML using a command
named imath-to-html.  This command can be invoked by M-x imath-to-html.
Then a buffer is created, visiting a file whose name is the same as the
original imath text file, only exception being .html as the file
extension.  Upon saving, the file is placed in the same directory as the
original file.  Also a directory is created whose name is the same as
the imath text file, but removing the extension and add -images.  Images
for formulas are copied in this directory.