home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / m / me_cd25.zip / DOC.ZIP / ME2MUTT.DOC < prev    next >
Text File  |  1992-11-09  |  59KB  |  1,190 lines
  1. !!!Concepts chapter:
  2.   talk about garbage collection:  what when
  3.   talk general about bags, marks, buffers
  4.   talk about current buffer, current window ain't the same
  5. ========================================================================
  6. ==    The ME Mutt Connection        Craig Durland  9/89 10/91 11/91   ==
  7. ========================================================================
  8.  
  9.   This document describes the link between the Mutt2 programming
  10. language (see MUTT2.DOC) and the Mutt Editor II (see ME2.DOC).
  11.  
  12.  
  13.              Copyright 1991 Craig Durland
  14.     Distributed under the terms of the GNU General Public License.
  15.   Distributed "as is", without warranties of any kind, but comments,
  16.            suggestions and bug reports are welcome.
  17.  
  18. ========================================================================
  19. ==        The ME2 Mutt functions                      ==
  20. ========================================================================
  21. (append-to-bag bag-id TEXT      <text>)
  22. (append-to-bag bag-id REGION      [mark1 mark2])
  23. (append-to-bag bag-id CHARACTERS <number>)
  24. (append-to-bag bag-id RECTANGLE  [mark1 mark2])
  25.       where TEXT = 0, CHARACTERS = 1, REGION = 2 and RECTANGLE = 3.
  26.  
  27.     TEXT       :    [NUMBER 0 STRING         : VOID]
  28.     REGION       :    [NUMBER 1 [NUMBER [NUMBER]] : VOID]
  29.     CHARACTERS :    [NUMBER 2 NUMBER        : VOID]
  30.     RECTANGLE  :    [NUMBER 3 [NUMBER [NUMBER]] : VOID]
  31.  
  32.   These functions append text to a bag.  
  33.     TEXT : Appends a string to the bag.
  34.     REGION : Appends the text contained in a region.
  35.     CHARACTERS : Appends n characters, starting from the dot.
  36.     RECTANGLE :    Copies the region-rectangle.  This clears the bag first.
  37.       Note that appending anything to a bag with a rectangle in it
  38.       (unless it is another rectangle) is a no-op until you clear the
  39.       bag.
  40.  
  41.   For example:
  42.     If the region contains "This is a test" then
  43.       (clear-bag 0)
  44.       (append-to-bag 0 REGION) (append-to-bag 0 TEXT " foo bar")
  45.     will set the cut buffer to "This is a test foo bar".
  46.   See also:  create-bag, clear-bag, insert-register, bag-stats,
  47.     bag-to-string.
  48. (arg-flag)                           [zip : BOOLEAN]
  49.   Check to see if somebody set the arg-prefix before calling this
  50.     routine (via (universal-argument) or (arg-prefix n)).
  51.   See also: arg-prefix.
  52. (arg-prefix [arg])                       [[NUMBER] : NUMBER]
  53.   Get or set the universal-argument.
  54.   With an arg, its the same as ^U before a function.
  55.     Notes:
  56.       The arg-flag is set to TRUE.
  57.       This really sets two prefixes:  one for ME commands and one for
  58.     Mutt programs.  ME commands and exe-key use and reset the prefix
  59.     to 1.  Programs can only read the prefix and so it will stay the
  60.     same for all children of a program unless it is changed by
  61.     (arg-prefix n).  If it is changed, all the children AND parents
  62.     will see the new value.  It is a good idea to make a copy of the
  63.     value upon entry to a program if it is possible that a child
  64.     might change it.
  65.       If prefix is not set, it is always 1 (and the arg-flag is FALSE)
  66.     when a program or ME command is run from the keyboard.
  67.   Note that there is a difference between (arg-prefix 1) and the default.
  68.     Setting arg-prefix sets arg-flag.  There are commands that just look
  69.     at arg-flag and do different things if it is set.
  70.   For example, to make META-n start the (universal-argument) count at n,
  71.     use the following (where n is 1,2,3,4,5,6,7,8 or 9):
  72.     (defun
  73.       META-arg { (arg-prefix (- (key-pressed) 0x230))(universal-argument) }
  74.       MAIN
  75.       {
  76.     (int j)
  77.     (for (j 1)(< j 10)(+= j 1)
  78.       (bind-to-key (concat "META-arg")(concat "M-" j)))
  79.       }
  80.     )
  81.   See also: (arg-flag), (universal-argument) in ME2.DOC.
  82. (argc)                                [zip : NUMBER]
  83.   The number of parameters on the command line when ME was invoked +1.
  84.   eg "ME2 foo bar" has argc == 3.
  85.   Use argv to look at the parameters.
  86. (argv)                             [NUMBER : STRING]
  87.   The ME command line parameters.  There are argc of them, numbering
  88.     0...argc-1.  (argv 0) is the name of the program (ME) (unless you are
  89.     running on MS-DOS 2.x where it is ""), (argv 1) is the first file name
  90.     (which is loaded by me2.mut), (argv 2) is the next file name, etc.
  91.   See nextfile.mut for an example.
  92. (attached-buffer window-id | buffer-name)      [NUMBER|STRING : NUMBER]
  93.   If given a number, attached-buffer returns the buffer id that is
  94.     attached to window n.  n == -1 means use the current window.
  95.   If given a name, attached-buffer returns the id of the buffer that is
  96.     named name.  Returns -2 if the buffer does not exist.
  97.   For example:
  98.     if the cursor is in third window (window #2) which is displaying
  99.       buffer "foobar" and foobar has an id of 123 then:
  100.     (attached-buffer -1) and (attached-buffer 2) both return 123.
  101.     (attached-buffer "foobar") returns 123.
  102.     (attached-buffer "FOOBAR") returns -2.
  103.   See also: buffers, windows.
  104.  
  105. (bag-stats bag-id pointer-to-data)             [NUMBER BLOB : VOID] 
  106.   Get stats on a bag.  pointer-to-data is a pointer the the data area
  107.     that the stats are put into:
  108.   (byte type) (small-int width height) (int size)    ;; struct BagInfo
  109.     type: 0 means text and 1 is rectangle.
  110.     width, height:  If the register is a rectangle.
  111.     size: Number of bytes in the register.
  112.   For example:
  113.     (defun get-bag-stats
  114.     {
  115.       (byte type)(small-int width height)(int size)    ;; struct BagInfo
  116.       (int n)
  117.  
  118.       (n (convert-to 3 (ask "bag id: ")))
  119.       (bag-stats n (loc type))
  120.       (msg "bag[" n "]: " (if (== type 0) "Text." "Rectangle.")
  121.     " Width:" width " Height:" height " Size:" size
  122.       )
  123.     })
  124.   Note:
  125.     If the bag is not a rectangle, the width and height are garbage.
  126.   See also:  append-to-bag, clear-bag, insert-bag.
  127. (bag-to-file bag-id file-name)             [NUMBER STRING : BOOLEAN]
  128.   Copy the contents of a bag to a file.  If the file already exists, it
  129.     is overwritten.
  130.   If bag-id is bad, the program aborts.
  131.   If some kind of error occurs (can't open file-name or can't write all
  132.     of bag), FALSE is returned so you can clean up if necessary.
  133.   See also: file-to-bag, bag-to-string
  134. (bag-to-string bag-id)                     [NUMBER : STRING]
  135.   Convert bag contents to a string.
  136.   If the bag contains a rectangle, the string will be each line of the
  137.     rectangle, one after the other.
  138.   Note:
  139.     The string sticks around until the bag is changed (clear-bag,
  140.     append-to-bag, etc).  At that point, the string is garbage and can
  141.     cause unknown behavior if used.  Use the string or save it - don't
  142.     expect it to hang around.
  143.   See also: append-to-bag
  144. (bit-and x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  145.   Binary and 2 or more numbers.
  146.   See also bit-or, bit-xor.
  147. (bit-or  x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  148.   Binary or 2 or more numbers.
  149.   See also bit-and, bit-xor.
  150. (bit-xor x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  151.   Binary xor 2 or more numbers.
  152.   See also bit-and, bit-or.
  153. (buffer-flags buffer-id [flags])        [NUMBER [NUMBER] : NUMBER]
  154.   Get or set the buffer flags.  There are 32 flags.
  155.     Bit        Flag    Notes
  156.     ---        ----    -----
  157.     0x0001  Modified    1 if the buffer has been modified since last save.
  158.     0x0002  NoCare    1 if don't care about buffer contents.
  159.     0x0004  Hidden    1 if buffer is hidden from user.
  160.     0x0008  Undo    1 if undo is turned on for the buffer.
  161.     0x0010  Mode    Tickle bit: force (modeline-hook) to be called.
  162.     0x0020  Immortal    Not a temporary buffer.
  163.     0x0040  Interactive A buffer for humans.
  164.  
  165.     The lower eight bits are reserved for ME2's use, you can use the
  166.       other 24.  Note - you might want to leave a few bits at the bottom
  167.       unused in case I need some more in the future.
  168.   Notes:
  169.     The Modified flag is set whenever the buffer changes.  When it
  170.       changes, (modeline-hook) is called.
  171.     The NoCare flag is used whenever ME wants exit or change a buffer -
  172.       it is set, ME will not ask before changes are made.
  173.     A buffer with the Hidden flag set is invisible to the user -
  174.       (next-buffer) skips it, the help and command completion routines
  175.       ignore it.
  176.     If you want a buffer to have undo, set this bit.  0 (off) is the
  177.       default.
  178.     Mode is a write only flag.  Set it if you want (modeline-hook) to be
  179.       called.
  180.     All buffers are created Mortal by default.  This means that they can
  181.       be garbage collected when your program is done running.  If you
  182.       want the buffer to live forever (at least until you free it), set
  183.       this bit.  Actually, set this bit in (create-buffer).
  184.     ME sets the Interactive bit for program convenience.  I typically
  185.       use it to avoid setting modes, etc for buffers where the modes
  186.       won't be used.  It is set by:  (switch-to-buffer), (visit-file)
  187.         and when the last buffer is freed and I have to create *scratch*.
  188.     If a tickle bit is set, only tickle bits are processed and other
  189.       bits are ignored.  So, for example, if you wanted (modeline-hook)
  190.       called and set the Undo flag, it takes two calls to
  191.       (buffer-flags).
  192.   See also: buffer-modified, create-buffer, modeline-hook.
  193. (buffer-modified buffer-id [bool])          [NUMBER [BOOLEAN] : BOOLEAN]
  194.   Check to see if buffer n is modified.
  195.   If n == -1 the current buffer is used.
  196.   (buffer-modified -1) : TRUE if the current buffer is modified.
  197.   (buffer-modified 123) : TRUE if the buffer with id 123 has been modified.
  198.   (buffer-modified -1 FALSE) : mark the current buffer as not modified.
  199.   See also: buffer-flags, current-buffer, (not-modified).
  200. (buffer-name buffer-id)                     [NUMBER : STRING]
  201.   Return the name of a buffer.
  202.   (buffer-name -1) returns the name of the current buffer.
  203.   See also: create-buffer, current-buffer, file-name.
  204. (buffer-stats n array int 6)                  [NUMBER BLOB : VOID]
  205.   Get some stats on the nth buffer.  n == -1 means current buffer.
  206.   These  stats  are:  buffer-size  (in   characters),   dot  (number  of
  207.     characters  from the start of the  buffer),  lines  (number  of text
  208.     lines in the buffer),  buffer-row (the line in the buffer the dot is
  209.     on), wasted (the number of  characters  allocated  but not used) and
  210.     character-at-dot  (ASCII  value  - eg if  the  dot is on a "A"  then
  211.     character-at-dot == 65).
  212.   Note that buffer-size may NOT be the same as the file size.  For
  213.     example, on MS-DOS the buffer is smaller than the file because the
  214.     <carriage-return><newline> is folded into a newline when the file is
  215.     read into the buffer.
  216.   An example of a typical Emacs buffer stats routine (ie whats bound to
  217.     "^X=") is:
  218.     (include tobase.mut)
  219.     (defun show-buffer-stats    ; bind this to "C-X="
  220.     {
  221.         ;; struct BufferInfo
  222.       (int buffer-size dot lines buffer-row wasted char-at-dot ratio)
  223.     
  224.       (buffer-stats -1 (loc buffer-size))
  225.       (ratio 0)(if (!= 0 buffer-size)(ratio (/ (* 100 dot) buffer-size)))
  226.       (msg "Row: " buffer-row "/" lines  " Column: " (current-column)
  227.       " CH: 0x" (tobase char-at-dot 16) 
  228.       " (" ratio "% of " buffer-size ")")
  229.     })
  230.   See also: nth-buffer
  231. (buffer-var var-name [value])                  [STRING [val] : val]
  232.   Each buffer can have local variables.  These vars are not used by ME2 -
  233.     they are there for program use.
  234.   The current buffer is searched for a buffer variable named var-name.
  235.     If it exists and you are trying to set its value, the value is
  236.     checked to make sure its type matches that of the buffer var and
  237.     then value is copied into the var.
  238.   The var is returned (with the new value if set), ready to be used like
  239.     any other Mutt var.
  240.   For example:
  241.     (int n)
  242.     (create-buffer-var NUMBER "x")    ;; create buffer var x of type number
  243.     (create-buffer-var STRING "s" "t")    ;; create 2 string buffer vars
  244.     (buffer-var "x" 123)    ;; set buffer var x to 123
  245.     (n (buffer-var "x"))    ;; also set n to 123
  246.     (buffer-var "s" "foo bar")    ;; set buffer var s to "foo bar"
  247.   Notes:
  248.     Lists and strings are not as well supported in Mutt2 as they could
  249.       be.  Right now, I don't have list or string pointer variables so
  250.       if you want to use a list or string buffer variable without
  251.       referring to it by name, you have to do extra data copies.  For
  252.       example, if you have a list buffer variable and want to modify it,
  253.       you can either use (buffer-var "foo") every time you need the list
  254.       (and spend time doing lookups) or you can (list foo)(foo
  255.       (buffer-var "foo")) and then use foo as you would any other list.
  256.       The drawback here is a copy of the buffer var is put into foo
  257.       (possibly wasting space if the buffer var is very big and it takes
  258.       time to do the copy).  You also have to remember to copy foo back
  259.       into the buffer bar after you modify it or all your changes will
  260.       be garbage collected into never-never land.  If I ever get around
  261.       to implementing pointer types, you will be able to (pointer list
  262.       foo)(foo (loc (buffer-var "foo"))) and then when you modify foo,
  263.       you will be really modifying the buffer var, avoiding extraneous
  264.       data copies and making less garbage to be collected.  You can fake
  265.       pointers by passing the buffer var to a function:  (bar
  266.       (buffer-var "foo")) where (defun bar (list foo) ...).  bar will
  267.       get a pointer to foo and can change it as described above.
  268.   See also:  create-buffer-var, markring.mut
  269. (buffers)                            [zip : NUMBER]
  270.   Return the number of buffers.
  271.   See also: nth-buffer.
  272.  
  273. (case-bag op bag-id)                    [NUMBER NUMBER : VOID]
  274.   Do some case folding on the contents of a bag.
  275.     op    action
  276.     --    ------
  277.     0    Lower case text.  All text in the bag is converted to lower case
  278.     in place.
  279.     1    Upper case text.
  280.     2    Capitalize text.  All text in the bag is capitalized.  The
  281.     starts of words are converted to upper case and all other text
  282.     is converted to lower case.  A character is the start of a word
  283.     if:  It is the first character in the bag and the syntax tables
  284.     say it is a word character or the character is a word character
  285.     and the character before it is a nonword character (white space).
  286.   See also: modify-syntax-entry, case.mut (for examples).
  287. (clear-buffer)                              [zip : VOID]
  288.   Clear the current buffer.
  289.   Remove all contents of the buffer and clear the marks.  There is no
  290.     checking - you need to do that if you care.  If undo is turned on,
  291.     the undo stack is cleared (yeah, I know it stinks, but I had my
  292.     reasons).
  293.   See also: free-buffer
  294. (clear-bag bag-id)                     [NUMBER : NUMBER]
  295.   Clears the bag by setting it to "".  The bag type is set to TEXT.
  296.   Bag id 0 is the cut buffer.
  297.   Returns bag-id.
  298.   See also:  append-to-bag, create-bag, insert-bag, bag-stats.
  299. (compare-marks [mark1 mark2])            [[NUMBER NUMBER] : NUMBER]
  300.   Returns: 1 (dot on same line as mark), 2 (dot above mark),
  301.     3 (dot below mark).
  302.   See also: region-stats.
  303. (complete selector "prompt")              [NUMBER STRING : STRING]
  304.   Works the same as (ask) but allows command completion.
  305.     Selector: bitwise OR the lists you want to complete:
  306.     bit    value    list
  307.      0    0x01    ME keywords (listed in ME2.DOC)
  308.      1    0x02    program names
  309.         2    0x04    Mutt keywords
  310.         3    0x08    buffer names
  311.      4    0x10    system vars
  312.      5    0x20    File names
  313.   For example:  Get a file path, using file name completion and insert
  314.     it at the dot:
  315.     (defun insert-file-name
  316.     { (insert-text (complete 0x20 "file name: ")) })
  317.   See also: ask (in MUTT2.DOC)
  318. (create-bag [immortal])                      [[BOOLEAN] : NUMBER]
  319.   Create a bag and return its id.  Whenever you need to do something
  320.     with this new bag, use its id.
  321.   The immortal flag controls how a bag is treated at garbage collection
  322.     time.  If TRUE, the bag won't be garbage collected and you have to
  323.     use free-bag to get rid of the bag.
  324.   The cut buffer always has an id of 0 and is created by ME at startup.
  325.   See also: free-bag, the discussion about garbage collection.
  326. (create-buffer name [flags])            [STRING [NUMBER] : NUMBER]
  327.   Create a buffer and return its id.  Whenever you need to do something
  328.     with this new buffer, use its id.
  329.   The name can be anything you want - it can be empty, contain blanks,
  330.     be the same as other buffer names, etc.  Since the buffer is referred
  331.     to by its id, there is no confusion.  Where the confusion comes in
  332.     is when the user wants to deal with the buffer - in that case, you
  333.     might want to use something reasonable for the name.
  334.   See buffer-flags for info on those.  Remember to set the immortal bit
  335.     if you want the buffer to hang around.
  336.   (buffer-created-hook) is called.
  337.   See also:  attached-buffer, buffer-flags, free-buffer, the discussion
  338.     about garbage collection, buffer-created-hook.
  339. (create-buffer-var type name [name ...])    [NUMBER STRING ... : VOID]
  340.   Create one or more buffer variables with a given type.
  341.   Supported types:
  342.     NUMBER    0x03
  343.     STRING    0x08
  344.     LIST    0x09
  345.   Buffer local variables are variables that live in a buffer.  This
  346.     allows you to store localized data in a buffer - two buffers can
  347.     have variables of the same name that contain different data (or even
  348.     data with different types).  This is useful when you need one
  349.     variable to hold different data for each buffer (such as with mark
  350.     rings - each buffer has a different ring but the mark ring code is
  351.     the same for all buffers).
  352.   Buffer vars live and die with the buffer.  When the buffer is freed,
  353.     all the buffer vars are too.  This is the only way to remove buffer
  354.     vars from a buffer.
  355.   If a buffer var named <name> already exists, create-buffer-var doesn't
  356.     do anything.  It should at least check to see if the types match.
  357.   See also:  buffer-var, markring.mut
  358. (create-mark [immortal])                  [[BOOLEAN] : NUMBER]
  359.   Create a mark and return its id.  Whenever you need to do something
  360.     with this new mark, use its id.  Marks are always created in the
  361.     current buffer and are invalid (ie not marking anything) when
  362.     created.
  363.   The immortal flag controls how a mark is treated at garbage collection
  364.     time.  If TRUE, the mark won't be garbage collected and you have use
  365.     free-mark to get rid of the mark.
  366.   When a buffer is created, two marks are allocated in it:  the dot (id
  367.     0) and the mark (id 1).  They are always in the buffer can be used
  368.     just like any other mark.  They can't be freed.
  369.   See also: free-mark, the discussion about garbage collection and marks.
  370. (create-process command)                 [STRING : NUMBER]
  371.   Create a process that will run concurrently with ME2.  Command is
  372.     passed to the compute server for parsing and running.  The process
  373.     communicates to your Mutt program via the process-hook hook.
  374.   Notes:
  375.     The compute server is not built into ME - it is also a separate
  376.       process.  For this reason (and others), only Unix supports
  377.       the compute server.  It needs to be running before create-process
  378.       is called.  The socket name for ME is "$HOME/.ME2.socket".
  379.     You can have many processes running.  Your Mutt programs will have
  380.       to keep track of the process ids to be able to track each process.
  381.   Returns:
  382.     Process id.  -1 if can't create a process.  This id will be used by
  383.       process-hook when the process sends messages to Mutt programs.
  384.   See also:  process-hook, documentation on the compute server
  385.     (COMSERVER.DOC).
  386. (current-buffer [buffer-id [display-buffer]])
  387.                          [[NUMBER [BOOLEAN]] : NUMBER]
  388.   Return the id of the current buffer.
  389.   To change the current buffer, pass in the id.  If you want the new
  390.     current buffer to be displayed in the current window, pass
  391.     display-buffer as TRUE.  The current window will be sync'ed with the
  392.     buffer (ie the window dot will be in the same place as the buffer
  393.     dot).
  394.   If you change the current buffer without displaying it, the windows
  395.     will be unaffected by anything that happens in the buffer - ie you
  396.     would not be able to see anything happening on the screen.  When
  397.     the program finishes running, the buffers and windows will be synced
  398.     up to what they were before the program ran.
  399.   If you change the current buffer and the new current buffer is
  400.     displayed in a non-current window, changes you make to the buffer
  401.     might not be reflected in that window.  See "update" for more on
  402.     this.
  403.   See also:  create-buffer, buffer-modified, buffer-name, buffers,
  404.     file-name, update.
  405. (current-column [column])                   [[NUMBER] : NUMBER]
  406.   With no argument, returns the column after the dot.  Otherwise, the
  407.     dot is set to column.
  408.   (beginning-of-line) is 1.
  409.   When you set the current-column, the dot will get as close as possible
  410.     to the position you specify, subject to:
  411.     - the dot will not leave the current line.
  412.     - because  of tabs and such, the dot may not be in the  column  you
  413.        specify but will be BEFORE the  character  that would have caused
  414.        the dot to be beyond the specified position.
  415.   The new dot column is returned.
  416.   If you wish to force the dot to be in column n, use (current-column n)
  417.     (to-col n).
  418. (current-directory [directory])               [[STRING] : STRING|BOOLEAN]
  419.   (current-directory) returns the current directory (eg "/users/craig").
  420.   (current-directory "tools") attempts to set the current directory to
  421.       tools.  Returns TRUE if successful, FALSE otherwise.
  422.   Note:  Only Unix versions of ME2 can change the dir.  Wildcards and ~
  423.     OK.
  424.   See also: dir.mut for examples.
  425. (current-window [n])                       [[NUMBER] : NUMBER]
  426.   Return the id of the current window.  The windows are numbered 0,
  427.     1, ... (windows)-1 where window 0 is the top window on the screen.
  428.   If changing the current window then:
  429.     The current buffer is changed to the one being displayed in window
  430.       n.  For example, if the current buffer is "foo" and window 0 is
  431.       displaying buffer "bar", (current-window 0) also changes the
  432.       current buffer to "bar".
  433.     The window dot is copied into the buffer dot ie the current buffer
  434.       is sync'ed with the current window.  Thus a buffer will track
  435.       window changes BUT NOT vice versa.
  436.   See also:  attached-buffer, windows, update, (next-window),
  437.     (previous-window) (in ME2.DOC).
  438.  
  439. (do-undo)                            [zip : NUMBER]
  440.   If undo is turned on for this buffer, undo the last block of changes.
  441.   Returns:
  442.     0 : Nothing happened (despite my best efforts)
  443.     1 : Something happened (ie something was undid)
  444.     2 : Problems of some unknow nature
  445.   See also:  buffer-flags, create-buffer, buffer-created-hook.
  446.  
  447. (EoB)                               [zip : BOOLEAN]
  448.   True if the cursor is at the end of the buffer.  Note that end of
  449.     buffer is the empty line you get to with (end-of-buffer).
  450. (erase-rectangle delete)                  [BOOLEAN : VOID]
  451.   Delete or clear the region-rectangle.  If delete is TRUE, the text in
  452.     the rectangle is removed, otherwise it is set to blanks (short lines
  453.     are not extended).
  454.   The dot is left at the upper left corner of the rectangle and the mark
  455.     is at the lower right corner.
  456.   The region-rectangle is the rectangle that has the dot at one corner
  457.     and the mark at the opposite corner.
  458.   See also: append-to-bag, register-stats.
  459. (exe-key keycode)                    [NUMBER : BOOLEAN]
  460.   Execute a key gotten by get-key.  This is the same as pressing that
  461.     key combo on the keyboard.
  462.   Returns TRUE if the key was executable.
  463.   Note: key-pressed is set to the key being executed.
  464.   See also: arg-prefix, get-key, key-pressed.
  465.  
  466. (file-exists file-name)                    [STRING : BOOLEAN]
  467.   Returns TRUE if file-name exists on disk.  If (file-exists file-name)
  468.     returns TRUE then (visit-file file-name) should also return TRUE.
  469. (file-name buffer-id [new-name])        [NUMBER [STRING] : STRING]
  470. (file-name buffer-id [new-name])
  471.                              [NUMBER : STRING]
  472.                          [NUMBER STRING : BOOLEAN]
  473.   Return the name of the file attached to the nth buffer.  If a file is
  474.     NOT attached, returns "".
  475.   (file-name -1) returns the name of the file  attached to the  current
  476.     buffer.
  477.   With new-name, attach a new name for the file attached to the current
  478.     buffer.  Returns TRUE is everything went as expected.
  479.   See also: buffer-name.
  480. (file-to-bag file-name bag-id)             [STRING NUMBER : BOOLEAN]
  481.   Copy the contents of a file to a bag.  The old contents of the bag are
  482.     cleared.
  483.   If bag-id is bad, the program aborts.
  484.   If some kind of error occurs (can't open file-name or can't copy all
  485.     of file-name into bag), FALSE is returned so you can clean up if
  486.     necessary.
  487.   See also: bag-to-file, bag-to-string
  488. (forward-line n)                    [NUMBER : BOOLEAN]
  489.   Move the dot forward n lines (backwards if n < 0).
  490.   The dot is left at column one.
  491.   Returns TRUE if all OK, FALSE if try move off the edge of the buffer
  492.     (the dot is left at the closest edge).
  493. (free-bag bag-id ...)                [[NUMBER [NUMBER ...]] : VOID]
  494.   Free zero or more bags and their contents.  It is always a good idea
  495.     to free bags after you use them (to save space, etc) but you only
  496.     really have to if the bag is immortal.  Mortal bags will be garbage
  497.     collected after your program has finished running.
  498.   Note:
  499.     While it possible to free the cut-buffer (id 0), it is a bad idea
  500.       (and probably a bug).  Lots of people assume (yeah, I know what
  501.       they say about that) that the cut buffer exists and just use it.
  502.       If you do free it, expect fire works.
  503.   See also: create-bag.
  504. (free-buffer buffer-id)                     [NUMBER : NUMBER]
  505.   Free a buffer and all its contents, keys and other resources.  If not
  506.     freed, mortal buffers will be garbaged collected.
  507.   See also: create-buffer.
  508. (free-mark mark-id ...)                [[NUMBER [NUMBER ...]] : VOID]
  509.   Free zero or more marks.  It is always a good idea to free marks after
  510.     you use them (to save space, etc) but you only really have to if the
  511.     mark is immortal.  Mortal marks will be garbage collected after your
  512.     program has finished running.
  513.   You can't free the dot (id 0) or the mark (id 1).
  514.   See also: create-mark.
  515. (free-window n)                        [NUMBER : BOOLEAN]
  516.   Remove the nth window from the screen.  n == -1 means the current window.
  517.   If there is only one window on screen, it is not deleted and FALSE is
  518.     returned otherwise TRUE is returned.
  519.   See also: (split-window), (delete-other-windows) (in ME2.DOC).
  520.  
  521. (get-key)                          [zip : NUMBER]
  522.   Wait for and grab the next ME key combo pressed.  These have a rather
  523.     strange format so it is a good idea to print out the ones you need
  524.     with (insert-text (get-key)).  If you look at the hex values you
  525.     might see a pattern.
  526.   key combo    get-key value
  527.     CR C-M      333 (0x014D)
  528.     f1 F-1     2097 (0x0831)
  529.     a           97 (0x0061)
  530.     A           65 (0x0041)
  531.     ^A C-A      321 (0x0141)
  532.     ^XA ^Xa C-XA 1089 (0x0441)
  533.     ^X^A C-XC-A     1345 (0x0541)
  534.     M-A          577 (0x0241)
  535.   See also: exe-key, getchar.
  536. (get-matched sub-string)                 [STRING : STRING]
  537.   Return the RE substitution of the last (re-search-xxx) or
  538.     (looking-at).
  539.   See REGEXP.DOC for syntax of the sub string.
  540.   eg if (re-search-forward 'f\w*r') matched "foobar" then (get-matched "&")
  541.     returns "foobar".
  542.   See also: (looking-at), (re-string), (re-search-forward),
  543.     (re-search-reverse).
  544. (getchar)                            [zip : STRING]
  545.   Get a character from the keyboard with no echo.  This is different from
  546.     get-key in that the string is the ASCII value of the next key hit.  You
  547.     should only use this for real raw input.
  548.   See also: get-key.
  549. (getenv    environment-variable-name)             [STRING : STRING]
  550.   Get the value of a environment variable.
  551.   Returns "" if not found.
  552.   For example: (getenv "SHELL") might return "D:/MUSH.EXE".
  553. (goto-line n)                        [NUMBER : BOOLEAN]
  554.   Move the dot to the beginning of the nth line in the current buffer.
  555.     First line of the buffer is 1.  If n is negative, got the nth line
  556.     from the end of the buffer.
  557.   Returns FALSE is try to move off either end of the buffer.  In that
  558.     case the dot is left at the buffer edge it tried to move across (at
  559.     the start of the line).
  560.   Notes:
  561.     Line 0 does not really exist so (goto-line 0) returns FALSE.  If you
  562.     ignore the error, (goto-line 0) is the same as (goto-line 1).
  563. (goto-mark mark-id)                    [NUMBER : BOOLEAN]
  564.   Move the dot to the mark whos id is mark-id.
  565.   Returns FALSE if mark-id doesn't exist or the mark is invalid (hasn't
  566.     been set or has been cleared).
  567.   See also:  create-mark, set-mark, swap-marks.
  568. (insert-bag bag-id)                       [NUMBER : VOID]
  569.   Insert the contents of a bag at the dot in the current buffer.
  570.   Bag 0 is the cut buffer.  (insert-bag 0) is the same as (yank).
  571.   If the bag contains a rectangle, the upper left corner of the
  572.     rectangle will be at the dot.
  573.   See also:  create-bag, append-to-bag, clear-bag, bag-stats.
  574. (insert-text stuff)           [STRINGs|NUMBERs|BOOLEANS|VOIDs : VOID]
  575.   Same as msg but the string is inserted into the current buffer.
  576.   eg (insert-text "foo = " foo)
  577.   See also: msg (in MUTT2.DOC).
  578. (is-space)                           [zip : BOOLEAN]
  579.   TRUE if character under cursor is a space or tab.
  580.  
  581. (key-bound-to keystroke-string)                 [STRING : STRING]
  582.   Tell what command a key is bound to.
  583.   For example, (key-bound-to "^A") returns "beginning-of-line".
  584.   If the key is not bound, key-bound-to returns "".
  585.   The typical Emacs function to tell what a key is bound to is:
  586.     describe-key    ;; what is a key bound to
  587.     {
  588.       (string key bind)
  589.  
  590.       (key (ask "Key: "))
  591.       (if (== "" (bind (key-bound-to key)))(msg key " is not bound.")
  592.       (msg key " is bound to " bind))
  593.     })
  594.   For Mutt programmer types, a handy program is:
  595.     deref-key    ;; insert name of the function bound to a key
  596.     {
  597.       (string key bind)
  598.       (key (ask "Key: "))
  599.       (if (!= "" (bind (key-bound-to key)))(insert-text bind))
  600.     })
  601.     This allows programming using keys rather than remembering command
  602.       names.
  603.   See also: complete.
  604. (key-pressed)                            [zip : NUMBER]
  605.   Returns the keycode of the key pressed to invoke the currently
  606.     executing program.
  607.   Note: exe-key sets this.
  608.   See also: exe-key, picture-self-insert in picture.mut for an example.
  609. (key-waiting [number-of-seconds-to-wait])          [[NUMBER] : BOOLEAN]
  610.   Returns TRUE if a user pressed key is sitting in the input buffer.
  611.   You can also specify the number of seconds to wait for a key to be
  612.     pressed.  If a key is pressed during the wait, (key-waiting)
  613.     immediately returns TRUE.  If no key is pressed and the time is up,
  614.     FALSE is returned.
  615.   Note: (key-waiting) is the same as (key-waiting 0).
  616.   Warning:  There are limits to how long you can wait.  Due to many
  617.     factors, you should limit number-of-seconds-to-wait to less than
  618.     32401 (9 hours).
  619.   See also: getchar, get-key.
  620.  
  621. (looking-at RE-string(s))    [STRINGs|NUMBERs|BOOLEANS|VOIDs : BOOLEAN]
  622.   Test to see if the text following the dot matches a regular
  623.     expression.  TRUE if it does.  The arguments are concatenated
  624.     together to form the RE.
  625.   See REGEXP.DOC for syntax of the pattern string.
  626.   Example:
  627.     If the text following the dot is "foobar" then (looking-at 'f\w*r')
  628.       returns TRUE.
  629.   You can retrieve the matched info with get-matched.
  630.   Remember that if you use the "string" form, "\" & "^" MUST be quoted:
  631.     "\\", "\^" if you don't want strange results.  You can
  632.     avoid this problem by using ' instead of ".  (See MUTT2.DOC).
  633.   See also: get-matched, re-string.
  634.  
  635. (modify-syntax-entry modify-string)             [STRING : STRING]
  636.   Modify the syntax table that is used by things that deal with words, etc.
  637.     eg (forward-word) or (re-search-forward).
  638.   String has the form: <type><characters to modify> where type is "w" if
  639.     characters are parts of words, "W" if characters are not parts of words.
  640.   eg (modify-syntax-entry "W0123456789") sez numbers are not parts of words
  641.     (modify-syntax-entry "w-") sez "-" is part of a word.
  642.   Default parts of words are: A-Za-z0123456789$'_
  643.   Returns:  modify-string.
  644. (move-cursor row column)                [NUMBER NUMBER : VOID]
  645.   Move the hardware cursor to (row,column).
  646.   Row and column are both start at zero.
  647.   Move-cursor does not change the dot.
  648.  
  649. (nth-buffer [n])                     [NUMBER : NUMBER]
  650.   Return the id the of the nth buffer.  Buffers are in a list, sorted
  651.     alphabetically, so (nth-buffer 0) is the buffer with the "smallest"
  652.     alphabetical name.
  653.   (nth-buffer) returns the count of the current buffer ie return n where
  654.     (nth-buffer n) is the id of the current-buffer or find n where
  655.     (== (nth-buffer n) (current-buffer)) is TRUE.
  656.  
  657. (OS-filter           [STRING [NUMBER [NUMBER [BOOLEAN]]]] : BOOLEAN]
  658.    filter-name
  659.    [in-bag-id  (-1 if no bag)]
  660.    [out_bag-id (-1 if no bag)]
  661.    [insert-output-at-dot])
  662.   Uses the Operating System to filter text.  On Unix and MS-DOS, this is
  663.     "filter-name <text_in >text_out".
  664.   in-bag-id contains the text_in to be run through the filter.  If id is
  665.     -1, there is no standard in for the filter.  Useful if you just want
  666.     stuff like the output of ls or grep.
  667.   out-bag-id will contain the transformed input text (text_out).  If id
  668.     is -1, the filter output is ignored (unless insert-output-at-dot is
  669.     TRUE).  Useful when the filter creates its own files (such as
  670.     uudecode or uncompress).
  671.   If insert-output-at-dot is TRUE, the output of the filter is also
  672.     inserted into the current buffer at the dot.
  673.  
  674.   OS-filter uses up to 2 files to hold the input and output of the
  675.       filter.
  676.     On UNIX, these are put in /tmp.  On other systems, they are put in
  677.     the current directory.  You can change the directory with a
  678.     environment variable.
  679.       UNIX : $TMP is used to hold the directory.  eg /v0/users/craig
  680.         Note that ME adds a trailing "/" to the name.
  681.       MS-DOS :  TMP is used.  If you have a RAM disk configured as drive
  682.     D and want the files put in the root:
  683.     SET TMP=D:
  684.         Note that ME adds a trailing "/" to the name.
  685.  
  686. (prefix-key n [new-prefix])            [NUMBER [STRING] : STRING]
  687.   Get or set the nth prefix key.  Returns the prefix keycode in ASCII
  688.     form.
  689.   n  Notes
  690.   -  -----
  691.   0  The META prefix.  Default is C-[ (ESCAPE).
  692.   1  Default is C-X.
  693.   2  open
  694.   3  open
  695.   META is a prefix so it can be overloaded (mimiced by) another key.
  696.     A consequence of this is you cannot prefix a METAed key when a META
  697.     key is a prefix.  For example, C-XM-P is OK but M-XM-P is not.
  698.   If you have a real META key, you can turn off prefix key 0.
  699.   Prefix keys 2 and 3 are open - use them for anything you like.
  700.   To turn off a prefix key, set it to "S-" or some other impossible
  701.     keycode (like "S-0").
  702. (puts "string")                    [STRINGs|NUMBERs : STRING]
  703.   Send a string to the terminal.  ME does not see this.
  704.   Useful for defining function keys or creating popup windows.
  705.   See also: insert-text, msg, popup.mut
  706.  
  707. (re-search-forward regular-expression-search-pattern)    [STRING : BOOLEAN]
  708.   Search from the dot forward for text that matches the regular
  709.     expression.  If a match is found, the dot is left after the last
  710.     matched character.
  711.   Returns TRUE if a match is found.
  712.   See also:  re-search-reverse, search-forward, search.mut, REGEXP.DOC.
  713. (re-search-replace search-pattern replace-pattern)
  714.                          [STRING STRING : BOOLEAN]
  715.   Search for (from the dot to the end of the buffer) and replace every
  716.     occurrence of search-pattern with replace-pattern.  re-search-forward
  717.     is used to search and get-matched is called at every match to create
  718.     the replacement text.
  719.   If re-search-replace is successful, the dot is unmoved and the mark is
  720.     left after the last replace.  If it fails, the mark is at the start
  721.     of the search and the dot is left where the failure occurred.
  722.   Returns TRUE if at least one replace was done, FALSE if search-pattern
  723.     was not found.
  724.   See also:  search-replace, qr.mut, re-search-forward, get-matched,
  725.     REGEXP.DOC.
  726. (re-search-reverse regular-expression-search-pattern)    [STRING : BOOLEAN]
  727.   Search from the dot backwards (towards the start of the buffer) for
  728.     text that matches the regular expression.  If a match is found, the
  729.     dot is left before the first matched character (ie the cursor is on
  730.     the first matched character.
  731.   The match algorithm is:
  732.     - Backup a character.
  733.     - Does the RE match the characters after the dot (remember the dot
  734.     is between two characters).  This is the same as (looking-at
  735.     search-pattern).
  736.       Yes:  done, leave the dot where it is.
  737.       No:  repeat until a match is found or run into the start of the
  738.     buffer.
  739.   Returns TRUE if a match is found.
  740.   See also:  re-search-forward, search-reverse, search.mut, REGEXP.DOC.
  741. (re-string RE-pattern string)             [STRING STRING : BOOLEAN]
  742.   Test to see if a string matches a regular expression.
  743.   Returns TRUE if it does.
  744.   You can retrieve the matched info with get-matched.
  745.   See REGEXP.DOC for syntax of the pattern string.
  746.   See also: get-matched, looking-at.
  747. (region-stats pointer-to-data [mark1 [mark2 [goto-top-mark]]])
  748.                 [BLOB [NUMBER [NUMBER [BOOLEAN]]] : VOID]
  749.   Get stats on the region.  pointer-to-data is a pointer the data area
  750.     that the stats are put into:
  751.     (byte type) (small-int ulcol width height) (int size)  ;; RegionInfo
  752.       type:  1 (dot on same line as mark), 2 (dot above mark), 3 (dot
  753.     below mark).  This is the same info as (compare-dot-and-mark).
  754.       ulcol: upper left column of the region-rectangle.
  755.       width, height:  of the region-rectangle.
  756.       size: Number of bytes in the region.
  757.     Mark1 and mark2 default to the dot (0) and the mark (1).
  758.     If goto-top-mark is TRUE, the dot is moved to the upper left corner
  759.       of the region.  Default is FALSE.
  760.   For example:
  761.     get-region-stats
  762.     {
  763.       (byte type)(small-int ulcol width height)(int size)  ;; RegionInfo
  764.  
  765.       (region-stats (loc type))
  766.       (msg
  767.     (switch type
  768.       1 "Dot and mark on same line."
  769.       2 "Dot above mark."
  770.       3 "Dot below mark."
  771.     )
  772.     " Upper left column:" ulcol
  773.     " Width:" width " Height:" height " Size:" size
  774.       )
  775.     })
  776.   See also: compare-marks.
  777.  
  778. (search-forward search-pattern)                [STRING : BOOLEAN]
  779.   Search from the dot forward for text that matches search-pattern.  If
  780.     a match is found, the dot is left after the last matched character.
  781.   Returns TRUE if a match is found.
  782.   See also:  search-reverse, re-search-forward, search.mut.
  783. (search-replace search-pattern replace-pattern)
  784.                          [STRING STRING : BOOLEAN]
  785.   Search for (from the dot to the end of the buffer) and replace every
  786.     occurrence of search-pattern with replace-pattern.  search-forward is
  787.     used to search for a match.  Matched text is replaced verbatim with
  788.     replace-pattern.
  789.   If search-replace is successful, the dot is unmoved and the mark is
  790.     left after the last replace.  If it fails, the mark is at the start
  791.     of the search and the dot is left where the failure occurred.
  792.   Returns TRUE if at least one replace was done, FALSE if search-pattern
  793.     was not found.
  794.   See also: re-search-replace, qr.mut, search-forward.
  795. (search-reverse search-pattern)                [STRING : BOOLEAN]
  796.   Search from the dot backwards (towards the start of the buffer) for
  797.     search-pattern.  If a match is found, the dot is left before the
  798.     first matched character (ie the cursor is on the first matched
  799.     character.
  800.   The match algorithm is:
  801.     - Backup a character.
  802.     - Does search-pattern match the characters after the dot (remember
  803.     the dot is between two characters).
  804.       Yes:  done, leave the dot where it is.
  805.       No:  repeat until a match is found or run into the start of the
  806.     buffer.
  807.   Returns TRUE if a match is found.
  808.   See also:  re-search-forward, search-forward, search.mut, REGEXP.DOC.
  809. (set-mark [mark-id])                       [[NUMBER] : !!!???]
  810.   Set a mark to match the dot.  The default is mark 1 (the mark).
  811.   See also:  create-mark, goto-mark, swap-marks, markring.mut.
  812. (swap-marks [mark1-id mark2-id])        [[NUMBER NUMBER] : NUMBER]
  813.   Exchange the locations that two marks point to.  If you (swap-marks 0
  814.     1) (the default case, same as (swap-marks)), the dot will move to
  815.     where the mark was and vice versa.  Doing it again will return the
  816.     marks to their original values ie (swap-mark a b)(swap-mark a b) is
  817.     a no op.  If you are moving the dot, the other mark must be valid
  818.     (ie have been set).  Remember that clear-buffer resets all marks
  819.     (except the dot).  If you do this, your program will die but ME will
  820.     be OK.
  821.   See also: goto-mark
  822. (sysvar sysvar-name [value])            [STRING [NUMBER] : NUMBER]
  823.   Access or set a sysvar.  This enables a program to give the user
  824.     access to sysvars.
  825.   Example:
  826.     (string sysvar-name 50)(sysvar-name "HELP")
  827.     (sysvar sysvar-name) gets the current value of HELP and 
  828.     (sysvar sysvar-name 0) sets it to zero.
  829.   See also: sysvar.mut for coding examples.
  830.  
  831. (to-col column)                         [NUMBER : NUMBER]
  832.   Insert space until the dot is at column.  If the dot is at or past
  833.     column, nothing happens.
  834.   Returns column.
  835.   If the sysvar tab-stops is zero then tabs and blanks are used,
  836.     otherwise only blanks are used as space.
  837.  
  838. (update [update-the-screen])                [[BOOLEAN] : VOID]
  839.   If update-the-screen is TRUE or not passed in, hard refresh the
  840.     screen.  Does not affect the minibuffer.  Different from
  841.     (refresh-screen) in that the refresh occurs now, rather than waiting
  842.     for the program to end.
  843.   If update-the-screen is FALSE, just sync the buffer and window.
  844.   Forces the current window dot to match the current buffer dot IF the
  845.     current window is displaying the current buffer.
  846.   Notes:
  847.     Keys in the typeahead buffer will keep the refresh from completing
  848.       (ME2 will finish up later when it has more time).
  849.     Refreshing the screen usually takes a long time (from the computers
  850.       point of view anyway).
  851.     It is important to realize that windows and buffers are independent.
  852.       Changing a buffer does not mean that a window displaying the
  853.       buffer always reflects those changes.  This is usually only a
  854.       problem when a program wants a window displaying a buffer to track
  855.       the changes the program is making to that buffer.  Here are the
  856.       rules for programs:
  857.         - Windows and buffers have their own dots.  Changes to a buffer
  858.       dot does not change the window dot.
  859.     - If you make changes to a buffer and then want to make changes
  860.       to the window displaying that buffer, you usually want to do a
  861.       (update FALSE) after the buffer changes and before the window
  862.       changes.  If you don't do this, the window dot will be in a
  863.       different place than the buffer dot and the window probably
  864.       won't be showing what you expected.  Make sure the current
  865.       window is displaying the buffer you are changing.
  866.   See also: current-buffer, current-window.
  867.  
  868. (window-height n [new-height])             [NUMBER [NUMBER]: NUMBER]
  869.   Return the height of the nth window (n == -1 means current window).
  870.   Note that the height does not include the mode line.  If there is only
  871.     one window then
  872.     (window-height -1) == (window-height 0) == (- (screen-length) 1).
  873.   If new-height, then resize the window to the new size (if there is
  874.     more than one window).
  875. (window-ledge n [left-edge])            [NUMBER [NUMBER] : NUMBER]
  876.   Set the left edge of window n.  Returns the current or new value.  If
  877.     n == -1, the current window is used.  The window will display only
  878.     the text starting at column left-edge.
  879.   If horizontal-scroll is enabled and setting window-ledge causes the
  880.     cursor to move off screen, the display routines will reset the left
  881.     edge so that the cursor is on screen.  Turning off horizontal-scroll
  882.     will prevent this.
  883.   With this command you can scroll windows manually (ie without using
  884.     the cursor) (see wscroll.mut).
  885.   The current screen column can be calculated by:
  886.     (- (current-column)(window-ledge -1))
  887.   See also: horizontal-scroll.
  888. (window-row)                            [zip : NUMBER]
  889.   Return the row the dot is on in the current window.  The top row of a
  890.     window is 1.  Note that this is not the screen row (unless the
  891.     current window is the top most one).
  892.   Note:  It is the display routines that figure out the window-row.  If
  893.     called when the display is out of sync (such as a program doing
  894.     display manipulation) this could very well be incorrect.  update can
  895.     force a display sync.
  896. (windows)                            [zip : NUMBER]
  897.   Return the number of windows on the screen.
  898.   See also: current-window.
  899.  
  900. (yesno prompt)            [STRINGs|NUMBERs|BOOLEANs|VOIDs : BOOLEAN]
  901.   Show the prompt (with " [y/n]? " appended) and wait for [Y, y, N, or n]
  902.     CR to be typed.  Returns TRUE on Y or y.  The program aborts on ^G.
  903.     Simular to (ask).
  904.   Notes:
  905.     If not interactive (ie the user is not asked), only "y" or "Y" will
  906.       return TRUE.
  907.     Use (ask-user) to force user prompting.
  908.     See (ask) for potential problems.
  909.  
  910. ========================================================================
  911. ==        SYSTEM VARIABLES (sysvars)                  ==
  912. ========================================================================
  913. System vars are used like any other var - (sysvar) returns its value and
  914.   (sysvar value) sets it to value.
  915. Most sysvars are global - they effect all buffers, windows, etc.  Some
  916.   sysvars are buffer local - they only effect a single buffer.  When you
  917.   set a local sysvar, it is set for the current buffer.  If you want to set
  918.   these to something other than the default for every buffer, do so in
  919.   buffer-created-hook.
  920. Unless otherwise noted, all sysvars are global.
  921.  
  922. (HELP [help-level])    Set the help level           [[NUMBER] : NUMBER]
  923.   (HELP) returns the current setting.
  924.   (HELP n) sets the level to n and returns n.
  925.   Help level:
  926.     0 : no help
  927.     1 : gimme help (if you make typo in (ME-command)
  928.     (describe-bindings) will be executed).
  929.   Initial value: 1
  930.  
  931. (beeper [volume])                       [[NUMBER] : NUMBER]
  932.   Now and then ME will beep at you.  This annoys some people.  You can tell
  933.     ME to shut up by setting beeper to 0.  Setting it to nonzero restores
  934.     the gift of gab.
  935.   Initial value: 1
  936.  
  937. (case-fold-search [ignore-case])               [[NUMBER] : NUMBER]
  938.   Affects searching (query-replace, search-forward, search-reverse).
  939.   If 1, case is ignored.
  940.   Initial value: 1
  941. (complete-key [keycode])                   [[NUMBER] : NUMBER]
  942.   This is the keycode that controls command completion.
  943.   It is initialized to space (32).
  944.   (complete-key) returns the current value.
  945.   To change it, use the keycode.  See get-key.
  946.   For example:
  947.     To set the complete key to tab (C-I), use (complete-key 0x149) or
  948.       (complete-key 329).
  949.     For space, use (complete-key 32).
  950.     For control A (C-A), use (complete-key 321).
  951.  
  952. (horizontal-scroll [step-size])                   [[NUMBER] : NUMBER]
  953.   This sysvar controls horizontal scrolling - moving text left and right
  954.     on the screen.  If 0,  horizontal  scrolling is disabled,  otherwise
  955.     the horizontal  scrolling rate is set to step-size.  When the screen
  956.     has to scroll, it will move in chunks in order to reduce the  amount
  957.     screen   thrashing.  Change  it  to  best  suit  your  hardware  and
  958.     preferences.
  959.   The range for step-size is [0 : screen-width).  If you set it outside
  960.     of this range, you are asking for many unpleasant surprises.
  961.   See also: window-ledge.
  962.  
  963. (modeline-color [color])                   [[NUMBER] : NUMBER]
  964.   Change the the mode line color.
  965.   Note that the color values are display dependent.
  966.   See also: text-color, ERRATA.DOC.
  967.  
  968. (overstrike [value])                       [[NUMBER] : NUMBER]
  969.   Overstrike is the mode opposite of insert (the default mode).  Overstrike
  970.     mode is very much a bag on the side of ME and ment only for occasional
  971.     use.
  972.   The following are different in overstrike mode:
  973.     - The tab key is disabled but you can still set the tab stops.
  974.     - <CR> sends you the start of the next line.
  975.     - Backspace is the same as backward-character.
  976.     - The mode line.
  977.     - self-insert don't, they overstrike.
  978.   If you wish to have overstrike toggled by the insert key, put the
  979.     following into your me2.mut:
  980.     (defun toggle-overstrike { (overstrike (- 1 (overstrike))) })
  981.     (bind-to-key "toggle-overstrike" "F-G")
  982.   Initial value: 0
  983.  
  984. (screen-length [new-screen-length])               [[NUMBER] : NUMBER]
  985.   Change the size of the physical screen.  This allows the same ME code
  986.     to run on different size screens.
  987.   For example, say ME came  configured  for a HP150 (which has 24 screen
  988.     lines) and you wanted to run it on a HP110 (which has 16 lines).  To
  989.     change  the   screen   size:  (screen-length   16).
  990.   If you need to use this often, put it in you me2.mut file.
  991.   Range: [3 : 400].  If you change this to be longer that the screen
  992.     really is, it is hard to edit.
  993.   See also: ERRATA.DOC file.
  994. (screen-width [new-screen-width])               [[NUMBER] : NUMBER]
  995.   Change the physical screen width.
  996.   Range: [15 : 500]
  997.  
  998. (tab-stops [tab-size])    Local                   [[NUMBER] : NUMBER]
  999.   If given an argument then set the tab stops to every nth column.  This
  1000.   is a buffer local variable.
  1001.     If n == 0 use the tab character.
  1002.     If n  > 1 use spaces to simulate the tab character.
  1003.   Initial value: 0
  1004.  
  1005. (text-color [color])                       [[NUMBER] : NUMBER]
  1006.   Change the the text color.
  1007.   Note that the color values are display dependent.
  1008.   See also: modeline-color, ERRATA.DOC.
  1009.  
  1010. (word-wrap [wrap-column])    Local               [[NUMBER] : NUMBER]
  1011.   Setting word-wrap > 0 turns it on, 0 turns it off.
  1012.   Initial value: 0
  1013.   When ME decides it is time to word wrap, it does a (exe-key "^M")
  1014.     which executes whatever is bound to the Enter key.  This also
  1015.     provides a hook if your program wants to do something at that time.
  1016.   This is a buffer local variable.
  1017.  
  1018. ========================================================================
  1019. ==        Hooks                              ==
  1020. ========================================================================
  1021.  
  1022.    Hooks are Mutt programs that are called by ME when it thinks somebody
  1023. else might be interested in what its about to do.  They allow the Mutt
  1024. programmer to modify ME's behavior.  If a hook is not defined, it is not
  1025. called (ie ME doesn't really care if you don't want to tell it what to
  1026. do).
  1027.  
  1028.    Note:  There may be more than one routine that is sharing the hook
  1029. call.  See the hook support in hook.mut (documented in PACKAGE.DOC).  If
  1030. you want your code to be a "good citizen" and interact "nicely" with
  1031. other Mutt code (that uses hooks), it is important that you use
  1032. (register-hook).  me2.h has the constants used by register-hook.
  1033.  
  1034. For examples of how hooks are used, see hook.mut and alamode.mut.
  1035.  
  1036. (buffer-created-hook)                           [zip : zip]
  1037.   This is called when a buffer is created and allows a Mutt program to
  1038.     set up a buffer.
  1039.   Notes:
  1040.     If you switch buffers, you should switch back so that other routines
  1041.       sharing this hook will have the correct current buffer when they
  1042.       are called.
  1043.     Register with
  1044.       (register-hook BUFFER-CREATED-HOOK name-of-your-routine).
  1045.   BUGS:
  1046.     Does not get called for "*scratch*" (the default buffer created when
  1047.       ME starts up) because me2.mco has not been loaded yet.
  1048.     If you want it called for *scratch* then put (buffer-created-hook)
  1049.       into the load time code of me2.mut.  Note that if you delete
  1050.       *scratch* in the MAIN of me2.mut then you will not need to do this
  1051.       because *scratch* will be recreated if no other buffers exist.
  1052.       Also, if you read in a files, buffer-created-hook will be called.
  1053.   See also:  create-buffer, ibuffer-created-hook.
  1054.  
  1055. (enter-ME-hook)                               [zip : zip]
  1056.   When ME starts up and opens the display, it calls this hook.  For
  1057.     example, (shell-command) calls this after the shell command is run
  1058.     and returns control to ME.
  1059.   Note:
  1060.     This is not called when ME is first run because it would be called
  1061.       before any Mutt programs were loaded.  If you need that
  1062.       functionality, do it with MAIN routines.
  1063.     Register with (register-hook ENTER-ME-HOOK name-of-your-routine).
  1064.   See also: leave-ME-hook.
  1065.  
  1066. ibuffer-created-hook                           [zip : zip]
  1067.   This is called when a interactive buffer is created and allows a Mutt
  1068.     program to set up a buffer.  Interactive buffers are those buffers
  1069.     ment for human interaction.  Since most Mutt buffer-created code
  1070.     only cares about interactive buffers (why set a buffer mode if
  1071.     nobody will ever use it?) and lots of non-interactive buffers are
  1072.     created, using this hook will reduce work ME has to do (and a few
  1073.     other things that I'm having a hard time explaining).
  1074.   This is not a real hook!  It is never called.  You can only get access
  1075.     to this functionality if you use register-hook.
  1076.   Notes:
  1077.     If you switch buffers, you should switch back so that other routines
  1078.       sharing this hook will have the correct current buffer when they
  1079.       are called.
  1080.     Register with
  1081.       (register-hook IBUFFER-CREATED-HOOK name-of-your-routine).
  1082.   See also:  buffer-flags, buffer-created-hook, iread-buffer-hook.
  1083. iread-file-hook                               [zip : zip]
  1084.   This hook is called after a file has been read into the current
  1085.     buffer and the current buffer is interactive.
  1086.   The dot is at the beginning of the buffer.
  1087.   This is not a real hook!  It is never called.  You can only get access
  1088.     to this functionality if you use register-hook.
  1089.   Notes:
  1090.     Register with (register-hook IREAD-FILE-HOOK name-of-your-routine).
  1091.   See also:  read-file-hook and ibuffer-created-hook.
  1092.  
  1093. (key-pressed-hook key)                        [NUMBER : zip]
  1094.   This is called when the user presses a key in the main loop (ie
  1095.     key-pressed-hook is not called from the following:  get-key,
  1096.     exe-key, anything that queries the user in the mini buffer).  The
  1097.     key is passed to the hook.  See get-key for the format of a key.
  1098.     After the hook has finished, the key is executed.
  1099.   Notes:
  1100.     This hook is not supported by register-hook.  It really slows things
  1101.       down to do so and is not used much.
  1102.   For example:
  1103.     If the user presses "a", (key-pressed-hook 0x61) is called and then
  1104.       "a" is inserted.
  1105.     Pressing ^X^F causes (key-pressed-hook 0x546) to be called.  After
  1106.       the hook returns, visit-file is called.  Any keys pressed while in
  1107.       visit-file will NOT trigger the hook.
  1108.   See also: key-pressed, saveall.mut and abbrev.mut for examples.
  1109.  
  1110. (leave-ME-hook)                               [zip : zip]
  1111.   Called when the display is being closed in preparation for leaving ME.
  1112.     This is when you quit ME or do something with a shell.
  1113.   Notes:
  1114.     Register with (register-hook LEAVE-ME-HOOK name-of-your-routine).
  1115.   See also: enter-ME-hook.
  1116.  
  1117. (modeline-hook)                            [zip : STRING]
  1118.   This hook is called when a window needs a new modeline.  Whatever the
  1119.     hook returns is put into the modeline.  The last character of the
  1120.     return value is repeated to the end of the modeline.
  1121.   For example:
  1122.     (defun modeline-hook
  1123.            { (concat "ME is editing " (buffer-name -1) " -") })
  1124.     If the current buffer is foo, then the modeline line will look like:
  1125.       "ME is editing foo --------------------------------------"
  1126.   Notes:
  1127.     The modelines for windows are not updated until ME thinks that the
  1128.       modeline needs to be updated.  A good way to do this for a buffer
  1129.       is:  (buffer-flags -1 Mode).
  1130.     The last character is repeated because it makes life easier on the
  1131.       hook (it doesn't have to know about the physical display).
  1132.     Not supported by register-hook.  It doesn't make sense to chain this
  1133.       hook.  If you need to have your own modeline for a buffer, do it
  1134.       with a buffer variable (see modeline.mut).  If you don't like the
  1135.       modeline format, change modeline.mut.
  1136.   See also: modeline.mut for examples.
  1137.  
  1138. (process-hook pid OUTPUT-STDOUT text)              [NUMBER 1 STRING : ]
  1139. (process-hook pid OUTPUT-STDERR text)              [NUMBER 2 STRING : ]
  1140. (process-hook pid PROCESS-DONE  exit-status)          [NUMBER 0 NUMBER : ]
  1141. (process-hook pid ERROR        error-code)          [NUMBER 3 NUMBER : ]
  1142.     where PROCESS-DONE == 0, OUTPUT-STDOUT == 1, OUTPUT-STDERR == 2,
  1143.       ERROR == 3.
  1144.   This hook is used by external processes (created by create-process)
  1145.     talk to Mutt programs.
  1146.   Since multiple processes can be running, you need to use the hook
  1147.     management facilities in hook.mut so that other Mutt programs can
  1148.     manage their own processes.
  1149.   Remember the id of the process you create so that you can tell if the
  1150.     hook is for you.
  1151.   ERROR codes are:
  1152.     CS_ERROR_SERVER_DIED 0
  1153.       For some reason, the compute server is going to stop running very
  1154.         soon.
  1155.     CS_ERROR_PROTOCOL     1
  1156.       ME sent garbage to the compute server.
  1157.     CS_ERROR_READ     2
  1158.       ME read garbage from the compute server.
  1159.     All these errors result in all processes terminating, not just
  1160.       yours.  You will have to start over and recreate them.  If you see
  1161.         an ERROR event,  ignore the pid and treat handle the error
  1162.     because this is the last event your pid will get (until it is
  1163.     recreated).
  1164.   Notes:
  1165.     Register with (register-hook PROCESS-HOOK name-of-your-routine).
  1166.   See also:  create-process, hook.mut, compile.mut, COMSERVER.DOC.
  1167.  
  1168. (read-file-hook)                           [zip : zip]
  1169.   This hook is called after a file has been read into the current
  1170.     buffer.
  1171.   The dot is at the beginning of the buffer.
  1172.   Notes:
  1173.     Register with (register-hook READ-FILE-HOOK name-of-your-routine).
  1174.   See also:  visit-file and read-file (in ME2.DOC).
  1175.  
  1176. ========================================================================
  1177. ==        Miscellaneous                          ==
  1178. ========================================================================
  1179.  
  1180. Initialization file (me2.mco)
  1181.      ME has an initialization file "me2.mco".  See (load) in ME2.DOC
  1182.   for where this is loaded from.
  1183.  
  1184.      Note that if there is an initialization file and it loads OK, ME
  1185.   does not process the command line in any way.  This means that
  1186.   me2.mut can process argv in anyway it wants to.  It also means it has
  1187.   to read in any files the user stuck there for editing.  You can create
  1188.   your own command line options, read all the files in at once, read the
  1189.   files one at a time, etc.
  1190.