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

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

     Retrieving data from the kill ring
     Moving regions of data
     Searching and replacing
     Using the HELP facility

This tutorial assumes  that  you  have mastered the basic EMACS commands
discussed in TEACH-EMACS-SUI-1.  If you don't feel comfortable using  those
commands, you should go back to TEACH-EMACS-SUI-1 and practice with them
for a while.

Note:  This tutorial follows the conventions of TEACH-EMACS-SUI-1  --  you are
expected to  press {NEXT SCREEN} when you come to the end of each screen and
follow all instructions preceded by ">>".

Press the {NEXT SCREEN} key to continue with this tutorial.



YANKING BACK AND MOVING KILLED TEXT
-----------------------------------

Now suppose  you  kill  something, and then you decide that you want to get it
back?  Well, whenever you kill something bigger than a character, EMACS  saves
it for you.  To yank it back, just press {PASTE}.  Note that you don't have to
be in  the  same  place  to use {PASTE}.  Consequently, this is a good way to
move text around.


>> For instance, press {DOWN} a couple of times to position the cursor at
   the beginning of some line on the screen.  Kill that line with {DELETE LINE}.
   Now press {PASTE} to yank the text back.


>> Next, move the cursor to the beginning of some line and enter {DELETE LINE} 4
   times.  Then press {PASTE} and watch what happens.


If you press several {DELETE LINE}s in a row, the text that is killed is all
saved together so that one {PASTE} will yank back all of the lines.

As we said earlier, you can also use {PASTE} to move text around.


>> Try this now.  Press {DELETE LINE} several times.


Now to retrieve the killed text:


>> Move the cursor to the point where you would like the yanked lines to
   be moved.


>> Press {PASTE}.  Then move the cursor down a few  lines  and  press {PASTE}
   again.  You now see how to move some text.


What do  you do if you have some text you want to yank back, and then you kill
something else?  {PASTE} yanks back the more recent kill.  But  the  previous
text is  not  lost!   You  can get back to it using the {ESC}Y command.  After
you've pressed {PASTE} to get the most recent kill,  {ESC}Y  will  replace  the
yanked text with the previous kill.

Pressing {ESC}Y again and again will bring in earlier and earlier kills.  When
you have reached the text you are looking for, you can just go away and  leave
it there.   If  you  {ESC}Y  enough times, you come back to the starting point
(the most recent kill).  This happens because EMACS saves the  last  11  kills
that you  make  on  a  stacked ring.  For that reason, it is very difficult to
lose anything that you delete.


>> Play around with {PASTE} and {ESC}Y now.  Kill a line, move around, kill a
   second line.  Then press {PASTE} to get back the second killed line.  Next,
   enter {ESC}Y and it will be replaced by the first killed line.   Enter more
   {ESC}Ys and see what you get.  Keep entering {ESC}Y until the second kill
   line comes back, and then enter a few more.

   If you like, you can try giving {ESC}Y positive and negative arguments.


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

Here's a recap of the killing and yanking commands you've learned so far:

                                                             PT45 template
     {BACKSPACE}        Deletes the character (or WORD)
                        immediately before point

     {DELETE FORWARD}   Deletes the character (or WORD)      {DELETE CHAR}
                        at point

     {DELETE LINE}      Deletes the entire line containing
                        point

     {CTRL-K}           Kills all text from point to end of
                        line

     {PASTE}            Yanks back most recent kill and
                        re-inserts it in your file at point.

     {ESC}Y             Replaces most recent text you've
                        re-inserted with a previous kill.


THE MARK AND THE REGION
-----------------------

So far you've learned how to kill and move characters, words, and lines.   But
what if  you have a large amount of text that you want move or kill?  In
EMACS you do this by defining a region.

A region begins at a place called the mark and ends wherever point is currently
located.  Therefore, to define a region, you must first set a mark and then
move the cursor to the place where you want the region to end.

The {MARK} command sets the mark at point.  After you press {MARK}, you can
move point away, leaving the mark behind you.  If you set the mark and then go
do something else, you may forget where you put the mark later.  To  find  out
where it  is,  you can press {EXCH MK + CRS} (or {CTRL-MARK} on the PT45
template - please label your PT45 template accordingly).  This command
exchanges the mark and the point -- it moves the cursor to where you last sent
the mark.  Notice, however, that the boundaries of the region do not change
since the same area of text is still bounded by a mark and point.  Before
trying to delete this region, press {EXCH MK + CRS} again to reset mark and
point to the original positions.

Once you've  defined a region of text, you can delete it with {CUT REGION} (or
{CUT} on the PT45 template).  EMACS will save this deleted text just like any
other text you kill.  You can always get it back with {PASTE} or {ESC}Y.

Sometimes it is necessary to make a copy of a region instead of moving it.
To do this, mark the region as defined above.  Then, instead of pressing {CUT
REGION}, press {COPY REGION} (or {CTRL-CUT} on the PT45 template - please
label your template accordingly).  This does not remove the defined region, but
places a copy of it into the kill buffer.  To retrieve the region, press
{PASTE}.


