\input texinfo

@setfilename maplev
@settitle MapleV Emacs Mode @value{VERSION}

@set VERSION 2.27
@set DATE June 2011

@dircategory Emacs
@direntry
* MapleV: (maplev).       A GNU-Emacs mode for developing Maple code.
@end direntry


@include version.texi

@iftex
@tolerance 10000
@end iftex

@copying
MapleV is a GNU Emacs major mode for developing source code for @w{Maple}, 
a computer algebra system (CAS) marketed by @w{Waterloo Maple Inc}.
In this manual @dfn{MapleV} refers to the Emacs major mode and
@dfn{Maple} to the CAS.  MapleV is written entirely in Emacs-Lisp and is
distributed under the GNU General Public License.

This manual is for MapleV version @value{VERSION}.

Copyright @copyright{} 2011, Joseph S. Riel

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License.''
@end quotation
@end copying



@setchapternewpage on

@titlepage
@title MapleV
@subtitle A GNU Emacs Mode for Maple Developers
@subtitle For MapleV Version @value{VERSION}
@c @subtitle @value{UPDATED}
  
@author Joseph S.@ Riel
@page
@vskip 0pt plus 1filll
Maple is a registered trademarks of Waterloo Maple Inc.@*

Copyright @copyright{} 1999, 2010 Joseph S. Riel@*
 
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.

@end titlepage
@page


@ifnottex
@node top, Copying, (dir), (dir)
@top MapleV

@insertcopying
@end ifnottex

@menu
* Copying::                     Conditions for copying and changing MapleV.
* GNU Free Documentation License::  Copying this manual.
* Introduction::                A brief tour of MapleV's features.
* Basics::                      A few basics.

Editing

* Indentation::                 Indenting Maple code.
* Font Lock::                   Syntactic highlighting of Maple code.
* Comments::                    Command for adding and aligning comments.
* Shortcuts::                   Abbreviations and templates.
* Imenu support::               Creating a procedure index.
* Miscellaneous features::      Useful editing features

Processes

* Mint::                        Syntax checking.
* Maple::                       Running Maple as a standalone process.
* Help pages::                  Displaying Maple help pages.
* Procedures::                  Displaying procedures from the Maple libraries.

Appendices

* Installation::                Installing MapleV.
* Evolution::                   Credits, Bugs, Enhancements.

Indices

* Key Index::                   
* Function Index::              
* Variable Index::              

@detailmenu
 --- The Detailed Node Listing ---

Indentation

* Indentation Commands::        Commands for inserting and aligning comments.
* Customizing Indentation::     Variables that affect indentation.
* Indentation Tricks::          Forcing and preventing indentation.
* Indentation Details::         Overview of the indentation algorithm.

Indentation Tricks

* Forcing indentation::         Using parentheses to force indentation.
* Preventing indentation::      Using continued comments to prevent indentation.

Font Lock

* Decoration level::            Selecting the decoration level.
* Adding keywords::             Customizing the font lock patterns.
* Display faces::               Setting the display faces.

Shortcuts

* Abbreviations::               Abbreviations for common Maple functions.
* Templates::                   Inserting procedures and assignments.

Abbreviations

* Customizing Abbreviations::   

Miscellaneous features

* Include statements::          Active include statements

Mint

* Running mint::                Commands for sending code to Mint.
* Mint mode::                   Mode for viewing the output of Mint.

Maple

* Running Maple::               Commands for sending code to the Maple engine.
* Cmaple mode::                 Mode for interacting with Maple.

Help pages

* Displaying help pages::       Commands for displaying Maple help pages.
* MapleV help mode::            Mode for viewing Maple help pages.

Procedures

* Displaying procedures::       Commands to display Maple procedures.
* MapleV proc mode::            Mode for viewing Maple procedures.

Installation

* Compiling::                   Byte compiling MapleV.
* Customizing::                 Customizing the installation.
* Info documentation::          Installing the Info documentation.

Evolution

* Bugs::                        
* Acknowledgments::             
* Enhancements::                

@end detailmenu
@end menu

@node Copying, GNU Free Documentation License, top, top
@unnumbered Copying
@cindex Copying
@cindex Copyright
@cindex GPL
@cindex General Public License
@cindex License
@cindex Free
@cindex Free software
@cindex Distribution
@cindex Right
@cindex Warranty

The programs currently being distributed that relate to MapleV consist
of GNU Emacs Elisp files.  These programs are "free"; this means that
everyone is free to use them and free to redistribute them on a free
basis.  The MapleV-related programs are not in the public domain; they
are copyrighted and there are restrictions on their distribution, but
these restrictions are designed to permit everything that a good
cooperating citizen would want to do.  What is not allowed is to try to
prevent others from further sharing any version of these programs that
they might get from you.

Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to MapleV, that you receive
source code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of the MapleV related programs, you must give the recipients all
the rights that you have.  You must make sure that they, too, receive or
can get the source code.  And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to MapleV.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.

The precise conditions of the licenses for the programs currently
being distributed that relate to MapleV are found in the General Public
Licenses that accompany them.





