/* TEACH-EMACS-FUND-4, EMACSSRC>EMACS*, ENVIRONMENTS AND TOOLS, 06/30/86
/* Tutorial file for EMACS "fundamental" mode - file 4 of 4
/* Copyright (c) 1986, Prime Computer Inc., Natick, MA 01760

You are looking at Part 4 of the EMACS tutorial for fundamental mode.  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-FUND-1, 2 and 3 first.


This tutorial follows the conventions of TEACH-EMACS-FUND-1 and
TEACH-EMACS-FUND-2  -- you are  expected  to  type  {CTRL-V}  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 {CTRL-N}{CTRL-D} thirty
times, you can  define a keyboard macro to execute {CTRL-N}{CTRL-D}
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  type
{CTRL-X}( followed  by  the  commands  you  want  the  macro to execute.  Each
command is executed as you type it so you can see its  effect  on  your  text.
When you've finished defining the macro, just type {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, type in 5 spaces, and then move the cursor down to 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 type {CTRL-X}(
   -- that's "CONTROL-X open parenthesis".  The notation "{Macro}" should
   appear on the mode line.


>> Next, type {CTRL-A} to move the cursor to the beginning of the line.
   Then enter 5 blank spaces.


>> Now, type {CTRL-N} to move the cursor down to the next line.


>> Finally, type {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:


>> Type {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, type {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 {ESC}X expand_macro command.  You should do this  in
a separate buffer.  Try that now:


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


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


>> Now type {ESC}X expand_macro {RETURN}.


>> When EMACS prompts you for a name, type "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 {CTRL-X}{CTRL-W} to save your macro in a file.   When  prompted  for  a
   filename, type "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 containing your macro "practice", type
   {ESC}X PL .  The message "PL completed" will appear at the bottom.
   To use your macro, type {ESC}X practice {RETURN} .  This macro
   will remain in EMACS's set of commands until you exit.


Loading a Saved Macro
-----------------------

When you enter EMACS at a later date and wish to use the macro (or macros)
defined in your file "my-macros.em", you can load the file in two different
ways.  One way - the load_pl_source command - is to cause EMACS to load and
interpret the file containing the source code for the macro when you want to
use it.  Another way - the load_compiled command - is to load a "fasload" file,
which you have created earlier via the dump_file command.  Fasload files can be
loaded into the system more quickly.


Loading an Original File of Source Code
---------------------------------------

The {EXC}X load_pl_source command loads a file of source code into a buffer and
then runs the PL command on it.  It prompts you for the pathname of the file
you want loaded and tells you when it's loaded.  Once the source code is
loaded, you can execute functions as described above.  You can keep the source
code for as many different functions as you like in one file.


Creating a FASLOAD File
-----------------------

To create a fasload file, you must go to the file containing your macro's
source code and then type the {ESC}X dump_file command.  This command compiles
the source code and places it in a new file ending in ".efasl".  For example,
if you compile the function "practice" which resides in the file
"my-macros.em", your FASLOAD file would be called "my-macros.efasl".

Try creating a FASLOAD file now:


>> First, switch to the buffer "practice".  Now, type
   "{ESC}X dump_file {RETURN}".


Your directory should now contain a file called "my-macros.efasl".  To load it,
you can  use the {ESC}X load_compiled command.  It prompts you for the name of
the fasload file you want loaded.  Do that now.


>> Type "{ESC}X load_compiled {RETURN}".  When prompted for a filename,
   enter  "my-macros".


Once you have created a macro file, whether it's just a source file or a
fasload file, you can automatically load the file when you invoke EMACS by
using the -ULIB option.  The command to invoke EMACS would look like:

   OK, emacs FILENAME -ttp TERMINAL_TYPE -noxoff -ulib PATHNAME

where PATHNAME is the name of your macro file.  You can use a full pathname to
your macros file.  If you don't include .EFASL in this pathname, EMACS will
choose the .EM file by default.


Executing a Saved Macro
-----------------------

Whatever way you chose to load your macro, it should now be loaded into the
system.  If you want to execute it, you can enter "{ESC}X practice".

If you're wondering why you should bother to go through the steps of creating a
fasload file, the answer is that it loads a lot faster than the  original  file
of source code does.  If you plan to use a macro frequently, it's worthwhile to
create  the  fasload  file so you can load it quickly when you need it.  If you
won't use the macro very much, you can save space by not creating  the  fasload
file  and  then  waiting a bit longer to load the original source code when you
need to use it.


Binding a Macro to a Key
------------------------

If you plan to use your macro often, you can bind it  to  a  key  to  make  it
easier to execute.  You can do this with the {ESC}X set_permanent_key command.
For example,  if you wanted to be able to execute your macro by typing {ESC}J,
you could use this command to do it.

{ESC}X set_permanent_key first  prompts  you  for  a  keypath,  for  instance,
"{ESC}J", and then for a command name, in this case, "practice".

Once you've  issued  this  command,  you can execute your macro using the keys
you've specified in any buffer during the current editing  session  only.   If
you want to be able to use these keybindings 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 {ESC}X 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 type "{ESC}X set_permanent_key" again,  but  this  time,  bind
   your macro to {ESC}J.


Now, any  time  you  type  {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 type 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         {ESC}X expand_macro

o Load current buffer into EMACS        {ESC}X pl

o Execute the macro                     {COMMAND MODE} macro-name

o Bind macro to key                     {ESC}X set_permanent_key
   (optional)

o Add keybinding to source code
   (optional)

o Create "fasload" file                 {ESC}X dump_file
   (optional)

o Load macro source code                {ESC}X:  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-FUND-4:


 {CTRL-X}(                        Begins macro definition

 {CTRL-X})                        Ends macro definition

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

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

 {ESC}X pl                        Interpret current buffer into EMACS system

 {ESC}X set_permanent_key         Binds specified function  to  specified  key
                                  path

 {ESC}X dump_file                 Creates a fasload file from the buffer

 {ESC}X 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.

 {ESC}X load_pl_source            Loads and compiles specified file of source
                                  code.



This is the end of the EMACS fundamental mode 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 Reference Guide                  IDR5026
     EMACS Extension Writing Guide          IDR5025
