\input texinfo
@c -*-texinfo-*-

@setfilename  xmaxima.info
@synindex ky cp
@settitle Xmaxima Manual

@setchapternewpage odd
@ifinfo
This is the Reference Manual for Xmaxima

Copyright 2006-2021 Jaime E. Villate

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
MA 02110-1301, USA.

@format
INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* Xmaxima: (xmaxima).     Graphical interface for Maxima.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@titlepage
@title Xmaxima Manual
@author Jaime E. Villate
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2006 Jaime E. Villate

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
MA 02110-1301, USA.

@end titlepage

@contents

@node Top, Command-line options, (dir), (dir)

@dfn{Xmaxima} is a graphical interface for @dfn{Maxima}, written in
@dfn{Tcl/Tk}. It also provides the @dfn{xmaxima} plotting program for
Maxima (formerly called 'openmath'), which can do some of the plots done by Maxima's default plotter
(@dfn{gnuplot}) and a few more that gnuplot cannot do.

This manual was written for Xmaxima - the screenshots are from the Linux version of Maxima 5.43.2. Some familiarity
with Maxima is assumed. There is a separate reference manual for
Maxima, which can be browsed and studied from Xmaxima.

@menu
* Command-line options::
* Main Window::
* Entering commands::
* Session control::
* Xmaxima plots::
* The browser::
* Getting Help::
* Concept Index::
@end menu

@node Command-line options, Main Window, Top, Top
@chapter Command-line options

The executable program, xmaxima, accepts the following command-line
options:

@table @option
@item @code{--help}
@itemx @code{-h}
Displays a brief usage summary.
@item @code{--url} site
Start Xmaxima's browser with the page at the URL @samp{site}
@item @code{--use-version} ver
@itemx @code{-u} ver
Launch version @samp{ver} of Maxima.
@item @code{--lisp} flavor
@itemx @code{-l} flavor
Use the lisp implementation @samp{flavor} of Maxima.
@item @code{--lisp-options} lisp-options
@itemx @code{-X} lisp-options
Options to be given to the underlying Lisp.
Option lines containing spaces have to be
quoted to be passed to the lisp as a whole.
@end table

@node Main Window, Entering commands, Command-line options, Top
@chapter Xmaxima Window

By default, Xmaxima creates two windows, a command window, where all
the commands for Maxima will be entered and the output returned by
Maxima will be printed.
@cindex text window

The second window is Xmaxima's browser; it is used to show a quick
primer, a copy of the Maxima manual and any other HTML you might want to
download from the Web.
@cindex browser

@ifnotinfo
@image{figures/xmaximawindow,8cm}
@end ifnotinfo

@ifnotinfo
@image{figures/xmaximabrowser,8cm}
@end ifnotinfo

The cursor is the small vertical bar that blinks in the text window. The
text that is currently being written in the text window and which could
be submitted to Maxima for evaluation is rendered in green. The text
sent back by Maxima is rendered in black, and the text that has been
previously entered by the user and that was already evaluated by Maxima
is rendered in blue.


You can also choose different types and sizes for the fonts, in the
section @samp{Preferences} of the @code{Options} menu; those settings
will be saved for future sessions.
@cindex Preferences

@node Entering commands, Session control, Main Window, Top
@chapter Entering commands

Most commonly, you will enter Maxima commands in the last input line
that appears on the text Window. That text will be rendered in green.
If you press enter, without having written a command-termination
character (either @samp{;} or @samp{$}) at the end, the text will remain
green and you can continue to write a multi-line command.  When you type
a command-end character and press the enter key, the text will become
blue and a response from Maxima should appear in black. You can also use
the key combination @kbd{Ctrl-j} to move to a new line without sending
the input for Maxima evaluation yet. If you want to clear all the
current input (in green), even if it spans several lines, use the key
combination @kbd{Ctrl-u}.
@kindex ;
@kindex $
@kindex Ctrl-j
@kindex Ctrl-u