@node GNU Free Documentation License, Introduction, Copying, top
@unnumbered GNU Free Documentation License
@include fdl.texi



@node Introduction, Basics, GNU Free Documentation License, top
@unnumbered Introduction
@cindex Introduction

@iftex
MapleV is a GNU Emacs major mode for developing source code for @w{Maple
V}, a computer algebra system (CAS) owned by @w{Waterloo Maple Inc}.  In
this manual @dfn{MapleV} refers to the Emacs major mode and @dfn{Maple}
to the CAS.  MapleV is written entirely in Emacs-Lisp and is distributed
under the GNU General Public License.
@end iftex

Following is a brief tour of MapleV's major features.

@heading Indentation

Maple source code is grammatically indented, either as you enter it or
all at once.  Customizable variables permit a limited control of the
indentation style.  The default settings produce a result that is very
close to the pretty printed output of Maple.

@heading Font Lock

Maple reserved words, special words, initial variables, builtin
functions, and top-level procedure assignments are font locked.
Comments and quotes are syntactically highlighted.  The amount of
``decoration'' can be customized.

@heading Comments

Commands are provided for inserting and aligning Maple comments.
Auto-filling can be enabled so that comments automatically wrap.

@heading Shortcuts

Abbreviations for common Maple words are defined and automatically
expanded, if enabled.  A blank procedure template, including your
copyright statement, can be inserted into the source.  It queries for
the name of the procedure, optional arguments, and a description.

@heading Mint interface

All or portions of the buffer can be sent to @code{mint}, Maple's syntax
checker.  The output is displayed in a buffer with a mode that
highlights and activates warnings and error messages.  Clicking on the
activated text either moves the cursor to the appropriate point in the
source code or queries to automatically correct the error.

@heading Maple interface

All or portions of the buffer can be sent to the command line version of
Maple, which is run in its own buffer.  You can work directly in that
buffer to exercise the source code.

@heading Online help

Help pages from Maple help databases can be called up and displayed in a
buffer.  The buffer has a mode that font locks section headings and
provides commands for viewing other help pages and recalling previously
visited pages.

@heading Library procedures

Procedures from Maple libraries can be displayed in a buffer.  They are
font locked the same as in a MapleV buffer.  Commands are
available for displaying other procedures and a history mechanism
provides a convenient means to return to previously displayed
procedures.

@heading Multiple Maple releases

At installation MapleV is configured to work with a default release of
Maple.  You may also specify alternate releases of Maple.  A MapleV
buffer can then be configured to work with a release different than the
default; it will access the versions of Maple and Mint appropriate for
the release.




@node Basics, Indentation, Introduction, top
@chapter Basics
@cindex Top-level procedures
@cindex Menubar

For MapleV to properly locate, fontify, and index @dfn{top-level
procedures}, that is, non-nested procedure assignments, the procedure
name @emph{must} be flush left.  Indenting the buffer moves top-level
procedures to the left margin.

There are a few exceptional cases in which what should be top-level
procedures are, in fact, not.  The primary example is a Maple script in
which procedures are conditionally assigned.  See @ref{Preventing
indentation}, for an illustration and a method to automatically indent
these procedures to the left column.

Most of the higher-level MapleV functions, those that do more than edit
text, are available on the menubar.




@node Indentation, Font Lock, Basics, top
@comment  node-name,  next,  previous,  up
@chapter Indentation
@cindex Indentation

Maple source code is indented according to its grammar.  The indentation
can occur either as you enter the code or all at once; the latter action
is useful when working with non-indented source code.  A grammatical
error, typically an out of place keyword or parenthesis, generates an
error and moves the cursor to the place where the error was detected.

@menu
* Indentation Commands::        Commands for inserting and aligning comments.
* Customizing Indentation::     Variables that affect indentation.
* Indentation Tricks::          Forcing and preventing indentation.
* Indentation Details::         Overview of the indentation algorithm.
@end menu


@node Indentation Commands, Customizing Indentation, Indentation, Indentation
@comment  node-name,  next,  previous,  up
@section Commands

@cindex Indentation commands
@cindex Commands, indentation

@kindex C-j
@kindex C-c @key{TAB} @key{TAB}
@kindex C-c @key{TAB} b
@kindex C-c @key{TAB} p
@kindex C-c @key{TAB} r

@findex maplev-electric-tab
@findex maplev-indent-newline
@findex maplev-indent-buffer
@findex maplev-indent-procedure
@findex maplev-indent-region

@table @kbd
@item @key{TAB}
Indent the current line (@code{maplev-electric-tab}).

@item C-j
Indent the current line, insert a new line, and indent that line
(@code{maplev-indent-newline}).

@item C-c @key{TAB} @key{TAB}
@itemx C-c @key{TAB} b
Indent the buffer (@code{maplev-indent-buffer}).

@item C-c @key{TAB} p
Indent a procedure (@code{maplev-indent-procedure}).

@item C-c @key{TAB} r
Indent the region (@code{maplev-indent-region}).