>> Move the cursor to the "T" in the word "This" in the  paragraph  above  and
   then press  {MARK}.   Then  move  the  cursor  to the period after the last
   sentence in that same paragraph.


>> Next, press {EXCH MK + CRS} and watch what happens.  Press  {EXCH MK + CRS}
   again and  then press {CUT REGION} to delete the region.  Notice the
   position of the cursor after you press {CUT REGION}.  Finally, press
   {PASTE} to  make  your region reappear at point.


>> Now press {EXCH MK + CRS} again and then press {CUT}.   Notice how the
   same text  is still deleted even though the positions of the mark and point
   have reversed.


>> Now try to copy a region from one place to another using {MARK} and
   point to define the region and then press {COPY REGION}.  Move the
   cursor to a new position for this region and press {PASTE}.


>> Try working with these commands a little more on your own.  They are  among
   the most useful EMACS commands and you should know them well.


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

Here's a list of the commands that deal with regions:

                                                             PT45 template
     {MARK}               Sets a mark at point

     {EXCH MK + CRS}      Exchanges the positions of         {CTRL-MARK}
                          the mark and point

     {CUT REGION}         Deletes the region bounded by      {CUT}
                          the mark and point

     {COPY REGION}        Copies the region bounded by       {CTRL-CUT}
                          the mark and point


SEARCHING AND REPLACING
_______________________

You may  be  wondering  if there are easier ways to move around a file than by
using the cursor moving commands.  Perhaps the easiest way  is  by  using  the
SEARCH commands.   EMACS  allows  you to search forward or backward from point
for the character string you specify.

The SEARCH commands are:

     {FORWARD SEARCH}    Forward Search
     {REVERSE SEARCH}    Reverse Search

When you enter either of these commands, EMACS prompts you at the bottom of the
screen for the string you want to search for.  When you see the  prompt,  enter
the string  followed  by  {RETURN}.   EMACS  will then move point to the first
occurrence of that string that it finds.  If EMACS can't find  that  string  in
the direction you specified, it will respond with an error message.

If you  make  a mistake while entering in a search string, you can use any EMACS
command to correct it before you press {RETURN}.  Also, if you begin entering in
a search string and then decide you don't want EMACS to do the search, you can
press {CTRL-G} to abort the search request.

Try using the search commands now:


>> Enter {FORWARD SEARCH} HOTDOG {RETURN}.  This will put you at the end of this
   file where there are instructions on how to get back.


Notice that  a  forward  search leaves the cursor positioned after the located
string while a reverse search leaves you positioned before it.

When you do a search, EMACS might locate the wrong string.   For  example,  if
you search  for  "the",  what  do  you think the odds are that you'll find the
right occurrence?   Fortunately,  EMACS   "remembers"   any   search   string.
Therefore, to  repeat  a search, all you have to do is press the
{FORWARD SEARCH} or {REVERSE SEARCH} key immediately followed by a {RETURN}.


>> Enter {FORWARD SEARCH} you {RETURN}, then enter just {FORWARD SEARCH}{RETURN}.
   What happens?  After  doing  this  enter  {REVERSE SEARCH}{RETURN} and then
   {REVERSE SEARCH}{RETURN} again.  Where are you now?


One more useful command for searching, as  well  as  editing  in  general,  is
{CTRL-C}.  It causes whatever EMACS command you last entered to be executed
again.  It is particularly useful with commands that take several keystrokes
to complete.  Try it now.


>> Enter {REVERSE SEARCH} EMACS {RETURN} and then press {CTRL-C}.  Now enter
   some  text anywhere on a line followed by {CTRL-C}.  Notice what happens.


Now that you've learned how to move around in a file with the SEARCH commands,
you have  an  easy way to refer back to any commands you may have forgotten in
this tutorial.  Just specify "Command Summary" as a search string,  and  EMACS
will take you back to the list of commands that appears after each section.


REPLACEMENT COMMANDS
--------------------

A very  common  editing  task  is replacing one character string with another.
EMACS gives you two ways to do this.   One  is  by  using  the  {GLOBAL REPLACE}
command.  This  command replaces all occurrences of one character string with a
second character string FROM POINT TO THE END OF THE BUFFER.  (Be careful!)


>> Position the cursor on this line.  Change all occurrences of the character
   string ">>" with "->" by entering the following sequence:

        {GLOBAL REPLACE}>>{RETURN}->{RETURN}.

   Now instead of seeing ">>" for the rest of the file, you will see "->".


Practice this command a few more times if you like.

In many instances, what you really want to do is  see  what  you're  going  to
replace before  it  happens.   The  {QUERY REPLACE}  command allows you to do
this.  It starts the same way as {GLOBAL REPLACE}.  That is, it will prompt you
for  two character strings.  However, after you press the final {RETURN}, things
change.  EMACS goes  to  the  first occurrence of the first string and then
prompts for you to press one of four things:


           {CTRL-G}  Tells EMACS to stop searching and replacing.  Any strings
                     already changed remain changed.

           {SPACE}   Tells EMACS to make the change you specifed and moves  to
                     the next occurrence of the string.

           {RETURN}  Tells EMACS not to  make  the  change  but  to  look  for
                     another occurrence.

           .         Tells EMACS to make this change and then stop searching.