If you move the cursor over the @code{(%i1)} input label, or any other
label or output text (in black), you will not be able to type any text
there; that feature will prevent you from trying to enter a command in
the wrong place, by mistake. If you really want to insert some
additional text to modify Maxima's output, and which will not be
interpreted by Maxima, you can do that using cut and paste (we will
cover that later).

You can also write a new input command for Maxima on top of a previous
input line (in blue), for instance, if you do not want to write down
again everything but just want to make a slight change. Once you press
the enter key, the text you modified will appear at the last input line,
as if you had written it down there; the input line you modified will
continue the same in Xmaxima's and Maxima's memory, in spite of having
changed in the screen.

For example, suppose you entered @samp{a: 45;} in input line
@code{(%i1)}, and something else in @code{(%i2)}. You then move up over
the @code{(%i1) a: 45;} and change the 5 for an 8. Once you press enter,
you will have in the screen @code{(%i1) a: 48;} and @code{(%i3) a: 48;}.
But if you write, in the current input line, @code{(%i1)} the original
input @samp{a: 45;} will reappear. If you navigate through the input
lines history (see next section), you will also see that the first input
keeps its original value.

@section Input lines history
When the cursor is at the end of the last @code{(%i)} label, you can use
the key combinations @kbd{Alt-p} and @kbd{Alt-n} to recover the previous
or next command that you entered. If you have just pressed @kbd{Alt-n},
the @samp{next} command means the first one you entered; but if you
press it again it will mean the second one and so on.
@kindex Alt-p
@kindex Alt-n

In the same way, if you press @kbd{Alt-p} repeatedly, until you reached
the first input, it will then continue to the last command you
entered. Once you get on the screen the command that you were looking
for, it will appear in green, as if you would have just type it, and you
can modify it before you press enter.

Those two key combinations can also be used to search for a previous
input line with a particular string in it. You first write down the
string to search, and then press @kbd{Alt-p}, to search backwards, or
@kbd{Alt-n} to search forward. Pressing those key combinations
repeatedly will allow you to cycle through all the lines that contain
the string. If you want to try a different string in the middle of the
search, you can delete the current input, type the new string, and start
the search again.

@section Cutting and pasting
You can cut or copy a piece of text that you select, from anywhere on
text window; not just from the input lines but also from the output text
in black.

To select the text, you can drag the cursor with the mouse while you
keep its left button depressed, or you can hold the @kbd{shift} key with
one finger, while you move the cursor with the mouse or with the arrow
keys.

Once you have selected the text, you can either cut it, with
@kbd{Ctrl-x}, or copy it to an internal buffer, with
@kbd{Ctrl-c}. Instead of those key combinations, you can also use two
options that appear inside the @command{Edit} menu.
@kindex Ctrl-x
@kindex Ctrl-c
@cindex Cut
@cindex Copy

The text that has been cut or copied more recently can be pasted
anywhere, even in the output fields, using @kbd{Ctrl-v} or an option in
the @command{Edit} menu.
@kindex Ctrl-v
@cindex Paste
@cindex Edit