@end table


@node Customizing Indentation, Indentation Tricks, Indentation Commands, Indentation
@comment  node-name,  next,  previous,  up
@section Customizing
@cindex Customizing indentation
@cindex Indentation, customizing

The following variables affect indentation:

@vtable @code
@item maplev-indent-level
The amount a subblock is indented. The default is 4.

@item maplev-indent-declaration
The amount the Maple procedure declarations (@code{local},
@code{global}, @code{option}, and @code{description}) are indented.  The
default is 0.

@item maplev-dont-indent-re
A regex or nil.  If non-nil then lines that begin with a match are not
indented.  The default, @samp{"#"}, prevents flush left comment lines
from being indented.

@end vtable


@node Indentation Tricks, Indentation Details, Customizing Indentation, Indentation
@section Indentation Tricks

The indentation algorithm is not perfect.  It can fail to indent code
that should be indented or it may indent code that should not be
indented.  The following sections give examples and demonstrate workarounds.

@menu
* Forcing indentation::         Using parentheses to force indentation.
* Preventing indentation::      Using continued comments to prevent indentation.
@end menu


@node Forcing indentation, Preventing indentation, Indentation Tricks, Indentation Tricks
@subsection Forcing indentation
@cindex Forcing indentation
@cindex Indentation, forcing
@cindex Indenting continued expressions
@cindex Continued expression, indenting

MapleV's indentation algorithm does not (currently) handle continued
expressions.  It aligns continuations with the left most
character in the preceding line.  In an assignment it is preferable to
align with the right side of the assignment.  

@subsubheading Problem

Indenting the following code causes the continued line to be left
aligned with the preceding line, as the following illustrates:

@example
---------- Buffer: foo ----------
y := a + ( ... ) 
     + b;@point{}
---------- Buffer: foo ----------

@key{TAB}
   @result{}
---------- Buffer: foo ----------
y := a + ( ... ) 
+ b;@point{}
---------- Buffer: foo ----------        
@end example

@subsubheading Solution

Use extra parentheses to prevent the continuation line from being
aligned with the opening column:

@example
---------- Buffer: foo ----------
y := ( a + ( ... ) 
       + b );
---------- Buffer: foo ----------
@end example


@node Preventing indentation,  , Forcing indentation, Indentation Tricks
@subsection Preventing indentation

@subsubheading Problem

Consider an installation script in which the procedures @samp{foo1} and
@samp{foo2} are assigned only when the flag @code{assign_procs} is
@samp{true}.  The following example shows what happens when the buffer
is indented.

@example
@group
---------- Buffer: foo ----------
if assign_procs then
foo1 := proc() ... end:
foo2 := proc() ... end:
fi:
---------- Buffer: foo ----------

@kbd{M-x maplev-indent-buffer}
   @result{}
---------- Buffer: foo ----------
if assign_procs then
    foo1 := proc() ... end:
    foo2 := proc() ... end:
fi:
---------- Buffer: foo ----------
@end group
@end example


Because @code{foo1} and @code{foo2} are no longer flush left they are
not recognized as top-level procedures.  Their names are not properly
font locked and MapleV commands that operate on top-level procedures do
not work on them.

@subsubheading Solution

Because MapleV ignores comment continuations that Maple respects
(@ref{Comments}), we can use the following technique to prevent
@samp{foo1} and @samp{foo2} from being indented.

@example
@group
---------- Buffer: foo ----------
if assign_procs then       #\
fi                         # @r{Maple does not see this line}
foo1 := proc() ... end:
foo2 := proc() ... end:
#\
if then                    # @r{Maple does not see this line}
fi:
---------- Buffer: foo ----------
@end group
@end example

MapleV ignores the comment continuations and determines that each
@code{if} statement is completed on the following line.  The procedures
@code{foo1} and @code{foo2} are not indented.  Maple, however, continues
the comments and so matches the initial @code{if} to the final
@code{fi}; it ignores the dummy statements.




@node Indentation Details,  , Indentation Tricks, Indentation
@section Indentation Details
@cindex Indentation details
@cindex Details, indentations
@cindex Indentation grammar
@cindex Grammar, indentation
@cindex Indenting, speed of
@cindex Speed of, indenting

A grammar table (@code{maplev--grammar-alist}) defines the grammar
used to indent Maple code.

MapleV parses the source to compute the appropriate indentation for each
line.  To speed this process, information from the last parse is saved
and reused.  This method allows it to indent entire buffers reasonably
quickly; the largest file in the Maple R5 share library
(@file{gdev.mpl}, 160K, by Bruno Salvy) took twelve seconds to indent on
a PC running NTEmacs.  During editing, if the buffer is modified above
the last indentation location then the indentation information is lost;
consequently, you may occasionally notice small delays as the source is
reparsed.



@node Font Lock, Comments, Indentation, top
@chapter Font Lock
@cindex Font lock


@menu
* Decoration level::            Selecting the decoration level.
* Adding keywords::             Customizing the font lock patterns.
* Display faces::               Setting the display faces.
@end menu


