######################################################################## ## INFO INFO INFO INFO INFO INFO INFO INFO INFO INFO INFO ## ######################################################################## PACKAGE: mupad.el [based on maple.el] CONTENTS: A MuPAD programming mode for emacs MAINTAINER: Olivier Ramare INSTALLED: 27.03.1998 VERSION: 1.26 Last Modified: 29-Marsh-1999 by Olivier Ramare. Purpose of this package ----------------------- If you want to do more than computing single statements with MuPAD, e.g. writing whole programs for it, then mupad.el is for you. The package is a plugin for notorious text editor emacs. It makes writing MuPAD-programs more comfortable by providing - different windows for writing (input) and running (output) programs which we shall most often call scripts. - standard editing-features of emacs, including such important features like auto-save and highlighting some chosen patterns. mupad.el was originally converted from maple.el and modified with the help of Henning von Bargen, Jürgen Billing, Michel Quercia, Nicolas Thiery, Winfried Trümper, Olivier Ramare and Paul Zimmermann. It now also incorporates a good deal of pari.el as well as genuinely mupad-specific functions. A Rapid Installation -------------------- We describe rapidly how to set this package in use so that you may follow the description of this file through some examples. The file 'mupad.el' has to be copied in a directory, where "emacs" is aware of it (ask your sys-admin for that); an appreciate place could be /usr/local/lib/emacs/site-lisp/ or /etc/site-lisp/ After that, you should add some lines in one of the files ~/.emacs (personal configuration) or /usr/lib/emacs/site-lisp/site-start.el (global configuration): this is the files emacs tries to read whenever starting a session. Then you should set the path to the utility files for MuPAD first. Two such pathes are required, a general one and a particular one used for vcam. By default, the general one is set to "/usr/local/MuPAD-1.4.0/share/" but this will probably not reflect your setup. This address is used for: (1) Getting examples in the subdirectories "examples/" and "demo/". (2) Installing the Hytex manual from the subdirectories "../bin/" (executable "hypage") (which by default is supposed to be in "/usr/local/MuPAD-1.4.0/bin/") and "doc/hytex/" (file "man_eng"). The particular path is used to find the graphical interface vcam (executable "vcam"). In MuPAD-1.4.0, it was "/usr/local/MuPAD-1.4.0/bin/" but in MuPAD-1.4.1, it appears to be "/usr/local/MuPAD-1.4.0/share/bin/". Here is the part to insert: ----- 8< ----- cut here ----- 8< ----- ;; The following variable decides where "MuPAD utilities" is to be found: (setq mupad-mode-hook (function (lambda nil (setq mupad-directory "/usr/local/MuPAD-1.4.0/share/") (setq mupad-vcam-directory "/usr/local/MuPAD-1.4.0/bin"))) ----- 8< ----- cut here ----- 8< ----- where you should of course replace "/usr/local/MuPAD-1.4.0/share/" by the proper one ... We shall describe later several other variables that can be modified in this hook. After that, in this same file, you should add the following lines: ----- 8< ----- cut here ----- 8< ----- (autoload 'mupad-mode "mupad" "MuPAD editing mode" t) (setq auto-mode-alist (cons '("\\.mu$" . mupad-mode) auto-mode-alist)) ----- 8< ----- cut here ----- 8< ----- As a result, all files ending with .mu are recognized as MuPAD-files and emacs will automagically switch into MuPAD-mode. The symbol MuPAD-mode is an alias for mupad-mode. Some user may prefer the .MU suffix, and it is easily fixed above. Main Features ------------- This package provides the definition of two major-modes, namely 'mupad-mode for editing scripts and 'mupad-shell-mode for running a mupad-process. Here is a summary of what these modes do: (1) Editing MuPAD script: Automatic indentation. Automatic braces. Universal closing of constructs (via "ctrl-c ctrl-e"). Ready-made shapes (like while-, for- or if- contructs). Commenting/Excluding areas. (2) Colouring MuPAD scripts. Several structures are recognised and coloured. They are: Comments (starting by "//", enclosed in "#"--"#", enclosed in "/*"--"*/"). Strings. Keywords (like "and", "begin" or "Fail"; Also "&" followed by some word). Options. Domains (like "AxiomConstructor" or "groebner") Function-names (user defined ones). Global-variable-names (not yet done). Types (all starting with "DOM_"). Info (starting with "userinfo("). Primitive-names. (3) Rewriting MuPAD scripts. According to the output of the "expose" function of MuPAD. Some problems are still pending, like the fact that comments are altogether removed. It is in fact quite a problem to know where to place them. (4) Editing a running session of MuPAD. A [tcsh] shell is started. You can write your input over several lines (by using the "meta-return" or "ctrl-j" to get a newline) and some other minor (but useful) commands described below. (5) Colouring a running session of MuPAD. Several structures are recognised and coloured. They are: Prompts (the two of them ">>" and "&>"). Inputs. (6) Getting help in three forms: Asking for a command name (can be a user's definition provided such a definition has been fed to the MuPAD process). For simplicity of maintenance, this help goes through MuPAD, and thus will not be available if it is not possible to start a MuPAD process. Starting the Hytex manual. Scanning inputs and outputs and trying to mend what is wrong. At this moment, it starts Vcam when MuPAD answers it cannot do it itself, extends the completion system whenever an export command is found and takes care of inserted eLisp commands. (7) Completion mecanism: All the standard command names of MuPAD can be used for completion. Like for the help-mechanism, this one goes through a mupad-process at the beginning. See the corresponding section below. (8) Inserting some eLisp commands into a MuPAD script. An extremely powerful feature, but more will be said about it later. Usage ----- The version of emacs for X11 has a menu entry, which lists most of the features of the new mode. Keys/functions available in mupad-mode: --------------------------------------- We added to this list some key bindings that are not defined in pari.el but are available since the corresponding packages are loaded by pari.el. The prefix "C-" means you should keep the Control key pressed and press on the following key: "C-g" means press the Control key and the g key simultaneously. RET is the return-enter key. The prefix "M-" stands for the meta-character which is usually denoted "Alt"(eration): use this key like the "C-" one. In case, you do not have such a key, you can use ESC (the escape key) which you should *release* before typing the next character. To access a function without resorting to its shortname (well it may have none like mupad-exclude-area), you can use either the menu-bar where this item are recalled, either type in this case: M-x mupad-exclude-area followed by RET. This is for instance the only way to set a buffer in mupad-mode if it has not been done magically. If you do so, you may have to use "C-l" to rehighlit the buffer properly. As it turns out, some other commands are available, but they depend on each installation and are easily got through the menu-bar: they are commands for getting examples and changing the colors. KEY eLisp-name Brief Description --- ---------- ----------------- C-c p mupad-proc proc-construct. C-c l mupad-local Add a local variable in a proc definition. C-c e mupad-else Add an elif clause, but if the clause is empty add an else. C-c w mupad-while while-construct. C-c f mupad-for for-construct. C-c F mupad-fun-to-proc Converts a fun definition into a (()->(...)). Point should be after the fun definition C-c m mupad-modify Format to add informations at the top of the script about modifications you made. C-c t mupad-title Provides a header to your script. C-c C-e mupad-close-statement Closes automatically for- while- if- and proc- constructs. M-p mupad-backward-to-same-indent Finds the beginning of the previous line that has a similar indentation as this one. M-n mupad-forward-to-same-indent Similar as M-p except that the search is done forward. C-> mupad-indent-region Indent a whole marked region without breaking relative indentation. Basic size for indentation is 'mupad-indent-level. C-< mupad-unindent-region Process reverse to C->. C-c C-c comment-region Comments out a whole marked region. C-u C-c C-c C-u comment-region Uncomments a whole marked region. M-* mupad-star-comment Comments out a whole marked region using c-style comments. mupad-display-comment Inserts ## for a large comment. mupad-exclude-area Yet another way to comment out a whole region. RET mupad-electric-auto-terminate-line Inserts a newline and redoes the indentation. It is quite magical ! M-RET newline Inserts a newline, but emacs will *not* redo the indentation. TAB mupad-electric-tab Tabulation character. DEL backward-delete-char-untabify Removes the TAB introduced. M-l mupad-force-update Updates locally the highlighting of your script. C-l hilit-recenter Updates the highlighting of your buffer. C-u C-l C-u hilit-recenter Updates the highlighting of the whole buffer however long it may be. mupad-save-colors Saves your choice of colors in a file mupad-colors.el described later. mupad-hilit-switch Dis/En-ables highlighting. mupad-update-hilit-buffers Rehighlights the buffers that are in mupad-mode or in mupad-shell-mode. mupad-rewrite-region The marked region should be a proc definition. It is rewritten in a `beautiful' way, though comment will disappear. Useful after severe messy modifications. mupad-rewrite-all Applies mupad-rewrite-region to all the proc definitions of the script. mupad-expose-who Gives a description of a proc. Try it with the argument "linopt::minimize" for instance. M-o mupad-restore-wind-conf Emacs will quite often split your window to present some help. When you want to get rid of this window, the general (and global) key M-o strives to restore the previous setting. You may have to repeat the operation once or twice (at most ... 19 times !). C-c C-k mupad-kill-job Kills an existing mupad-process. mupad-start Starts a mupad-process. mupad-file Sends "read(my-file):" to a mupad-process where "my-file" is the argument you give. Like always a mupad-process is created if required. Note the final ":" which means that errors will *not* be explained (though the program ay have some output). In the menu-bar, it is called [Run MuPAD on file... / Silently]. mupad-execute-file Similar to the preceding but with a final ";". In the menu-bar, it is called [Run MuPAD on file... / Silently]. The advantage on this way of doing is that error messages are more helpful than with a final ":". mupad-start-hytex-manual Starts the HyTeX manual like with xmupad. mupad-start-vcam Starts vcam. mupad-mdx A debugger. mupad-set-digits Sends "DIGITS=what-you-want" to the mupad-process. mupad-set-prettyprint-switch Turns the prettyprinter ON/OFF. mupad-adapt-textwidth Tells mupad about the width of this window. You should use this function if you have modified the window width since the mupad- process has been started. mupad-mode Makes mupad-mode the major-mode of this buffer. M-i mupad-complete Emacs will try to complete the word under the cursor and display all possible completions if more than one are possible that do not have any common kernel. Otherwise this common part is inserted. C-i/TAB mupad-electric-tab (Rather) Intelligent tabulation character. C-c h mupad-help Like under the mupad-process, except that the help is displayed on a separate window. Keys available in mupad-shell-mode: ----------------------------------- mupad-shell-mode is the mode used for running a mupad-process. All the functions above are available but *not all * their key bindings ! In particular, completion goes through C-i/TAB also, though the M-i is still valid. Very few keys have been defined in this mode: KEY eLisp-name Brief Description --- ---------- ----------------- C-c C-c mupad-interrupt Same as in mupad-mode. C-c C-k mupad-kill-job Same as in mupad-mode. M-l mupad-force-update-hilit Same as in mupad-mode. C-c C-l mupad-recenter-output-buffer Does what is says. RET mupad-send-input If it is the last input and it is a complete one, sends it to mupad, else warns you and does nothing. If it is not the last input, copy the input surrounding the point to the end of the buffer and sends it to the mupad-process. M-RET mupad-C-j Inserts a newline without sending the partial input to the mupad-process. C-j mupad-C-j Same as above. M-c mupad-copy-input Copies input surrounding point to the end of the buffer but does not send it to the mupad-process, so that it may be edited. M-i mupad-complete Same as in mupad-mode. C-c h mupad-help Same as in mupad-mode. [up] mupad-history-recall-previous Applies to the arrow [up]. The previous command line fed to MuPAD is inserted at point, and up to 20 commands are stored. This behaviour (similar to the way the arrows work on a [t]csh shell) can be disabled via the boolean mupad-shell-historyp (see the HOOK part). [down] mupad-history-recall-next Applies to the arrow [down]. Reverse command to the previous one. The next five keys are a bit special: C-c T mupad-toggle-previous-next-behaviour C-n mupad-next-input / next-line C-p mupad-previous-input / previous-line M-n next-line / mupad-next-input C-p previous-line / mupad-previous-input Initially the usual C-n/C-p look for the next/previous input and M-n/M-p for the next/previous line. C-c T is a switch between these two sets, and will exchange them. ############################################## # THE LOCKED SEMI-MODE IN MUPAD-SHELL-MODE # ############################################## In 'mupad-shell-mode, the usual behaviour is the following: if you enter some character on a line which is *not* the line for the last input, emacs will not modify the line on which you type, but copy this whole input to the end of the buffer with the proper character inserted. This is so is 'mupad-lock-shell-modep is set to t in 'mupad-mode-hook (see below). Otherwise, your character will simply be inserted normally. This variable can be modified in 'mupad-shell-mode via the menu-bar item [MuPAD/Environment/Locked Mode Switch]. Note that this behaviour also concerns clicking on mouse-2 as well as yanking (C-y). In case you work with students and do not want them to "unlock" their session, change the constant 'mupad-forcefully-lock-shell-modep to t in the *file* mupad.el (you could call this modified file mupad-student.el, and replace in their autoload the names "mupad.el" by "mupad-student.el" and similarly with compiled (.elc) files). ######################################### # THE ELECTRIC SEMI-MODE IN MUPAD-MODE # ######################################### This electric semi-mode is meant for writing scripts: lines are automatically indented when ended, closed braces are inserted, closing " are inserted and properly prefixed if they occur within a string. This behaviour can altogether be frozen by setting 'mupad-electric-allowedp to nil. You can modify it partially, via 'mupad-auto-indent, 'mupad-tab-always-indent and 'mupad-no-closed-brace. See the standard hook. In the case of carriage return, if you do not want automatic indentation after a carriage return, you can use M-RET (meta-return). The menu-bar switch Exchange-Keys will exchange the meaning of the keys RET and M-RET. ################ ## HOOKS ## ################ There are five hooks that the user can set, and which are 'mupad-mode-hook : common to both modes. 'mupad-script-mode-hook : special for scripts. 'mupad-shell-mode-hook : special for the shell. 'mupad-input-filter-hook : to interpret some eLisp commands in a mupad-script. 'mupad-mdx-mode-hook : to specify behaviour of the mdx-debugger. For the time being, users should only use 'mupad-mode-hook and forget about 'mupad-script-mode-hook and 'mupad-shell-mode-hook. We shall describe the other two hooks in the section relative to eLisp programs for one and in the section devoted to mdx for the other. First note that many of these variables takes boolean values, which in eLisp are denoted by t (for true) and nil (for false). Here is a general pattern for 'mupad-mode-hook: (setq mupad-mode-hook (function (lambda nil ; To select where utilities are to be found: (setq mupad-directory "/usr/local/MuPAD-1.4.0/share/") ;; also hypage should be "../bin/hypage" relative to ;; this directory and the (relative) file ;; "doc/hytex/man_eng" should exists. ; To select where vcam is to be found: (setq mupad-directory "/usr/local/MuPAD-1.4.0/share/bin/") ; Set this variable to t if you use MuPAD-1.4.1: (setq mupad-mend-vcamp nil) ; To select the name of the mupad executable: (setq mupad-command "mupad") ; To select where the global completion file should be stored: (setq mupad-cpl-directory "~/") ; To select where temporary files will be created: (setq mupad-temp/directory "/tmp/") ; Set this variable to t if you want emacs to start vcam ; whenever it encounters the message "Dumb terminal..." ; and to nil otherwise : (setq mupad-should-not-start-vcam nil) ; Indentation variables: ; See the electric semi-mode part: (setq mupad-electric-allowedp t) ; Carriage return will trigger indentation: (setq mupad-tab-always-indent t) ; Turn off self-closed barces: (setq mupad-no-closed-braces nil) ; To select where the choice of colors is stored. It should ; be user dependant in case of a network installation. ; A default is provided. (setq mupad-colors "/home/ramare/lisp/first-look/mupad-colors.el") ; Set it to nil if you do not want any highlighting: (setq mupad-can-hilit t) ; To select the javodoc-style for title/description etc: (setq mupad-javadoc-stylep nil) ; To let the system of your email address (could be automated ; with Xemacs). It is required only with the javadoc-style: (setq mupad-user-mail-address "ramare@gat.univ-lille1.fr") ; To use mupad-lock-shell-mode: (setq mupad-lock-shell-modep t) ; Set this variable to nil if you do not want the arrows up ; and down to carry the history list: (setq mupad-shell-historyp t) ; Set to t if you want Emacs to ask you whether the last session ; of MuPAD should be saved. If so, it will save it in the file ; "MuPAD-last-session" : (setq mupad-save-sessionp nil) ; Set it to nil if you do not want too much help: (setq mupad-tutorial-requiredp t)))) ############ # DEBUGGER # ############ To start the debugger, just type: M-x mdx You get a new MuPAD session, with the -g option enabled. You can run the debugger on any expression by using: >> debug(my_expression); This gives you a new prompt: mdx> You can now type various commands to go through the execution of the expression. Emacs will show in another buffer the file and the position of the expression being debugged. Here is a very short extract of the available commands: Command Emacs shortcut Brief description ? Internal help of the debugger n C-c C-n Next line (skip OVER calls) s C-c C-s Step one line (step INTO calls) c C-c C-r Continue execution C-c C-c Interrupt running computation S C-c C-b Set breakpoint at current file and line q Interrupt current computation and quit mdx This uses gud, which is a generic debugging environment under emacs for various debuggers such as gdb, perldb, ... To get help on this environment, type: M-h m The debugger is customized via the hook 'mupad-mdx-mode-hook. BUGS: There are some limitations due to MuPAD's debugger. I quote: You can't debug functions/libraries that are already loaded on their original source code, but only on the internal data. Activate debugger on startup to debug on the original source code. For example, use option -g on Unix systems. Well, even with -g on startup this does not work (MuPAD 1.4). The internal commands of MuPAD's debugger are not perfectly standard (S, ...). This should be fixed with MuPAD 1.5. Some shortcuts of Emacs are not yet implemented and do not send the correct command to MuPAD's debugger. ################ # HIGHLIGHTING # ################ The best way to customize your colours is through the menu-bar. Note that global-variables are not yet coloured. If you find that highlighting takes too much time, you can disable the colouring of some patterns by selecting the colour 'default. Just now, most of the time for highlighting is spent working on 'primitive-names, so selecting the default colour for this item will be a real time saver. ########### # MARKERS # ########### If your script if long, eLisp may have to scan the whole program to determine whether point is within a comment, or a function definition and so on, which tends to slow things down if your script is more than say 500 lines. You can then introduce some markers that indicates safe places outside a comment or a function definition. The two predefined markers are `####' and `//--'. Such a pattern should be placed at the beginning of a line and followed by an end of line. ################### # HELP/COMPLETION # ################### Both of these features rely heavily on the existence of a mupad-process. This has been done so that modification of MuPAD will not require modifications of mupad.el. For instance going from version 2.0.3 to 2.0.4 would have been quite a pain to handle. All the MuPAD predefined words are stored in the file "mupad-cpl-file.el" which should be stored in the directory specified by the variable 'mupad-cpl-directory. Such a file will be created if required in which case emacs will start automatically a mupad-process in the background. You may have to wait a bit when this is first done. If you change your version of MuPAD, simply erase the file "mupad-cpl-file.el". If you export some package, for instance "numeric", you will want the completion system to know about it and to complete "quad" to "quadrature". As soon as a file containing "export("numeric")" is send to the mupad-process via emacs, it will be so. If you want it to be so without sending the whole file to MuPAD, simply select the region in which the string above appears (maybe in a comment) and send to MuPAD. Nothing more will be done than extending the completion system. #################### # GRAPHICAL MATTER # #################### Nothing much has been done here since I do not use them nor do I know much about this subject either. Any help is welcome. As mentioned above, the variable mupad-vcam-directory decides where the executable vcam is to be found. Curiously enough, with version 1.4.1, vcam commits suicide when called from this shell, so a local mending has been provided: set the variable 'mupad-mend-vcamp to t in 'mupad-mode-hook. Well, you can always set this variable to t in fact, but it is a bit better not to use if you can. ################## # eLisp COMMANDS # ################## An important functionnality is the possibility to introduce elisp-commands inside a mupad-script. Elisp commands can be inserted anywhere and will be executed prior to sending the file to MuPAD. The file should be edited for emacs to take care of these commands. They are to be surrounded by "/*@@" and "*/", like in /*@@ .................. */ An additional cookie is the string "//@@" which, when located in a program at the beginning of a line and followed by a newline is understood as emacs-should-not-wait-for-output-of-the-program, which is convenient while working with lengthy programs that give partial answers. In fact, the effect of "//@@" can be obtained by writing /*@@ (setq mupad-should-wait-for-outpup nil) */ This variable is automatically reset to t after the output. Concerning this functionnality, a hook mupad-input-filter-hook is run whenever an input is sent to mupad. It can be set in the .emacs and can be modified in the file itself. For instance, if the file "mupad-with-syntax.el" contains the function 'translate, we can use /*@@ (load-file "mupad-with-syntax.el") (setq mupad-input-filter-hook (list 'translate)) */ By "translation" we mean applying some transformations to a mupad-script before sending it to mupad. There is a general file "mupad-translator.el" which contains functions handy for writing such a translator. The hook 'mupad-input-filter-hook is automatically reset to nil after evaluation. ######### # NOTES # ######### (1) This version has been built for emacs 19.34 and works also fine with emacs 20.3. It should also work with Xemacs. (2) javadoc-style has not yet been properly implemented. (3) You may be dazed by the way emacs treats indentation at first. Just leave it alone, and you'll soon see what happens. You can use the menu-bar item [MuPAD ReWrite Region] after having marked a region containing a proc to get an idea of what emacs thinks a well-written script looks like. (4) For the time being, starting is a bit slow. We hope to do better in a near future. ############## # KNOWN BUGS # ############## On very old system an '^M' apears at the end of the lines printed by MuPAD. ######################################################################## ######################################################################## Last Modified: 29-Marsh-1999 by Olivier Ramare. VERSION: 1.26 ;; mupad.el-info ends here