The extent covered by the QUERY REPLACE function is the same as for the GLOBAL
REPLACE function.


>> If you want, try this:  enter {QUERY REPLACE} EMACS {RETURN} emacs {RETURN}
   Don't worry about returning back.  EMACS will do it for you.


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

Here's a list of the commands for searching and replacing:

     {FORWARD SEARCH}   Forward Search

     {REVERSE SEARCH}   Backward Search

     {GLOBAL REPLACE}   Replace one string with another from point to end of
                        the buffer

     {QUERY REPLACE}    Query before replacing from point to end of buffer


HELP COMMANDS
_____________

The final basic EMACS commands you should know about are the HELP commands.
You can  use them at any time to find out how to do something or why something
happened differently than you expected it to.

The {HELP} key is the simplest SUI/SUI help command.  When you press
it, EMACS responds with a menu driven HELP facility.  The first menu
lets you choose between examining a layout of the functions keys or
having a function key described for you.  The operation of {HELP} is
self explanatory.


>> Try pressing {HELP} now and select menu item number 2.  When the second
   menu is displayed, select item 2 to show you a description of the
   {CHAR/WORD} key (or {WORD/CHAR} key on the PT45 template).


>> This HELP command is one of the most useful, so try it again several  times
   with a variety of subjects.


{CTRL-_} ("CONTROL underscore") is the help command for Fundamental Mode.  When
you type it, EMACS responds with the following prompt:

     Help on tap:  C, A, D, L, or ?  for more info

which lists the various help options.  EMACS then  waits  for  you  to  choose
which one  you  want.   If  you want to abort the help request, type {CTRL-G}.
Otherwise, type one of the characters listed in the  prompt.   The  "?"   will
give you a list of what all the other options do.  They are listed below.


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

Once you type {CTRL-_}, you have the following options:


     C  Explains what the command you type does

     A  Lists commands related to subject you specify

     D  Invokes the "Describe" function

     L  Lists last 20 characters you typed

     ?  Summarizes all of above options at top of screen


Three of them -- C, A, and L, are used most often.  Try them  now  to  see  how
they work.


>> First, type {CTRL_} and notice the prompt at the  bottom  of  your  screen.
   Then type C.


>> When you see the "Explain key" prompt, type the {CTRL-F} command.


EMACS will then tell you what this command does at the bottom of  the  screen.


>> Try this command several more times to get explanations of different  EMACS
   commands.  Try  typing  in  commands  that  you  don't  know -- {ESC}L, for
   example, or {CTRL-J}.  What happens?


>> Now type {CTRL-_} and then A.  You'll see the prompt


  Apropos:

       >> Now type the word "delete", followed by {RETURN}.

EMACS will respond with a list of commands at the  top  of  your  screen  that
pertain to deleting text.  Don't worry if this lists types over what's already
on your  screen.   It will disappear when you type your next command.  You can
also use {CTRL-L} to make it disappear.  (Remember, it refreshes your screen.)


>> This HELP command is one of the most useful, so try it again several  times
   with a variety of subjects.


Since this  option  finds  commands  on  the  basis  of their definitions, the
subject you specify may not match the commands you have in mind.  If you don't
get the results you want the first time, don't  give  up.   Try  stating  your
subject in  a  different  way.   If  you  use  "kill"  instead of "delete" for
instance, EMACS will show you a whole new group of commands.


>> Now type {CTRL-_} and then L.


The last twenty keystrokes you've typed  will  appear  at  the  bottom  of  the
screen.   You  may  see  the  notation  "^".  It stands for CONTROL.  This HELP
option is very useful when you've just typed something that's made a change  to
your  text  and you don't know what you did.  When you see a keystroke that you
don't recognize, you can use the C option to find out what it does. (Sometimes,
when you've been using your terminal's function keys, the L option's output  is
not too helpful.)


>> This time, type {CTRL-_L}.  What happens?


You can type the HELP option you want immediately after the  {CTRL-_}  without
waiting for the prompt.


CONCLUSION
__________

This concludes "TEACH-EMACS-SUI-2".


>> If you're here because you searched for the string  "HOTDOG", enter the
   sequence {REVERSE SEARCH} {RETURN} twice.


>> If you would like to practice the functions you have just learned, use
   EMACS to edit the file of your own choosing that you created after
   completing TEACH-EMACS-SUI-1.  Move some of the lines around; search for
   strings; replace strings; and use the HELP facility.


>> If you want to  continue  on  to  TEACH-EMACS-SUI-3  (or  another  file),
   press {FIND FILE} followed  by TEACH-EMACS-SUI-3 (or the name of the other
   file) and {RETURN}.


>> If you want to get out of EMACS and back to PRIMOS, press  {QUIT EMACS}.
   If you see the message:
        "Above list of modified buffer(s) not saved to file(s).  Quit anyway?"
   Enter "YES".


END OF TEACH-EMACS-SUI-2