@node Decoration level, Adding keywords, Font Lock, Font Lock
@section Decoration level
@cindex Font lock, decoration level
@cindex Decoration level, font lock
@cindex Maximum decoration, font lock

@vindex font-lock-maximum-decoration
@findex maplev-reset-font-lock

The amount of syntactical highlighting, or ``decoration'', is controlled
by the global variable @code{font-lock-maximum-decoration}, which you
may set in your @file{.emacs} file.  @inforef{Font Lock,,emacs}, for
information.  MapleV mode provides three levels of decoration:

@enumerate
@item 
Comments, quotes, top-level procedure names and Maple reserved works
are highlighted.

@item 
Everything in level 1 plus Maple special words, initial variables, and
the ditto operators are highlighted.

@item
Everything in level 2 plus Maple builtin functions are highlighted.

@end enumerate

Execute @kbd{M-x maplev-reset-font-lock @key{RET} LEVEL @key{RET}} or
use the menubar, @kbd{MapleV -> Setup -> Decoration}, to change the
decoration in a MapleV buffer.  @code{LEVEL} is an integer from 1 to 3.



@node Adding keywords, Display faces, Decoration level, Font Lock
@section Adding keywords
@cindex Font lock, adding keywords
@cindex Keywords, font locking
@cindex Customizing font lock keywords

You can use the usual method to add new keywords to font lock in MapleV
mode.  For example, the following snippet can be added to your
@file{.emacs} file to font lock @samp{simplify} and @samp{printf} in
MapleV mode.

@example
(font-lock-add-keywords 
 'maplev-mode
 '(("simplify" . maplev-font-special-word-face)
   ("printf"   . maplev-font-special-word-face)))
@end example


@node Display faces,  , Adding keywords, Font Lock
@section Display faces
@cindex Font lock, display faces
@cindex Font lock, faces
@cindex Faces, font lock
@cindex Display faces, font lock

@vtable @code
@item maplev-special-word-face
Display face used for Maple special words.  The special words are
@samp{args}, @samp{nargs}, @samp{procname}, @samp{RootOf} and
@samp{Float}.

@item maplev-initial-variable-face
Display face used for Maple initial variables.  These are
@samp{Catalan}, @samp{true}, @samp{false}, @samp{FAIL}, @samp{infinity},
@samp{Pi}, @samp{gamma}, @samp{integrate}, @samp{libname}, @samp{NULL},
@samp{Order}, @samp{printlevel}, and @samp{lasterror}.

@end vtable



@node Comments, Shortcuts, Font Lock, top
@chapter Comments

@cindex Comments

@kindex M-;
@kindex C-x ;
@kindex C-u - C-x ;
@kindex M-q

@findex indent-for-comment
@findex set-comment-column
@findex kill-comment
@findex fill-paragraph

@vindex comment-column
@vindex fill-column


MapleV uses standard Emacs commands to enter, align and fill Maple
comments.  @inforef{Comments,,emacs}. The commands are reproduced here
for convenience.

@table @kbd
@item M-; 
Insert or align an inline comment (@code{indent-for-comment}).  The
comment character is inserted at column @code{comment-column}.

@item C-x ;
Set comment column (@code{set-comment-column}).

@item C-u - C-x ;
Kill comment on current line (@code{kill-comment }).

@item M-q
Fill a comment (@code{fill-paragraph}).  Wrap lines at column
@code{fill-column} and insert new comment characters, aligned with the
original comment character.

@end table

The following variables affect comments:

@vtable @code
@item maplev-auto-fill-comment-flag
A boolean flag. If non-nil, the default, comment lines wrap as they are
typed.  Wrapping, however, does not automatically start in an inline
comment; it must be invoked with @code{fill-paragraph}.