There is a command similar to @samp{cut}, called @samp{kill}
(@kbd{Ctrl-k}, with two major differences: it only works in input fields
(blue or green) and instead of cutting a text that was selected, it will
cut all the text from the cursor until the end of the input line where
the cursor is.  The command @samp{Clear input} (@kbd{Ctrl-u}) is similar
to @samp{kill}, but it will cut the whole input line.
@kindex Ctrl-k
@kindex Ctrl-u
@cindex Kill
@cindex Clear input

To paste the last text that you have cut with either @samp{kill} or
@samp{clear input}, you should use the @samp{yank} command,
@kbd{Ctrl-y}. If you prefer, you can use entries in the @command{Edit}
menu to kill, clear input and yank.
@kindex Ctrl-y
@cindex Yank

@section Other key combinations
There are other useful key combinations, which are not particular to
Xmaxima, but are defined in most Tcl/Tk programs:

@table @kbd
@item Ctrl-f
The same as the right arrow key.
@kindex Ctrl-f
@item Ctrl-b
The same as the left arrow key.
@kindex Ctrl-b
@item Ctrl-p
The same as the up arrow key.
@kindex Ctrl-p
@item Ctrl-n
The same as the down arrow key.
@kindex Ctrl-n
@item Ctrl-a
Moves to the first character in a line (either input or output)
@kindex Ctrl-a
@item Ctrl-e
Moves to the last character in a line (either input or output)
@kindex Ctrl-e
@item PageUp
Moves one page up
@kindex PageUp
@item PageDown
Moves one page down
@kindex PageDown
@item Home
Moves the first character in the text window.
@kindex Home
@item End
Moves to the last character in the text window.
@kindex End
@end table

@node Session control, Xmaxima plots, Entering commands, Top
@chapter Session control

The @command{File} menu has sections to manage the work session in
Xmaxima. The @samp{Batch file} and @samp{Batch file silently} sections
are equivalent to Maxima's commands @command{batch} and
@command{batchload}, which can also be used in Xmaxima. The advantage of
those two options is that they will open a dialog box that will allow
you to navigate through your directories, until you find the one that
you are looking for.
@cindex Batch file
@cindex File

The @samp{Restore Maxima State} (@kbd{Alt-i}) section allows you to
reload the state of a Maxima session that you saved using the @samp{Save
Maxima State to File} section. The latter saves the state as a Lisp file
using Maxima's @command{save} command.
@cindex Save Maxima State
@cindex Restore Maxima State
@cindex Alt-i

The @samp{Save Maxima Input to File} (@kbd{Ctrl-a}) section saves each
input line as Maxima code using the Maxima @command{stringout}
command. This code can be manually edited in a text editor and loaded
into Xmaxima using @samp{Batch file}.
@cindex Save Maxima Input
@cindex Ctrl-a

In the menu @command{Edit} there is also an option @samp{Save console to
file} which will save the complete contents of the text window into a
file. The input and output will be saved as they look on the screen, and
not as they were originally written.
@cindex Edit

The option @samp{Input prompt} (@kbd{Alt-s}) will repeat the last input
label sent back by Maxima. That will be useful if you are working on a text
that is not near the last input label and you want to move quickly to
the last input.
@kindex Alt-s

Option @samp{Interrupt} (@kbd{Alt-g}) can be used to interrupt a
calculation. And the option @samp{Restart} will end the current
execution of Maxima; a new Maxima process will be invoked, so the input
prompt will start again as @code{(%i1)}.
@kindex Alt-g
@cindex Interrupt
@cindex Restart

@node Xmaxima plots, The browser, Session control, Top
@chapter Xmaxima plots

@dfn{Xmaxima} can be used either directly or from Maxima, to plot 2d
and 3d graphs. From Maxima, it will be used by the functions
@command{plot2d} and @command{plot3d}, if the option @code{[plot_format,
xmaxima]} is used. There are other plotting functions in Maxima that
will only work with the xmaxima plot_format: @command{plotdf}, @command{openplot_curves}
and @command{graph2d}. All those plotting functions are documented in
the Maxima Reference Manual.
@cindex plot2d
@cindex plot3d
@cindex plotdf
@cindex openplot_curves
@cindex graph2d

A command used to create a 2d xmaxima plot, for example:

@example
plot2d(sin(x), [x, -%pi, %pi], [plot_format, xmaxima]);
@end example

creates a window with a menu bar with the following options:

@itemize @bullet
@item @dfn{Close}. Destroys the plot window and sends the control back
to Maxima.
@cindex Close

@item @dfn{Config}. Allows you to change some configurations of the
plot.
@cindex Config

@item @dfn{Replot}. After configuration changes are made, this
menu option should be selected, to activate the new settings.
@cindex Replot

@item @dfn{Zoom}. Will change the behavior of the mouse so that it will
allow you to zoom in on a region of the plot by clicking with the left
button. Each click near a point magnifies the plot, keeping the center
at the point where you clicked. Holding the @kbd{Shift} key while
clicking, zooms out to the previous magnification.
@cindex Zoom

@item @dfn{Dragging}.  Holding the right mouse button down while the
cursor is moved, the plot can be moved sideways or up and down.
@cindex Dragging

@item @dfn{Save}. Can be used to save a copy of the plot in a Postscript
file.
@cindex Save

@item @dfn{Help}. Will show a short summary of the plot window options.
@cindex Help

@end itemize

@ifnotinfo
@image{figures/xmaximaplot,8cm}
@end ifnotinfo

By default, each plot will be opened in a new separate window. However,
the plot windows can be embedded into Xmaxima's text window, by
selecting the option @samp{Plot windows -> Embedded} in the
@command{Options} menu, before the plot command is issued.
@cindex Embedded

@ifnotinfo
@image{figures/xmaximaembedded,8cm}
@end ifnotinfo

The 3d plot has a menu very similar to that obtained with
@command{plot2d}, but with one additional option: @dfn{Rotate}. Normally,
if you click on the plot, it will not be enlarged, as the 2d
plots. Clicking on the left button, while dragging the mouse, will
rotate the plot, allowing to control two angles: azimuth and elevation.
@cindex Rotate

The menu option @samp{Zoom}, will change that default behavior, making
the mouse enlarge the plot, as in the 2d case. To return to the default
behavior (the mouse makes the plot rotate), the Rotate button should be
used.

If Xmaxima is executed from the command line, giving as argument the
name of a file, it will open that file and interpret it as a plot command,
with a syntax specific of Xmaxima. The graph generated by the commands
in the file will be plotted in a plot window, and the main window of
Xmaxima will not be opened and no communication with Maxima will be
established. An example of the contents of a file that can be passed
directly to Xmaxima is the following:

@example
plot2d -xfun "sin(A*x);cos(x)" -yradius 10
       -sliders @{A=1:6@} -parameters @{A=1@}
@end example

that file will generate a plot of a cosine function with fixed period,
and a sine function with a period that can be changed by moving the
slider that appears on the bottom.

@ifnotinfo
@image{figures/xmaximaslider,8cm}
@end ifnotinfo

the sliders option of xmaxima is one feature that cannot be accessed
directly from @command{plot2d} in Maxima. Other examples of input
files for xmaxima are the files @file{maxoutNNNN.xmaxima} (where NNNN
is the process id (an unique number) of the maxima process, that Maxima
creates; when Maxima is run from the command line, and a plotting
function that involves xmaxima is used, the data is not passed directly
to Xmaxima, but it is rather saved into that file and then xmaxima is
executed with the name of that file as argument.

The strings used in those files must be properly represented as Tcl/Tk
strings. 

@node The browser, Getting Help, Xmaxima plots, Top
@chapter The browser

Xmaxima's browser is a Web browser. It lacks many features available in
any modern browser, such as style-sheets and tables support. On the
other hand, that browser accepts two additional tags, which are not part
of HTML, but are very useful to pass commands to Xmaxima from the html
page.

One example of that is the Maxima Primer that appears in the browser when
Xmaxima starts. That primer has some fields where you can click to get
the result inside the browser window. The syntax of the two additional
tags is as follows

@example
<eval program=maxima doinsert=0>maxima_command</eval>
<eval program=maxima doinsert=1>command</eval>
<result modified>result</result>
@end example

The first form will highlight the given Maxima command, and when the user
double clicks on it, it will be evaluated, but its result will not be
inserted back into the original web page.

The second form will act similarly to the first, but the result from
Maxima will now be inserted back into the Web page, in the next tag
@samp{result} that appears in the page. The commands shown in the
@code{eval} tags can be edited and reenter.

Some more sample active pages can be found in
@url{https://web.archive.org/web/20190926040445/https://web.ma.utexas.edu/users/wfs/netmath/netmath.html}
 
@node Getting Help, Concept Index, The browser, Top
@chapter Getting Help

Xmaxima can be used to access Maxima's documentation in several
different forms. The @command{describe} of Maxima should work exactly
as it does in Maxima. The @code{Help} menu has a link to the local copy
of the manual, which is distributed with Maxima. In that menu there is
also a link to the Website of Maxima, where some other documentation can be
found.


@node Concept Index,  , Getting Help, Top
@unnumbered Concept Index

@printindex cp
@bye
