mex.1

You are looking at the mex tutorial.  Comments on this document
may be refered to Moshe Braner <braner@tcgould.tn.cornell.edu>.

mex is a text editor based on the original "microEMACS" by Dave Conroy.
The name "mex" (Generally Not the Original Micro Emacs) is meant to
distinguish this version from the numerous other versions of "microEMACS"
that exist now, and to comply with Richard Stallman's request that the
name "EMACS" be reserved for his original full-screen editor.

I use mex daily for all of my work, including program editing, some data
files, shell scripts, letters, and word processing (in combination with
YAFIYGI ("you asked for it you got it") style typesetting software, such as
TeX or troff).  Its strongest advantage is that I can use it on every
system I need to work on.  The source code is written purely in C.  It does
not support GRAPHICAL windows (has text-only output) but it supports the
editing of multiple files in multiple windows.  The edited files must
completely reside in RAM, but the editor can use all available RAM.


[Press Control-V to see the next screen]


The philosophy behind mex is:

	- keep it SMALL (easy on system resources) and SIMPLE (easy
		on the user).

	- make it a powerful PROGRAMMING editor,
		but don't make it do EVERYTHING.

	- retain REDUNDANCY in command invocations to please many
		and reduce mistakes.

	- include built-in instant HELP.

	- make it PORTABLE but use each system's strengths.

	- use FUNCTION KEYS as far as possible.

[Press Control-V to see the next screen --- hope you remember it by now]


The nice features of my version include:

*	The function-key support means little use of control-keys is necessary.
	(The standard control-key command invocations are retained, though.)

*	Horizontal scrolling for long lines (up to 255 chars).

*	All parameter entry requests (e.g., search patterns, file names,
	buffer names...) have intelligent defaults through which one
	can scroll with up-down arrows.  Each can be screen-edited with
	the usual keys (left-right arrows, delete, backspace, etc.).
	This makes for very quick respones with minimal typing.

*	Command line option (default ON in UNIX version) to save all keystrokes
	in a file (flushed every 256 keystrokes).  The file pathname is taken
	from an environment variable.  This is to recover work after a system
	crash.

*	Search patterns can include a '.' wildcard (fits any char), a
	"whitespace" wildcard (^W, fits any amount of whitespace, including
	none), and '!' that means the next char can be anything BUT what
	is in the search pattern.

*	8-bit extended ASCII supported (in ST and MS-DOS versions): preceding
	a key with Alt-A sets the 8-th bit.  Such chars are displayed in the
	extended system font.  In disk files, 8-bit data are read and written
	correctly.  The help facility includes a built-in table of these chars.

*	The MS-DOS version uses DIRECT screen output (courtesy of Turbo C 1.5),
	with a command-line option to force BIOS output in non-100% compatible
	machines.  The latter is fast, the first is even faster.

*	Word wrap and paragraph reformatting.  Margins can be set from
	the command line or inside the editor.

*	The number of rows and columns to use is settable from the command
	line.  Useful for slow over-the-modem use and with windowing terminals.

*	In ST and MS-DOS versions: low-level binary block file I/O, MUCH faster
	than the original microEMACS.

*	In MS-DOS: escape to COMMAND.COM for a shell or for one command.
	In the latter case, the default-entry facilities create a pseudo-
	shell with screen-editing of previous commands, intact across
	separate accesses to this command (Alt-Z).

*	Search for matching brackets, recognising nested (), [], and {}.

And so on.


mex commands generally involve the CONTROL key (sometimes labelled CTRL or 
CTL) or the META key (generally labelled ESCAPE).  Rather than write out META 
or CONTROL each time we want you to prefix a character, we'll use the following
abbreviations:

   ^<chr>   means hold the CONTROL key while typing the character <chr>
            Thus, ^F would be: hold the CONTROL key and type F.

   <Esc> <chr>  means type the ESCAPE key and release it, then type the 
              character <chr>.  The <chr> can be upper or lower case 
              and it will have the same meaning.

		(<Esc> is abbreviated E- in the help screens)

Important note: if you must exit at some point, type ^C.  

Important note:  On microcomputers, function keys are used for command entry
whenever possible.  This tutorial only mentions the Control and Meta
commands, which are also retained in the microcomputer versions.  Check out
the built-in help in your system for function key usage.

