/* TEACH-EMACS-SUIX-4, EMACSSRC>EMACS*, Environments group, 09/11/84
/* EMACS Tutorial for Standard User Interface with eXtensions - file 4 of 4
/* Copyright (c) 1984, Prime Computer Inc., Natick, MA 01760

You are looking at Part 4 of the EMACS tutorial for the standard interface
with extensions.  This module will teach you the following EMACS functions:

     Create and use keyboard macros
     Bind keys to a macro
     Create a fasload file

This tutorial assumes that you are comfortable with basic EMACS commands
and have a basic understanding of the way EMACS uses files and buffers.  If
this is not the case, you should work through TEACH-EMACS-SUIX-1, 2 and 3 first.


This tutorial follows the conventions of TEACH-EMACS-SUIX-1 and
TEACH-EMACS-SUIX-2  -- you are  expected  to  press  {NEXT PAGE} at the end of
each screen and follow instructions preceded by a >>.

Remember that you can use  the  search  commands  to  refer  to  the  "Command
Summary" sections if you want information about commands quickly.


KEYBOARD MACROS
---------------

A keyboard  macro  is  an  EMACS  command that you define yourself using other
EMACS commands.  It is actually a sequence of commands that are saved together
so you can execute them later with a single command.

Keyboard macros are useful when you discover that you're  going  to enter the
same sequence  of  commands  over  and  over  again to perform some task.  For
instance, if you find that you are about to enter {DOWN ARROW}{DELETE CHAR} 30
times, you can  define a keyboard macro to execute {DOWN ARROW}{DELETE CHAR} and
then give the macro an argument to repeat its execution the correct number of
times.

Keyboard macros are useful for performing specific tasks in  EMACS.  Since
they are internally represented in the EMACS command language (PEEL), they
can be used as a basis for writing general or more intelligent EMACS
functions.  The "EMACS Extension Writing Guide" explains how to do this.


Defining a Keyboard Macro
-------------------------

Defining a keyboard macro is  very  simple.   All  you  have  to  do  is  enter
{CTRL-X}( followed  by  the  commands  you  want  the  macro to execute.  Each
command is executed as you enter it so you can see its  effect  on  your  text.
When you've finished defining the macro, just enter {CTRL-X}).

Try defining  a  simple  keyboard  macro  now.   Suppose  you want to indent 6
consecutive lines 5 spaces.   You  would  have  to  move  the  cursor  to  the
beginning of  a  line, enter in 5 spaces, and then move the cursor down to the
next line in order to repeat the process.  Go ahead and do that:


>> First position to this line and then enter {ESC}2 {CTRL-L} to move this
   line and the cursor to the top  of the screen.  Then enter {CTRL-X}(
   -- that's "CONTROL-X open parenthesis".  The notation "{Macro}" should
   appear on the mode line.


>> Next, press {BEGIN LINE} to move the cursor to the beginning of the line.
   Then enter 5 blank spaces.


>> Now, press {DOWN ARROW} to move the cursor down to the next line.


>> Finally, enter {CTRL-X}) to end the macro definition.


You've now defined a simple keyboard macro.  It has been  executed  once,  but
how do  you  execute  it  again?  Use the {CTRL-X}E command.  It executes your
most recently defined keyboard macro at point.   You  can  give  {CTRL-X}E  an
argument like  any  other  EMACS  command.  Do that now.  Since you've already
executed the macro once, you need to execute it 5 more times:


>> Enter {ESC}5 {CTRL-X}E and watch EMACS indent the next five lines at the top
   of your screen.

This time, try defining your own macro.  Since the example you just tried  was
a very  simple one, try something a little more complicated this time.  If you
make a mistake at any time, enter {CTRL-X}) immediately and then start over.


Expanding a Macro
-----------------

You know how to execute the most recent macro you've defined  with  {CTRL-X}E,
but how do you save it so it can be used any time?  It's very easy.

The first  step  to  saving  a macro is to expand the commands that make it up
into source code with the {COMMAND MODE} expand_macro command.  You should do
this  in a separate buffer.  Try that now:


>> First, divide your screen into two windows using {2 FILE ON/OFF} so you can
   refer to these instructions while you're working with the macro.  (Remember
   that you can  use {OTHER FILE} to move back and forth between windows and
   {2 FILE ON/OFF} when you're ready for one window again.)


>> Next, move to the buffer in the bottom window.

>> Now type {COMMAND MODE} expand_macro {RETURN}.

>> When EMACS prompts you for a name, enter "practice" {RETURN}.


EMACS will then expand your macro into a function called "practice" and insert
its source code into the current buffer at point.  (If you know the computer
language Lisp, you'll notice that the PEEL source code is similar to it.)

Once you  have  the source code for your function in a buffer, you should save
it in a file for future use.  Do that now:


>> Use {WRITE FILE} to save your macro in a file.   When  prompted  for  a
   filename, enter "my-macros.em".


You now  have  a  macro called "practice" saved in a file called
"my-macros.em".  You can now create additional keyboard macros without losing
this one.


The PL command
--------------

Although EMACS has stored your macro in a file, it has not yet added this
new function into its set of available commands.

>> While in the window con whenever you've loaded the macro,
you can  incorporate  these  bindings into the source code of the macro before
you save it.  We'll cover the latter in a moment.

As the keys {ESC} and {CTRL} have special meanings to EMACS, you are required
to use special symbols to represent the {ESC} and {CTRL} keys. They are as
follows:

     ^     represents the {CTRL} key

     ^[    represents the {ESC} key


Also, if  you're  binding  a  function to an ESCAPE sequence, you must use the
"set_permanent_key" command twice -- once for uppercase letters and  once  for
lowercase letters.

In the following section of examples, do not actually type in the " characters.
They are there only to delimit the actual characters you ARE to type.  The
actual number of characters you are expected to type in will be written here.

Now try it:


>> Type {COMMAND MODE} set_permanent_key {RETURN}.  When asked for a keypath,
   type in the three characters "^[j" (that's ^ [ j and then {RETURN}).  When
   asked for a command name, type "practice {RETURN}".


Your macro is now bound to {ESC}j.  You still need to bind it to {ESC}J.


>> Go ahead and enter "{COMMAND MODE} set_permanent_key" again, but this time,
   bind your macro to {ESC}J.


Now, any  time  you  enter  {ESC}J  (in upper or lowercase) during this editing
session, your macro will be executed.


Adding a Keybinding to Macro Source Code
----------------------------------------

If you want to add a keybinding to  the  source  code  to  make  it  effective
whenever the  function is loaded, add the following line of source code to the
end of the file containing your macro.  Substitute the  appropriate  arguments
for "keypath"  and  "commandname";   otherwise enter the source code exactly as
written, including the spaces AND QUOTATION MARKS:

     (set_permanent_key "keypath" "commandname")

For example, if you wanted to add the {ESC}J keybinding to your  macro  source
code, you would add these lines at the end of the file "my-macros.em":

     (set_permanent_key "^[J" "commandname")

     (set_permanent_key "^[j" "commandname")

Don't forget to save the source file as well as to create a new fasload file.


Summary of Steps to Creating and Saving a Macro
-----------------------------------------------

Here's a  summary  of  the  steps  to  follow for creating and saving keyboard
macros:


Step                                     Commands
----                                     --------

o Create Macro                          {CTRL-X}(
                                        {CTRL-X})

o Execute macro
   (make sure it works)                 {CTRL-X}E

o Expand macro into source code         {COMMAND MODE} expand_macro

o Load current buffer into EMACS        {COMMAND MODE} pl

o Execute the macro                     {COMMAND MODE} macro-name

o Bind macro to key                     {COMMAND MODE} set_permanent_key
   (optional)

o Add keybinding to source code
   (optional)

o Create "fasload" file                 {COMMAND MODE} dump_file
   (optional)

o Load macro source code                {COMMAND MODE}:  load_compiled
                                                     or
                                                         load_pl_source
                                                     or, in PL mode:
                                                         (fasload "filename")


The ability to save macros in a file as well as to bind macro functions to a
key is just the beginning of how you can tailor EMACS to your specific needs.
A macro library provides a basis for a very sophisticated user library.
Remember that by making modifications to the macro library source code using
PEEL, you can greatly enhance your library's capabilities.  Please refer to
the EMACS Extension Writing Guide (IDR5025) for more information.


Command Summary
---------------

Here's a summary of the commands you've learned in TEACH-EMACS-SUIX-4:


 {CTRL-X}(                         Begins macro definition

 {CTRL-X})                         Ends macro definition

 {CTRL-X}E                         Executes most  recently   defined   keyboard
                                   macro

 {COMMAND MODE} expand_macro       Expands most  recent  keyboard  macro   into
                                   source  code  and  places  code  in  current
                                   buffer

 {COMMAND MODE} pl                 Interpret current buffer into EMACS system

 {COMMAND MODE} set_permanent_key  Binds specified function  to  specified  key
                                   path

 {COMMAND MODE} dump_file          Creates a fasload file from the buffer

 {COMMAND MODE} load_compiled      Prompts for the name of an .EFASL file
                                   and loads it

 {ESC}{ESC} (fasload "pathname")   Loads file  of  source  code  specified   by
                                   pathname.  This is the PL equivalent of the
                                   load_compiled command.

 {COMMAND MODE} load_pl_source     Loads and compiles specified file of source
                                   code.



This is the end of the EMACS SUIX tutorial.  If you would like to learn more
about EMACS or need further explanation of a concept or function, please refer
to the following Prime documents:

     EMACS Standard User Interface Guide    DOC7446-192
     EMACS Reference Guide                  IDR5026
     EMACS Extension Writing Guide          IDR5025