@item maplev-comment-string
String variable inserted by @code{indent-for-comment}.
The default is @samp{# }.

@item maplev-comment-column
Initial value of @code{comment-column}.  The default is 40.

@item maplev-comment-fill-column
Initial value of @code{fill-column}.  The default is 79.

@end vtable

Maple comment lines can be continued to the next line by ending them
with a backslash.  MapleV does @emph{not} recognize this continuation
and interprets the following line as code.  This can fool the MapleV
indentation grammar; however, it can also be used to achieve certain
effects.  @xref{Preventing indentation}, for an example.


@node Shortcuts, Imenu support, Comments, top
@chapter Shortcuts
@cindex Shortcuts

@menu
* Abbreviations::               Abbreviations for common Maple functions.
* Templates::                   Inserting procedures and assignments.
@end menu


@node Abbreviations, Templates, Shortcuts, Shortcuts
@section Abbreviations
@cindex Abbreviations
@cindex Custom abbreviations

Abbreviations are available for common or lengthy Maple keywords. They
are expanded whenever @code{abbrev-mode} is active.
@inforef{Abbrevs,,emacs}. The command @code{maplev-abbrev-help} displays
a list of the available abbreviations.

The following variables affect the expansion of abbreviations:

@table @code
@item maplev-initial-abbrev-mode-flag
If non-nil @code{abbrev-mode} is activated when MapleV is started.  The
default is @samp{t}.

@item maplev-expand-abbrevs-in-comments-and-strings-flag
If non-nil then the Maple abbreviations are expanded in comments and
strings. The default is @samp{nil}.

@end table

@menu
* Customizing Abbreviations::   
@end menu




@node Customizing Abbreviations,  , Abbreviations, Abbreviations
@subsection Customizing Abbreviations

The predefined MapleV abbreviations are stored in the abbreviation table
@code{maplev-mode-abbrev-table}.  The following code may be added to
your @file{.emacs} file to assign @samp{simp} as an abbreviation for
@samp{simplify}.

@example
(define-abbrev maplev-mode-abbrev-table 
        "simp" "simplify" 'maplev--abbrev-hook)
@end example

The function @samp{'maplev--abbrev-hook} prevents the abbreviation from
being expanded inside a comment or quote.

To remove an abbreviation from the table assign it @code{nil}.  For
example, to prevent @samp{lib} from expanding to @samp{libname}, add the
following to @file{emacs}:

@example
(define-abbrev maplev-mode-abbrev-table "lib" nil nil)
@end example




@node Templates,  , Abbreviations, Shortcuts
@section Templates
@cindex Templates
@cindex Procedure template
@cindex Template, procedure
@cindex Assignment operator, template

@kindex C-c C-p
@kindex C-;

@findex maplev-proc-template
@findex maplev-insert-assignment-operator

@table @kbd
@item C-c C-p
Insert a procedure template (@code{maplev-proc-template}).  The user is
queried for the name, arguments, and a description of the procedure.
Any of the entries can be left blank.  If the name is blank then an
anonymous procedure is inserted, otherwise an assignment is inserted
with the procedure assigned to the given name.  Backquotes are added
automatically to procedure names if required by Maple.

@item C-;
Insert an assignment operator at the end of the current line
(@code{maplev-insert-assignment-operator}).

@end table


The following variables affect the shortcuts:

@vtable @code
@item maplev-insert-copyright-flag
If non-nil then a copyright notice is inserted in the @code{option}
declaration of the procedure template.  The default is @code{t}.

@item maplev-copyright-owner
String inserted as the copyright owner.

@item maplev-comment-end-flag
If non-nil then the name of the procedure is inserted as a comment to
the right of the closing @code{end} statement.

@item maplev-assignment-operator
The string inserted by @code{maplev-insert-assignment-operator}.
The default value is @samp{ := }.

@end vtable



@node Imenu support, Miscellaneous features, Shortcuts, top
@chapter Imenu support
@cindex Imenu
@cindex Index, procedures
@cindex Procedure index

@findex maplev-add-imenu

Executing @kbd{maplev-add-imenu} or selecting @kbd{MapleV -> Add Index}
from the menubar creates an indexed menu of the top-level Maple
procedures, global variables, and macro assignments.  The menu appears
under the @samp{Index} heading in the menubar.  Clicking on an item in
the menu moves point to the assignment of that item.

The assignments must be flush left to be indexed.
Only the first macro in a @code{macro} assignment is indexed.

@node Miscellaneous features, Mint, Imenu support, top
@comment  node-name,  next,  previous,  up
@chapter Miscellaneous features
@cindex Miscellaneous

@menu
* Include statements::          Active include statements
@end menu

@node Include statements,  , Miscellaneous features, Miscellaneous features
@section Include statements
@cindex Include

@findex maplev-find-include-file-at-point
Maple include statements, such as @code{$include <somefile>},
are font-locked and active.  
Clicking on them, or typing @kbd{C-c C-o},
calls @kbd{maplev-find-include-file-at-point},
which searches for the file and, if successful, opens it.
If the path exists, but the file does not, the user is
asked whether to create the file.  

@vindex maplev-include-path
The include path can be
assigned, as a list of strings, to the variable @kbd{maplev-include-path}.
The paths are searched in the order of occurrence in the list.

@vindex maplev-include-file-other-window-flag
The customizable variable @kbd{maplev-include-file-other-window-flag}
determines whether the file is opened in the current window or 
another window.

@node Mint, Maple, Miscellaneous features, top
@chapter Mint
@cindex Mint
@cindex Syntax checking
@cindex Checking syntax

Mint is Maple's syntax checker. It analyzes a Maple program and produces
a report about the syntax and variable usage.  MapleV can run mint on
the entire buffer or a portion of it.  The output of mint is displayed
in a buffer with a special mode, @code{mint-mode}, that provides a
convenient means for locating and correcting syntax errors.

@menu
* Running mint::                Commands for sending code to Mint.
* Mint mode::                   Mode for viewing the output of Mint.
@end menu


@node Running mint, Mint mode, Mint, Mint
@section Running mint
@cindex Running mint
@cindex Mint, running

@kindex C-c @key{RET} b
@kindex C-c @key{RET} p
@kindex C-c @key{RET} r
@kindex C-c @key{RET} @key{RET}

@findex mint-buffer
@findex mint-procedure
@findex mint-region
@findex mint-rerun

The following commands send source code in the buffer to Mint:

@table @kbd
@item C-c @key{RET} b
Run Mint on the buffer (@code{mint-buffer}).

@item C-c @key{RET} p
Run Mint on the current procedure (@code{mint-procedure}).

@item C-c @key{RET} r
Run Mint on the marked region (@code{mint-region}).

@item C-c @key{RET} @key{RET}
Rerun the previous Mint command (@code{mint-rerun}).

@end table

These commands are available through the menubar, @kbd{MapleV -> Mint}.
The following variables affect the output of Mint:

@vtable @code
@item mint-info-level
An integer from 0 to 4 that selects the amount of information displayed
by Mint.  0 displays no information, 4 displays the most.  The default
value is 3.  This value can be set through the menubar,
@kbd{Maplev -> Mint -> Mint level}.

@item mint-start-options
A string passed to Mint at startup.  The default is @samp{"-q"}, which
suppresses the display of the Maple logo.  Type @kbd{?mint} in Maple for
other options.

@item mint-coding-system
Symbol that defines the coding system used by Mint.  The default value
is @code{undecided-dos}.

@end vtable


@node Mint mode,  , Running mint, Mint
@section Mint mode
@cindex Mint mode
@cindex Mode, Mint

Mint mode is applied to mint's output buffer.  Warnings and errors are
font locked and activated.  Moving the mouse pointer over active text
highlights it; clicking it (@kbd{mouse-2}) either moves the cursor to
the appropriate point in the source code or queries to automatically
correct an error.

The following commands are available:

@table @kbd
@item s
Incremental forward search (@code{isearch-forward}).

@item r
Incremental backward search (@code{isearch-backward}).

@item @key{RET}
Re-execute the previous mint command (@code{mint-rerun}).

@item @key{DEL}
Scroll down (@code{scroll-down}).

@item @key{SPC}
Scroll up (@code{scroll-up}).

@item mouse-2
Goto location in source, or fix error, depending on the active text.

@end table

The following variables set the display faces for the highlighted text in the
Mint buffer:

@vtable @code
@item mint-proc-face
Face for procedure names.

@item mint-warning-face
Face for warnings.

@item mint-error-face
Face for errors.

@item mint-note-face
Face for notes (usually @samp{on line}).

@end vtable



@node Maple, Help pages, Mint, top
@chapter Maple
@cindex Cmaple
@cindex Maple, command line

The command line version of Maple can be started in a buffer.  All or
portions of the code in the MapleV buffer can be passed directly to the
Maple process.  Maple commands can be directly executed in the buffer.

@menu
* Running Maple::               Commands for sending code to the Maple engine.
* Cmaple mode::                 Mode for interacting with Maple.
@end menu


@node Running Maple, Cmaple mode, Maple, Maple
@section Running Maple
@cindex Cmaple, running
@cindex Running, Cmaple

@kindex C-c C-c b
@kindex C-c C-c p
@kindex C-c C-c r
@kindex C-c C-c g
@kindex C-c C-c i
@kindex C-c C-c k

@findex cmaplev-send-buffer
@findex cmaplev-send-procedure
@findex cmaplev-send-region
@findex cmaplev-goto-buffer
@findex cmaplev-interrupt
@findex cmaplev-kill

The following commands in the MapleV buffer affect the Maple engine:

@table @kbd
@itemx C-c C-c b
Send the entire buffer to the Maple engine (@code{cmaplev-send-buffer}).

@item C-c C-c p
Send the current procedure to the Maple engine
(@code{cmaplev-send-procedure}).

@item C-c C-c r
Send the marked region to the Maple engine (@code{cmaplev-send-region}).

@item C-c C-c g
Goto the Maple buffer (@code{cmaplev-goto-buffer}).

@item C-c C-c i
Interrupt the Maple engine (@code{cmaplev-interrupt}).

@item C-c C-c k
Kill the Maple engine (@code{cmaplev-kill}).

@end table

These commands are available through the menubar, @kbd{MapleV -> Maple}.


@node Cmaple mode,  , Running Maple, Maple
@section Cmaple mode
@cindex Cmaple mode
@cindex Mode, cmaple

The command line version of Maple is run in a buffer with the mode
@code{cmaple-process-mode} that is based on @code{comint-mode}.
@inforef{Shell Mode,,emacs} for more information.
In addition to the normal @code{comint} commands, the following commands
are available:

@table @kbd
@item ?
@itemx C-?
Display a Maple help topic (@pxref{Help pages}).

@item M-?
Display a Maple procedure (@pxref{Procedures}).

@end table



@node Help pages, Procedures, Maple, top
@chapter Help pages
@cindex Help pages, Maple
@cindex Maple help pages

Help pages can be read from the Maple help databases and displayed in a
buffer with major mode @code{maplev-help-mode}.  Text in the buffer is
highlighted and cross references are activated.

@menu
* Displaying help pages::       Commands for displaying Maple help pages.
* MapleV help mode::            Mode for viewing Maple help pages.
@end menu


@node Displaying help pages, MapleV help mode, Help pages, Help pages
@section Displaying help pages

@kindex C-?
@kindex S-mouse-2

@findex maplev-help-at-point
@findex maplev-help-follow-mouse

The following commands display Maple help pages:

@table @kbd
@item C-?
Query for a help topic, using the word at point as a default.  Display
the help page in a buffer (@code{maplev-help-at-point}).

@item S-mouse-2
Display the Maple help page for the topic at the click
(@code{maplev-help-follow-mouse}).

@end table

Help pages are displayed in a buffer with major mode
@code{maplev-help-mode}.
@ifinfo 
@xref{MapleV help mode}.
@end ifinfo


@node MapleV help mode,  , Displaying help pages, Help pages
@section MapleV help mode
@cindex MapleV help mode
@cindex Mode, help, MapleV
@cindex History, help mode

@findex maplev-help-mode
@findex maplev-clear-history

The major mode @code{maplev-help-mode} is active in the buffer that
displays Maple help pages.  Section headers are font locked and text in
the @samp{See Also} section is activated so that clicking on it opens
the help page for the topic.  The following commands are available:

@kindex s
@kindex p
@kindex n
@kindex P
@kindex r
@kindex ?

@table @kbd
@item s
Incremental forward search (@code{isearch-forward}).

@item p
Previous help topic (@code{maplev-prev-item}).

@item n
Next help topic (@code{maplev-next-item}).

@item P
Parent help topic (@code{maplev-help-parent}).

@item r
Redraw help page (@code{maple-redo-item}).

@item ?
@itemx C-?
@itemx @key{RTN}
Query for a help topic (@code{maplev-help-at-point}).

@item M-?
Query for a procedure (@code{maplev-proc-at-point}).

@item @key{SPC}
Scroll down.

@item @key{DEL}
Scroll up.

@end table

MapleV help mode keeps a history of the help topics displayed.
Use the command @code{maplev-clear-history} to erase the history.

The help page for a chosen topic is displayed by sending the string
@samp{?TOPIC} to the Maple engine and capturing the output.  If the
Maple engine is busy an error message, @samp{Maple busy}, is displayed in
the message window.  



@node Procedures, Installation, Help pages, top
@chapter Procedures
@cindex Procedures, Maple
@cindex Maple, procedures
@cindex Displaying Maple procedures

Procedures can be read from the active Maple libraries and displayed in
a buffer with major mode @code{maplev-proc-mode}. The code is font
locked the same as in MapleV mode.

@menu
* Displaying procedures::       Commands to display Maple procedures.
* MapleV proc mode::            Mode for viewing Maple procedures.
@end menu


@node Displaying procedures, MapleV proc mode, Procedures, Procedures
@section Displaying procedures
@kindex M-?
@kindex M-S-mouse-2

@findex maplev-proc-at-point
@findex maplev-proc-follow-point

The following commands display Maple procedures:

@table @kbd
@item M-?
Query for a procedure name, using the word at point as the default.
Read the procedure from the Maple library and display it in a buffer
(@code{maplev-proc-at-point}).

@item M-S-mouse-2
Read the procedure at the click from the library and display it in a
buffer (@code{maplev-proc-follow-point}).

@end table

Procedures are displayed in a buffer with major mode
@code{maplev-proc-mode}.
@ifinfo
@xref{MapleV proc mode}.
@end ifinfo


@node MapleV proc mode,  , Displaying procedures, Procedures
@section MapleV proc mode
@cindex MapleV proc mode
@cindex Mode, proc, MapleV
@cindex History, proc mode

@findex maplev-proc-mode
The major mode @code{maplev-proc-mode} is active in the buffer that
displays Maple procedures read from a Maple library.  It font locks the
procedure, highlighting keywords the same as MapleV mode does.  Clicking
on procedure names in the buffer displays their source code or opens a
help page for them.  A history mechanism stores the previously displayed
procedure.

The following commands are available:

@table @kbd
@item s
Incremental forward search (@code{isearch-forward}).

@item p
Previous procedure (@code{maplev-prev-item}).

@item n
Next procedure (@code{maplev-next-item}).

@item r
Redraw procedure (@code{maple-redo-item}).

@item ?
@itemx C-?
@itemx @key{RTN}
Query for a help topic (@code{maplev-help-at-point}).

@item M-?
Query for a procedure (@code{maplev-proc-at-point}).

@item @key{SPC}
Scroll down.

@item @key{DEL}
Scroll up.

@end table

MapleV help mode keeps a history of the help topics displayed.
Use the command @code{maplev-clear-history} to erase the history.

A procedure is read from a library and displayed by using the Maple
procedure @samp{maplev_print} that is assigned when the Maple engine is
started.  If the Maple engine is busy an error message, @samp{Maple
busy}, is displayed in the message window.



@c Appendices


@node Installation, Evolution, Procedures, top
@appendix Installation

@cindex Installation
@cindex @file{.emacs}
@cindex Initialization
@cindex Customization

This section describes how to install MapleV into GNU Emacs.

@menu
* Compiling::                   Byte compiling MapleV.
* Customizing::                 Customizing the installation.
* Info documentation::          Installing the Info documentation.
@end menu



@node Compiling, Customizing, Installation, Installation
@section Compiling

Move the file @file{maplev.el} into your Emacs load path and byte
compile it as shown below:

@example
@kbd{M-x byte-compile-file} @key{RET} maplev.el @key{RET}
@end example

Add the following line to your @file{.emacs} file:

@example
(autoload 'maplev-mode "maplev" "Maple editing mode" t)
@end example

To have Emacs auto-magically start in MapleV mode when editing Maple
source, add the following to your @file{.emacs} file, modifying the
regex @file{.mpl} to an extension appropriate for your usage:

@example
(setq auto-mode-alist 
      (cons `("\\.mpl\\'" . maplev-mode) auto-mode-alist))
@end example


@node Customizing, Info documentation, Compiling, Installation
@section Customizing

You must customize some of MapleV's default settings to be appropriate
for your installation.  Most significantly, you must specify the
locations of the executable files for mint and the command line version
of Maple.  You can specify multiple versions of mint and Maple.  The
easiest method is to invoke @code{customize} using the following
commands:

@example
M-x load-library @key{RET} maplev @key{RET}
M-x customize-group @key{RET} maplev @key{RET}
@end example

The important options are in the subgroup @code{maplev-important}.
After setting these options, save them to your @file{.emacs} file by
clicking on the @samp{Save for Future Sessions} button.


@node Info documentation,  , Customizing, Installation
@section Info documentation

To create the Info documentation for MapleV, convert the TeXinfo
file @file{maplev.texi} to an Info file.  You may use either the
stand-alone utility @code{makeinfo} or, from inside Emacs, the command
@code{makeinfo-buffer}.

Move the output file @file{maplev} to a directory in the Info
load path and then edit the @file{dir} file, that is,
the top level node of your Emacs Info structure, to point to 
@file{maplev}.  I added the following menu item to my @file{dir} file:

@example
* MapleV: (maplev).       MapleV reference manual.
@end example




@node Evolution, Key Index, Installation, top
@appendix Evolution


@menu
* Bugs::                        
* Acknowledgments::             
* Enhancements::                
@end menu

@node Bugs, Acknowledgments, Evolution, Evolution
@section Bugs

If you encounter a bug in this package, wish to suggest an enhancement,
or want to make a smart remark, then send an email to me, the humble
developer.

   Joseph S. Riel (Joe Riel) @samp{joer@@k-online.com}


@node Acknowledgments, Enhancements, Bugs, Evolution
@section Acknowledgements
@cindex Acknowledgements
@cindex Credits
@cindex Gap mode

I'd like to thank a number of people who have contributed, either
directly or indirectly, to this package.


@table @b
@item Bruno Salvy
For writing @code{maple-mode}, a small but useful Emacs
mode for editing Maple code.

@item Michael Smith
For writing @code{Gap-mode} and @code{Gap-process}.
These gave me the idea, and showed me how, to display help pages.
Displaying source code from the Maple libraries was a natural extension.
@code{Gap} is a CAS specialized for group theory.

@item Nicholas Thi@'ery
For writing @code{Maple-mode}, another Emacs mode for
editing Maple code.  It introduced the idea of using a grammar to indent
Maple source code.

@item Bob Glickstein
For writing @cite{Writing GNU Emacs Extensions}.
It allowed me, a novice Elisp programmer, to put it all together.

@item Christian Pomar
For courageously agreeing to test a series of alpha
versions of this package.  He found numerous errors and suggested many
improvements.

@end table


@node Enhancements,  , Acknowledgments, Evolution
@section Enhancements
@cindex Enhancements
@cindex Debugger, source code
@cindex Code debugger
@cindex LaTeX 
@cindex MapleDoc

The following is a short list of features that I am tentatively planning
to add to MapleV.

@itemize @bullet
@item
Source code debugger.  The Maple debugger @code{DEBUG} provides a useful
means to step through code; its interface, however, leaves much to be
desired.  A more convenient interface would be similar to that of
@code{Edebug}, the Emacs-Lisp source code debugger.

@item
La@TeX{} support.  I use MapleDoc, a La@TeX{} macro package that I wrote,
for documenting Maple source code.  To facilitate its use MapleV should
be able to font-lock La@TeX{} keywords in comments.  This will be an
optional package.

@end itemize




@node Key Index, Function Index, Evolution, top
@comment    node-name,         next,       previous, up
@unnumbered Key Index

@printindex ky

@node Function Index, Variable Index, Key Index, top
@comment    node-name,         next,       previous, up
@unnumbered Function Index

@printindex fn

@node Variable Index,  , Function Index, top
@comment    node-name,         next,       previous, up
@unnumbered Variable Index

@printindex vr

@printindex cp

@summarycontents
@contents
@bye