This tutorial attempts to help you "learn by doing".  The characters ">>" 
at the left margin of your screen indicate directions for you to try using 
a command.  For instance:

>>  Now type ^V (View next screen) to move to the next screen.
    (go ahead, do it by depressing the control key and V together).

Note that there is an overlap when going from screen to screen; this
provides some continuity when moving through the file.

The first thing that you need to know is how to move around from place to 
place in the file.  You already know how to move forward a screen, with ^V.  
To move backwards a screen, type <Esc> V.

>>  Try typing <Esc> V and then ^V to move back and forth a few times.

>>  Now try pressing <Esc> <Esc>.  This will enter the built-in help facility.
    Then press 'C' to display all the cursor-moving commands.
    The following section gives more details.


BASIC CURSOR CONTROL
--------------------

Getting from screenful to screenful is useful, but how do you reposition 
yourself within a given screen to a specific place?  There are several ways 
you can do this.  One way (not the best, but the most basic) is to use the 
commands previous, backward, forward and next.  As you can imagine these 
commands (which are given to mex as ^P, ^B, ^F, and ^N  respectively) move 
the cursor from where it currently is to a new place in the given direction.  
Here, in a more graphical form are the commands:
 
                          Previous line, ^P
                                  :
                                  :
   Backward, ^B .... Current cursor position .... Forward, ^F
                                  :
                                  :
                          Next line, ^N

You'll probably find it easy to think of these by letter.  P for
previous, N for next, B for backward and F for forward.  These are
the basic cursor positioning commands and you'll be using them ALL
the time so it would be of great benefit if you learn them now.

>> Do a few ^N's to bring the cursor down to this line.

>> Move into the line with ^F's and then up with several ^P's.
   See what ^P does when the cursor is in the middle of the line.

>> If your keyboard has arrow keys, try them.  They might work!

On Unix, lines are separated by a single Linefeed character, which is what
Unix calls a Newline.  On MS-DOS lines are separated by a CR-LF pair.  On
either system, mex will correctly read in either kind of file, and, if
asked to write the file, write it with the line separators standard on that
system.

>> Try to ^B at the beginning of a line.  Do a few more ^B's.
   Then do ^F's back to the end of the line and beyond.

When you go off the top or bottom of the screen, the text beyond
the edge is shifted onto the screen so that your instructions can
be carried out while keeping the cursor on the screen.

>> Try to move the cursor off the bottom of the screen with ^N and
   see what happens.

If moving by characters is too slow, you can move by words.  <Esc> F
(Meta-F) moves forward a word and <Esc> B moves back a word.

>> Type a few <Esc> F's and <Esc> B's.  Intersperse them with ^F's and ^B's.

Notice the parallel between ^F and ^B on the one hand, and <Esc> F and
<Esc> B on the other hand.  Very often Meta characters are used for
operations related to English text whereas Control characters operate on
the basic textual units that are independent of what you are editing
(characters, lines, etc).  For example, <Esc> P and <Esc> N move up and
down by paragraphs.

>> Try a couple of <Esc> P's, and then a couple of <Esc> N's.

Now try ^A and ^E: they move to the beginning and the end of a line.
See how repeated ^A's or ^E's do nothing.

Two other simple cursor motion commands are <Esc> < (Meta Less-than),
which moves to the beginning of the file, and <Esc> > (Meta Greater-than),
which moves to the end of the file.  You probably don't need to try
them, since finding this spot again will be boring.  If you need the
shift key to type a "<", then you must also use the shift key to type
<Esc> <.  Otherwise, you would be typing <Esc> , .

The location of the cursor within the text is also called "point".  To 
paraphrase, the cursor shows on the screen where point is located in
the text.

Like most other commands in mex, these commands can be given
arguments which cause them to be executed repeatedly.  The way you
give a command a repeat count is by typing META and then the digits
before you type the command.  (Remember META is usually called ESCAPE)

For instance, META 8 ^F moves forward eight characters.

>> Try giving a suitable argument to ^N or ^P to come as close
   as you can to this line in one jump.

This also applies to the screen moving commands, ^V and <Esc> V.  When
given an argument, they scroll the screen up or down by that many
screenfuls.  As a special case, typing just ^U is equivalent to <Esc> 4.

>> Try typing <Esc> 3 ^V now.


