home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / elisp / packages / rexx-1.0 / rexx-mode.doc < prev    next >
Encoding:
Text File  |  1993-03-19  |  9.6 KB  |  329 lines
  1.  
  2.                rexx-mode  V1.0
  3.                ~~~~~~~~~~~~~~~
  4.                    
  5.         Copyright (C) 1993 by Anders Lindgren.
  6.                    
  7.           This file is NOT part of GNU Emacs (yet).
  8.                    
  9.                    
  10.                    
  11.                  DISTRIBUTION
  12.  
  13.     rexx-mode is free software; you can redistribute it and/or modify
  14.     it under the terms of the GNU General Public License as published 
  15.     by the Free Software Foundation; either version 1, or (at your 
  16.     option) any later version.
  17.  
  18.     GNU Emacs is distributed in the hope that it will be useful,
  19.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  20.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21.     GNU General Public License for more details.
  22.  
  23.     You should have received a copy of the GNU General Public
  24.     License along with GNU Emacs; see the file COPYING.  If not,
  25.     write to the Free Software Foundation, 675 Mass Ave, Cambridge,
  26.     MA 02139, USA.
  27.  
  28.  
  29.                 AUTHOR
  30.           Anders Lindgren, d91ali@csd.uu.se
  31.                    
  32.                Abbrevationtable due to:
  33.         Johan Bergkvist, nv91-jbe@nada.kth.se
  34.  
  35.  
  36.                  INTRODUCTION
  37.  
  38.     The rexx-mode is a package contains an edit mode for the
  39.     REXX language, called rexx-mode, and a source level debugging
  40.     mode, called rexx-debug (or rxdb-mode for short) for the
  41.     GNU Emacs editor.
  42.  
  43.     The following files is part of the distribution:
  44.  
  45.     rexx-mode.doc        This file
  46.     rexx-mode.el        The elisp code for rexx-mode.
  47.     rexx-debug.el        The elisp code for the debugger.
  48.     comint.el        General purpose process communication
  49.                     module by Olin Shivers.
  50.     *.elc            Byte-compiled versions of the above.
  51.     
  52.     readme.amiga        Some details concerning a bug in
  53.                 the Amigaport V1.26 of GNUEmacs.
  54.     rxnq/rxnq        A hack to fix the above mentioned bug.
  55.     rxnq/rxnq.c        Sourcecode in C for rxnq.
  56.     
  57.  
  58.                 HOW TO INSTALL
  59.  
  60.     In order to use the rexx mode and the debugger they have
  61.     to be loaded into Emacs. This can manually be done
  62.     by M-x load-library RET rexx-mode RET. Although this
  63.     is rather cumbersome. A better way is to autoload them,
  64.     i.e. emacs loads them when they are needed.
  65.  
  66.     Emacs can also recognize certain types of files and
  67.     start the correct mode accordigly.
  68.  
  69.     The script below will recognize .rexx, .elx, .ncomm and .cpr
  70.     files as REXX-files. If you would like others to be recognized,
  71.     create additional (cons ...) lines. Please insert the script
  72.     to your ~/.emacs file.
  73.  
  74.     See also the parts on custimation below.
  75.  
  76.     --- cut here --- cut here --- cut here --- cut here ---
  77.  
  78. (autoload 'rexx-mode  "rexx-mode"  "REXX mode" t)
  79. (autoload 'rexx-debug "rexx-debug" "REXX source level debugger" t)
  80. (setq auto-mode-alist
  81.       (append
  82.        (list (cons "\\.rexx$"  'rexx-mode)
  83.          (cons "\\.elx$"   'rexx-mode)
  84.          (cons "\\.ncomm$" 'rexx-mode)
  85.          (cons "\\.cpr$"   'rexx-mode)
  86.          )
  87.        auto-mode-alist))
  88.  
  89.     --- cut here --- cut here --- cut here --- cut here ---
  90.  
  91.  
  92.                   EDIT MODE
  93.  
  94.     The edit mode knows the indentations rules which applies to
  95.     REXX programs, and tries to indent the lines accoringly. It is
  96.     capable of recognizing DO-blocks, SELECT-blocks, IF-THEN-ELSE
  97.     statements etc. It also recognizes comments and strings.
  98.  
  99.     To indent the line, execute the funciton rexx-indent-command,
  100.     which is normally bound to TAB. It indents line line (or
  101.     inserts a TAB depending on the cursor position and the
  102.     variable rexx-tab-always-indent.)
  103.  
  104.     The standard GNU Emacs commands, such as indent-region 
  105.     work properly in rexx-mode.
  106.  
  107.  
  108.               CUSTOMIZATION OF REXX-MODE
  109.  
  110.     rexx-mode follows the Emacs tradition of being as customizable
  111.     as possible. The following variables directs the indentation:
  112.  
  113.     rexx-indent:
  114.         The basic indentation for do-blocks.
  115.  
  116.     rexx-end-indent: 
  117.         The relative offset of the "end" statement.
  118.         0 places it in the same column as the statements of
  119.         the block. Setting it to the same value as
  120.         rexx-indent places the "end" under the do-line.
  121.  
  122.     rexx-cont-indent:
  123.         The indention for lines following "then", 
  124.         "else" and "," (continued) lines.
  125.  
  126.     rexx-tab-always-indent:
  127.         Non-nil means TAB in REXX mode should always reindent
  128.         the current line, regardless of where in the line the
  129.         point is when the TAB command is used.
  130.  
  131.     
  132.  
  133.     The variable rexx-indent set the basic indentation. Setting
  134.     it to 4 results in the following indentation:
  135.  
  136.         DO
  137.             SAY 'foo'
  138.             ...
  139.  
  140.     while setting it to 8 (which is the default) results in:
  141.  
  142.         DO
  143.             SAY 'foo'
  144.             ...
  145.  
  146.     The variable rexx-cont-indent indents IF-THEN-ELSE statements
  147.     and continued lines. It is strongly recomended to set it
  148.     to the same value as rexx-indent.
  149.  
  150.     The rexx-end-indent controls the placement of the END. If it
  151.     contains 0 the end is placed in the same column as the block,
  152.     for example:
  153.  
  154.         DO
  155.             SAY 'foo'
  156.             END
  157.  
  158.     A positive value will move it to the left, by setting it to the
  159.     same value as rexx-indent the end is aligned with the DO, as
  160.     shown below:
  161.  
  162.         DO
  163.             SAY 'foo'
  164.         END
  165.  
  166.  
  167.     The return key ought to be redefined to either 
  168.     rexx-newline-and-indent, or rexx-indent-newline-indent.
  169.     The latter is prefered if the indentation has been configurated
  170.     to place the END under the corresponding DO or SELECT-statement.
  171.     It indents the current line before creating a new. If a non-
  172.     standard indentation is wanted, press C-q RET TAB to create
  173.     a new line without indentating the current.
  174.  
  175.     The "normal" newline-and-indent command is not recomended since
  176.     it doesn't expand abbrevs.
  177.  
  178.  
  179.                  ABBREV MODE
  180.  
  181.     The editing mode contains an abbrevation table consisting of
  182.     all the keywords of REXX. When active it will automatically
  183.     convert all keywords into upper case when typed. 
  184.  
  185.     Abbrev-mode is turned on by M-x abbrev-mode, or by calling
  186.     (abbrev-mode 1) from lisp, for example from a hook.
  187.  
  188.  
  189.                   DEBUG MODE
  190.  
  191.     The debug mode is a simple fontend to the normal rexx debugger
  192.     Currently, the ONLY thing it does is to parse the output
  193.     for line-numbers. If one is found, an arrow is placed on the
  194.     corresponding line in the window containing the source.
  195.  
  196.     The rexx-debug mode is called by the function rexx-debug, which
  197.     is bound to C-c C-c in rexx-mode. It will prompt you for
  198.     the name of the file (press return to use the current buffer)
  199.     and the arguments to send to the script.
  200.  
  201.     The debug-mode is built using comint.el by Olin Shivers which
  202.     contains full history and other command line features.
  203.  
  204.     The following keys can be used in rexx-debug mode.
  205.  
  206.     m-p                    Cycle backwards in input history.
  207.     m-n                        Cycle forwards.
  208.     m-s                Previous similar input.
  209.     c-m-r             Search backwards in input history.
  210.     return            Send input to REXX.
  211.     c-a                     Beginning of line; skip prompt.    
  212.     c-d                  Delete char unless at end of buff. 
  213.     c-l            Refresh
  214.     c-c c-u                   Kill input.
  215.     c-c c-w                   Backward kill word.
  216.     c-c c-c               Interrupt subjob.
  217.     c-c c-z                   Stop subjob.
  218.     c-c c-\                   Quit subjob.
  219.     c-c c-o                   Delete last batch of process output.
  220.     c-c c-r                   Show last batch of process output.
  221.  
  222.     Suggestions of additions to this mode is appreciated.
  223.  
  224.  
  225.            CUSTOMIZATION OF THE DEBUG MODE
  226.  
  227.     The rexx-debug mode contains the following variable:
  228.  
  229.     rxdb-command-name
  230.         The name of the REXX interpretator in the current system.
  231.  
  232.  
  233.                 HOOKS
  234.  
  235.     The normal way to configureate a mode under Emacs is to create
  236.     a so called hook, which is called when a mode is started. This
  237.     is way better then to setq all varaibles on startup. For example,
  238.     you never have to look up the name of the keymap, use 
  239.     local-set-key instead. Hooks is normally placed in ~/.emacs,
  240.     or in other files loaded at startup.
  241.  
  242.  
  243.     The following hooks are called:
  244.  
  245.     rexx-mode-hook    on entry to rexx-mode.
  246.  
  247.     rxdb-mode-hook      when entering rexx-debug mode (rxdb-mode).
  248.     
  249.     comint-mode-hook  is also called before the above, as it is by
  250.               all modes which uses comint. (i.e. Don't put
  251.               any REXX-specific stuff here.)
  252.  
  253.  
  254.     A hook looks like:
  255.  
  256.     (setq some-hook '(lambda ()
  257.                ;; statements to be executed when mode started.
  258.                ))
  259.     
  260.     [ Technically, the variable some-hook is assigned to a nameless
  261.     function, indicated by the (lambda () ...), which is executed when
  262.     the mode is stared.รก]
  263.  
  264.  
  265.     Example 1:
  266.     (setq rexx-mode-hook '(lambda ()
  267.             (setq rexx-indent 4)
  268.             (setq rexx-end-indent 4)
  269.             (setq rexx-cont-indent 4)
  270.             (local-set-key "\C-m" 'rexx-indent-newline-indent)
  271.             (abbrev-mode 1)
  272.             ))
  273.  
  274.     will make the END aligned with the DO/SELECT. It will indent
  275.     blocks and IF-statenents four steps and make sure that the END
  276.     jumps into the correct position when RETURN is pressed. Finaly 
  277.     it will use the abbrev table to convert all REXX keywords into
  278.     upper case.
  279.  
  280.     
  281.     Example 2:
  282.     (setq rxdb-mode-hook '(lambda ()
  283.             (setq rxdb-command-name "/usr/local/bin/rexx")
  284.             ))
  285.  
  286.     is quite useable is UNIX environments.
  287.  
  288.  
  289.              KNOWN BUGS/PROBLEMS
  290.  
  291.     -- Nested comments aren't supported. This is because the standard
  292.     Emacs parsing functions are used. A new can be written in elisp but
  293.     I don't belive it will be efficient enough.
  294.  
  295.  
  296.     -- The Amigaport V1.26 of GNUEmacs has a annoying bug; it quotes
  297.     all arguments to commands, therefore RX can't be called directly.
  298.  
  299.     A workaround is to specify rexx-command-name to "rxnq", which
  300.     is a small (264 bytes!) command (i.e. hack) which strips the quotes
  301.     and calls RX. To do this, place the following line into the
  302.     rxdb-mode-hook is the s:.emacs file:
  303.  
  304.         (setq rxdb-command-name "rxnq")
  305.  
  306.     And place rxnq in the loadpath.
  307.  
  308.  
  309.                  FINAL WORDS
  310.  
  311.     I would like to thank Bo Liljegren and Johan Bergkvist, both
  312.     members of Swedish User Group of Amiga (SUGA). A special
  313.     thank is also given to Malin, who has put up with me while
  314.     writing this, and other programs.
  315.  
  316.     Suggestions, new ideas and (positive) criticism are highly
  317.     appreciated. Please email them to:
  318.  
  319.         d91ali@csd.uu.se
  320.  
  321.     or snail mail them to:
  322.  
  323.         Anders Lindgren
  324.         Kantorsg. 2-331
  325.         754 24 Uppsala
  326.         Sverige
  327.  
  328.                     /Anders Lindgren, 93-03-20
  329.