QUITTING FROM COMMANDS
----------------------

The character in mex used to quit out of all commands which request
input is ^G.  For example, you can use ^G to discard a numeric argument
or the beginning of a command that you don't want to finish.
(You can also use the F2 key on IBM-PC compatibles, and the UNDO key
on the Atari ST.)  In some situations ^C and/or <Esc> are additional
back-out keys.

>> Type <Esc> 100 to make a numeric arg of 100, then type ^G.
   Now type ^F.  How many characters does it move?
   If you have typed an <Esc> by mistake, you can get rid of it
   with a ^G.


INSERTING AND DELETING
----------------------

If you want to type text, just do it.  Characters which you can see, such 
as A, 7, *, etc. are taken by mex as text and are immediately inserted.  
Type <Return> (the carriage-return key) to insert a line separator.

You can delete the last character you typed by typing ^H.  On some
keyboards, there is a dedicated key for creating a ^H.  If so, it is
usually labeled as either <Backspace> or "<--".  <Delete> is a key on the
keyboard, which may be labeled "Rubout" instead of "Delete" on some
terminals.  <Delete> deletes the character directly "under" the current
cursor position.  A ^D has the same effect.

>> Do this now, type a few characters and then delete them by typing
   <Backspace> a few times.  Don't worry about this file being changed,
   as long as you do not press ^Z.

>> Now start typing text until you reach the right margin, and keep
   typing.  When a line of text gets too big for one line on the
   screen, the line of text is "continued" off the edge of the screen.
   mex scrolls the screen over so you can see what you are editing.
   The '$' at the left or right edge of the screen indicates 
   that the current line extends off in that direction.  

>> The following line actually goes off the edge.  Trying typing enough ^F's
   so that you move off the right hand end of this line.  This is a long line.  Note the "$"s at each edge.  Keep typing ^F's and watch where mex decides to scroll the line.  Now, type ^B's until mex decides to scroll the line again.

>> Use ^D's or <Delete>s to delete the text until the text line fits on 
   one screen line again.  The continuation "$" will go away.

>> Move the cursor to the beginning of a line and type <Backspace> (or ^H).
   This deletes the line separator before the line and merges the line onto
   the previous line.  The resulting line may be too long to fit, in which
   case it has a continuation indication.

>> Type <Return> to insert the separator again.

mex has an internal limit of 32768 characters on line lengths.  If you try
to surpass this limit, mex will give you an error message.

Remember that most mex commands can be given a repeat count;  Note
that this includes characters which insert themselves.

>>  Try that now -- type META 8 * and see what happens.

If you want to create a blank line in-between two lines, move to the
start of the second of the two lines and type ^O.

>>  Try moving to a line and typing ^O now.

You've now learned the most basic way of typing something in
mex and correcting errors.  You can delete by words or lines
as well.  Here is a summary of the delete operations:

	^D or <Delete>      delete the character under the cursor
	^H or <Backspace>   delete the character just before the cursor

	<Esc> ^H        kill the word immediately before the cursor
	<Esc> D         kill the next word after the cursor

	^K              kill from the cursor position to end of line

Notice that <Delete> and ^D vs <Esc> <Delete> and <Esc> D extend the parallel
started by ^F and <Esc> F.

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, mex 
saves it for you.  To yank it back, use ^Y.  Note that you don't have to 
be in the same place to do ^Y; This is a good way to move text around.  
Also note that the difference between "Killing" and "Deleting" something 
is that "Killed" things can be yanked back, and "Deleted" things cannot.  
Generally, the commands that can destroy a lot of text save it, while the 
ones that attack only one character, or nothing but blank lines and spaces, 
do not save.

For instance, postion the cursor at the left end of some line on this screen.

>> Do this now, move the cursor and kill that line with ^K.

Note that a single ^K kills the contents of the line, and a second
^K kills the line itself, and make all the other lines move up.  If
you give ^K a repeat count, it kills that many lines AND their contents.

The text that has just disappeared is saved so that you can
retrieve it.  To retrieve the last killed text and put it where
the cursor currently is, type ^Y.

>> Try it; type ^Y to yank the text back.

Think of ^Y as if you were yanking something back that someone took away 
from you.  Notice that if you do several ^K's in a row the text that is 
killed is all saved together so that one ^Y will yank all of the lines.

>> Do this now, type ^K several times.

Now to retrieve that killed text:

>> Type ^Y.  Then move the cursor down a few lines and type ^Y
   again.  You now see how to copy some text.

What happens if you have some text that can be yanked back, and then
you kill something else?  ^Y would yank the more recent kill.

>> Kill a line, move around, kill another line.
   Then do ^Y to get back the second killed line.


FILES
-----

In order to make the text you edit permanent, you must put it in a file.
Otherwise, it will go away when you leave mex.  While you are editing a
file in mex, your changes are actually being made to a private "scratch"
copy of the file, a copy that resides in your computer's short-term memory.
The changes don't become permanent until you "save" the file.  This is so
you can have control to avoid leaving a half-changed file around when you
don't want to.

If you look near the botton of the screen you will see a line that
looks like this:

+* mex -- ESC-? for help -- mex.tut -- File: mex.tut ------------------

Note that mex indicates the name of the file you are currently editing.
This is the name of your own temporary copy of the text of the mex
tutorial; the file you are now editing.  Whatever file you edit, that
file's name will appear in that precise spot.

The commands for finding and saving files are unlike the other commands you
have learned in that they consist of two characters. They both start with the
character Control-X.  There is a whole series of commands that start with
Control-X; many of them have to do with files, buffers, and related things,
and all of them consist of Control-X followed by some other character.  As
with <Esc>, the character is interpreted the same regardless of case.

Another thing about the command for finding a file is that you have to say
what file name you want.  We say the command "reads an argument from the
terminal" (in this case, the argument is the name of the file).  After you
type the command

     ^X ^V   Visit a file

mex will ask you for the file name.  mex tries to guess what name
you might want, and displays it on the screen.  You can edit it with ^F,
^B, ^H, ^D, ^K, and so on.  If mex can think of several possible
names, it will supply them all.  Only one is displayed at any one time,
but you can scroll through them with ^N and ^P.  You should end the name
with the Return key.  After this command, you will see the contents of the
file on the screen.  You can edit the contents.  If and when you wish to
make the changes permanent, issue the command

     ^X S   Save the file

A new version of the file, with the same name, will be created.  The old
version is overwritten, and thus destroyed.  If you want to save the
changed version as a new file, keeping the old version, you must either
make a back-up copy of the old file before you save the new one, or write
the new version out from mex with a new name.  Issue the command:

     ^X ^W   Write the file

and mex will ask you for the new file name.

If you forget to save, edit a different file, and then decide to quit,
mex will remind you that you made changes that have not been saved and
then ask you whether you want to discard them.  (If you don't save them,
they will be thrown away.  That might be what you want!)  You should
answer with a "N" to save them or a "Y" to throw the changes away.

To make a new file, just edit it "as if" it already existed.  Then start 
typing in the text.  When you ask to "save" the file, mex will really 
create the file with the text that you have inserted.  From then on, you 
can consider yourself to be editing an already existing file.

It is easy for you to try out editing a file and then continue with the 
tutorial.  Type:

     ^X B   Use another buffer

followed by a name for the new buffer.  Then type

     ^X ^R  Read in a file to edit

if you want to edit an existing file, or simply type text in to create a
new file.  When you're done editing, save the file (^X S, or ^X ^W if you
need to give it a file name).  Then use ^X B again, to enter yet another
buffer, and use ^X ^R to read in the file that was saved.  Does it look
like what you wanted it to?  Finally, use ^X B to return to this buffer.
Note the name of this buffer below (the buffer name appears just before the
file name).  You can type it in after issuing the ^X B command, or you can
use ^N and ^P to scroll through the existing buffers until you find the
right one, then press <Return>.


SEARCHING
---------

mex can do searches for strings (these are groups of contiguous
characters or words) either forward through the file or backward
through it.  

>> Now type <Esc> S to start a search.  Type the word 'cursor', then <Return>.

>> Type <Esc> S <Return> to find the next occurrence of "cursor".

>> Type <Esc> R for a Reverse search back towards the top of the file.


MACROS
------

mex has a simple but effective facility for automating typing tasks
through the definition of "macros".  A macro in mex is simply a
collection of keystrokes (which may include text and other mex
commands).  This collection may be replayed by issuing the "execute
macro" command, ^X E.  To define a macro, type ^X M.  mex will continue
normal operation,  but all keystrokes will be recorded in the macro.  When
done, type ^X M again.  mex prints a message on the bottom line saying
"[start macro]" or "[end macro]", so you'll know what it's doing.
Only one macro can be defined at any one time, and macros cannot be saved
on disk nor edited.  (This is an area where mex could use some
enhancement).


TEXT REPLACEMENT
----------------

There is no command in mex for "search-and-replace".  Instead, this
can easily be done via a simple macro definition.

>> Type <Esc> S changed <Return>.  Then type ^X M to start a macro definition.
   Then backspace (^H) over the word "changed", and type "altered".
   Follow with <Esc> S <Return> ^X M.  Now type ^X E to execute the macro.
   Repeat ^X E another time.

   Notice how this line has changed: you've replaced
   the word c-h-a-n-g-e-d with "altered" wherever it occurs
   after the cursor, such as here: "changed".

Notice that the macro definition had the search FOLLOWING the editing.
This allows you to examine the found text and decide whether you really
want to change that specific occurrence.  If you do, press ^X E again.
If not, press anything else.  If you are sure you want to do a global
search and replace without checking, you can precede ^X E with a large
numerical argument, e.g., type <Esc> 999 ^X E.


MODE LINE
---------

The bottom line of the screen is known as the communications line.  This
is where mex interactively communicates with you.  You have already
seen how mex prompts you for information (like when searching).  mex
can also report things to you as well.

>> Type ^X = and see what you get in the communications line.

The line immediately above the communications line is called the MODE
LINE. The mode line says something like

+* mex -- ESC-? for help -- mex.tut -- File: mex.tut ------------------

This is a very useful "information" line.

The plus (+) means that you can change the text.  If you press ^X ^E,
you will enter "view-only mode", where you cannot change the file by
mistake, nor can you save it.

The star (*) means that you have made changes to the text.  Right after
you read in or save a file, there is no star.

The buffer name is the name mex gave to the buffer, and it is usually
related to the filename. You already know what the filename means -- it
is the name used by the operating system to identify the file you have
edited, when stored on disk.


WORD WRAP
---------

A mode which is very useful, especially for editing English text, is "wrap"
(or "fill") mode.  When this mode is on, mex breaks the line in between
words automatically whenever the line gets too long.  You can turn this
mode on by typing (for example) <Esc> 65 ^X R.  This means: set the right
margin to 65 columns from the left end of the screen.  When the mode is on,
you can turn it off by doing ^X R by itself.

If you make changes in your text, you may want to reformat a paragraph to
fit the set margin again.  Put the cursor ANYWHERE in the paragraph and
press ^X F.

>> Type "<Esc> 20 ^X R" now.  Then insert a line of "asdf " over 
   again until you see it divide into two lines.  You must put in spaces 
   between them because Auto Fill breaks lines only at spaces.


GETTING MORE HELP
-----------------

In this tutorial we have tried to supply just enough information to
get you started using mex.  There is so much available in mex that
it would be impossible to explain it all here.  However, you may want
to learn more about mex since it has numerous desirable features
that you don't know about yet.

The on-line help feature is brief but complete.  Type <Esc> ?  (or <Esc>
<Esc>).  There are also options available through the command-line that
launches mex from your operating system.  Type "mex -h" (at the
operating system prompt) for a list.

>> Type <Esc> ? right now.  Press ^G to return to full-screen editing.


CONCLUSION
----------

Remember, to exit use ^C.

This tutorial is meant to be understandable to all new users, so if
you found something unclear, don't sit and blame yourself - complain!

You'll probably find that if you use mex for a few days you won't be able
to give it up.  Initially it may give you trouble.  But remember that this
is the case with any editor, especially one that is as versatile as mex.


Acknowledgements
----------------

mex was made possible by the placement in the public domain of the
source code for "microEMACS" by Dave Conroy.

This is a modified version of the "microEMACS Tutorial" by Dan Lawrance and
Dana Hoggatt.  That document was in turn a modified version of the "JOVE
Tutorial" by Jonathan Payne, which in turn was based on the tutorial
"Teach-Emacs" from MIT as modified by Steve Zimmerman.

This document was last updated on 880311 by Moshe Braner.
This document was last updated on 221024 by Axel Reinhold.