.TH me "" "" Command
.II MicroEMACS
.PC "\*(ME screen editor"
\fBme [-e \fIerrorfile\^\fB] [-f \fIbindfile\fB] [\fItextfile ...\^\fB]\fR
.PP
.HS
.SH Options:
.IC "\fB\-e \fIerrorfile\fR"
Error-handling mode; read error messages from \fIerrorfile\fR
.IC "\fB\-f \fIbindfile\fR"
Read keyboard bindings from \fIbindfile\fR
.HE
.B me
is the command for
\*(ME, the screen editor for \*(PN.
With \*(ME, you can insert text, delete text, move text,
search for a string and replace it, and perform many other editing tasks.
\*(ME reads text from files and writes edited text to files;
it can edit several files simultaneously, while displaying
the contents of each file in its own screen window.
.SH "Screen Layout"
Before you can use \*(ME, you must set the environmental variable
.B TERM
in your environment.
If you do not set this variable explicitly in your
.B .profile
file, \*(CO sets it by default to
.BR ansipc .
See the Lexicon entry
.B TERM
for details.
.PP
If the command
.B me
is used without arguments, \*(ME opens an empty buffer.
If used with one or more file name arguments,
\*(ME will open each of the files named, and display its
contents in a window.
If a file cannot be found, \*(ME will assume that you
are creating it for the first time, and create an appropriately
named buffer and file descriptor for it.
.PP
The last line of the screen is used to
print messages and inquiries.
The rest of the screen is portioned into one or more
.I windows
in which text is displayed.
The last line of each window
shows whether the text has been changed, the name of the buffer,
and the name of the file associated with the window.
.PP
\*(ME notes its
.IR "current position" .
It is important to remember that the current position is always to the
\fIleft\fR of the cursor, and lies \fIbetween\fR two letters, rather than
at one letter or another.
For example, if the cursor is positioned at the letter \*(Qlk\*(Qr
of the phrase \*(QLMark Williams\*(QR, then the current position
lies \fIbetween\fR the letters \*(Qlr\*(Qr and \*(Qlk\*(Qr.
.SH "Commands and Text"
The printable ASCII characters, from \*(Ql \*(Qr to \*(Ql~\*(Qr,
can be inserted at the current position.
Control characters and escape sequences are recognized as
.IR commands ,
described below.
A control character can be inserted into the text by prefixing it with
.B <ctrl-Q>
(that is, hold down the \fB<control>\fR key and type the letter \*(QlQ\*(Qr).
.PP
There are two types of commands to remove text.
.I Delete
commands remove text and throw it away, whereas
.I kill
commands remove text but save it in the
.IR "kill buffer" .
Successive kill commands append text to the previous
kill buffer.
Moving the cursor before you kill a line will empty the kill buffer,
and write the line just killed into it.
.PP
Search commands prompt for a search string terminated by
.B <return>
and then search for it.
Case sensitivity for searching can be toggled with the command
.BR <esc>@ .
Typing
.B <return>
instead of a search string tells \*(ME
to use the previous search string.
.PP
Some commands manipulate words rather than characters.
\*(ME defines
a word as consisting of all alphabetic characters, plus \*(Ql_\*(Qr
and \*(Ql$\*(Qr.
Usually, a character command is a control character and
the corresponding word command is an escape sequence.
For example,
.B <ctrl-F>
moves forward one character and
.B <esc>F
moves forward one word.
.PP
\*(ME
can handle blocks of text as well as individual characters, words, and lines.
\*(ME defines a block of text as all the text that lies between
the \fImark\fR and the current position of the cursor.
For example, typing \fB<ctrl-W>\fR kills all text
from the mark to the current position of the cursor; this is
useful when moving text from one file to another.
When you invoke \*(ME, the mark is set at the beginning of the
file; you can reset the mark to the cursor's current position
by typing \fB<ctrl-@>\fR.
.SH "Using MicroEMACS with the Compiler"
\*(ME can be invoked automatically by the compiler command
.B cc
to help you repair all errors that occur during compilation.
The
.B \-A
option to
.B cc
causes \*(ME to be invoked automatically when an error occurs.
The compiler error messages are displayed in one window,
the source code in the other, and the cursor is at the line on which
the first error occurred.
You can correct the errors one by one.
To move to the next error in the list, type
.BR <ctrl-X>> ;
to move the previous error, type
.BR <ctrl-X>< .
.PP
When have finished making corrections,
exit from \*(ME by typing
.BR <ctrl-Z> ,
as usual; the compiler will automatically be re-invoked to
re-compile the corrected source code.
If more errors are found, \*(ME will be re-invoked with the
new list of errors.
This cycle will continue either until the file compiles without error,
or until you break the cycle by typing
.BR "<ctrl-U> <ctrl-X> <ctrl-C>" .
.PP
The option
.B \-e
to the
.B me
command allows you to invoke the error buffer by hand.
For example, the commands
.DM
	cc myprogram.c 2>errorfile
	me -e errorfile myprogram.c
.DE
.PP
divert the compiler's error messages into
.BR errorfile ,
and then invokes \*(ME to let you correct them interactively.
.SH "The MicroEMACS Help Facility"
\*(ME has a built-in help facility.
With it, you can ask for information either for a word that you
type in, or for a word over which the cursor is positioned.
The \*(ME help file contains the bindings for all library
functions and macros included with \*(PN.
.PP
For example, consider that you are preparing a C program and want more
information about the function
.BR fopen .
Type \fB<ctrl-X>?\fR.
At the bottom of the screen will appear the prompt
.DM
	Topic:
.DE
.PP
Type \fBfopen\fR.
\*(ME will search its help file, find its entry for
.BR fopen ,
then open a window and print the following:
.DM
	Open a stream for standard I/O
	#include <stdio.h>
	FILE *fopen (name, type) char *name, *type;
.DE
.PP
If you wish, you can kill the information in the help window
and copy it into your program, to ensure that you prepare the
function call correctly.
.PP
Consider, however, that you are checking a program written earlier,
and you wish to check the call for a call to \fBfopen\fR.
Simply move the cursor until it is positioned over one of the letters in
\fBfopen\fR, then type \fB<esc>?\fR.
\*(ME will open its help window, and show the same information it
did above.
.PP
To erase the help window, type \fB<ctrl-X>1\fR.
.SH Options
The following list gives the \*(ME commands.
They are grouped by function, e.g., \fIMoving the cursor\fR.
Some commands can take an \fIargument\fR, which specifies how
often the command is to be executed.
The default argument is 1.
The command
.B <ctrl-U>
introduces an argument.
By default, it sets the argument to four.
Typing
.B <ctrl-U>
followed by a number sets the argument to that number.
Typing
.B <ctrl-U>
followed by one or more
.BR <ctrl-U> s
multiplies the argument by four.
.SH "Moving the Cursor"
.IP \fB<ctrl-A>\fR 0.8i
Move to start of line.
.IP \fB<ctrl-B>\fR
(Back)
Move backward by characters.
.IP \fB<esc>B\fR
Move backward by words.
.IP \fB<ctrl-E>\fR
(End) Move to end of line.
.IP \fB<ctrl-F>\fR
(Forward) Move forward by characters.
.IP \fB<esc>F\fR
(Forward) Move forward by words.
.IP \fB<esc>G\fR
Go to an absolute line number in a file.
Same as \fB<ctrl-X>G\fR.
.IP \fB<ctrl-N>\fR
(Next)
Move to next line.
.IP \fB<ctrl-P>\fR
(Previous) Move to previous line.
.IP \fB<ctrl-V>\fR
Move forward by pages.
.IP \fB<esc>V\fR
Move backward by pages.
.IP \fB<ctrl-X>=\fR
Print the current position.
.IP \fB<ctrl-X>G\fR
Go to an absolute line number in a file.
Can be used with an argument; otherwise, it will prompt
for a line number.
Same as \fB<esc>G\fR.
.IP \fB<ctrl-X>[\fR
Go to matching C delimiter.
For example, if the cursor is positioned under the character \*(Ql{\*(Qr,
then typing \fB<ctrl-X>[\fR moves the cursor to the next \*(Ql}\*(Qr.
Likewise, if the cursor is positioned under the character \fB}\fR, then
typing \fB<ctrl-X>[\fR moves the cursor to the first preceding \*(Ql{\*(Qr.
\*(ME recognizes the delimiters [, ], {, }, (, ), /*, and */.
.IP \fB<ctrl-X>]\fR
Toggle reverse-video display of matching C delimiters.
For example, if reverse-video displaying is toggled on, then whenever
the cursor is positioned under a \*(Ql}\*(Qr \*(ME displays
the first preceding \*(Qr{\*(Qr in reverse video (should it be on the screen).
\*(ME recognizes the delimiters [, ], {, }, (, ), /*, and */.
.IP \fB<esc>!\fR
Move the current line to the line within the window given by
.IR argument ;
the position is in lines from the top if positive,
in lines from the bottom if negative,
and the center of the window if zero.
.IP \fB<esc><\fR
Move to the beginning of the current buffer.
.IP \fB<esc>>\fR
Move to the end of the current buffer.
.SH "Killing and Deleting"
.IP \fB<ctrl-D>\fR 0.8i
(Delete) Delete next character.
.IP \fB<esc>D\fR
Kill the next word.
.IP \fB<ctrl-H>\fR
If no argument, delete previous character.
Otherwise, kill
.I argument
previous characters.
.IP \fB<ctrl-K>\fR
(Kill)
With no argument, kill from current position to end of line;
if at the end, kill the newline.
With argument set to one, kill from beginning of line to current position.
Otherwise, kill
.I argument
lines forward (if positive) or backward (if negative).
.IP \fB<ctrl-W>\fR
Kill text from current position to mark.
.IP \fB<ctrl-X><ctrl-O>\fR
Kill blank lines at current position.
.IP \fB<ctrl-Y>\fR
(Yank back)
Copy the kill buffer into text at the current position;
set current position to the end of the new text.
.IP \fB<esc><ctrl-H>\fR
Kill the previous word.
.IP \fB<esc><DEL>\fR
Kill the previous word.
.IP \fB<DEL>\fR
If no argument, delete the previous character.
Otherwise, kill
.I argument
previous characters.
.SH "Windows"
.IP \fB<ctrl-X>1\fR 0.8i
Display only the current window.
.IP \fB<ctrl-X>2\fR
Split the current window into two windows.
This command is usually followed by
.B <ctrl-X>B
or
.BR <ctrl-X><ctrl-V> .
.IP \fB<ctrl-X>N\fR
(Next)
Move to next window.
.IP \fB<ctrl-X>P\fR
(Previous)
Move to previous window.
.IP \fB<ctrl-X>Z\fR
Enlarge the current window by
.I argument
lines.
.IP \fB<ctrl-X><ctrl-N>\fR
Move text in current window down by
.I argument
lines.
.IP \fB<ctrl-X><ctrl-P>\fR
Move text in current window up by
.I argument
lines.
.IP \fB<ctrl-X><ctrl-Z>\fR
Shrink current window by
.I argument
lines.
.SH "Buffers"
.IP \fB<ctrl-X>B\fR 0.8i
(Buffer)
Prompt for a buffer name, and display the buffer in the current window.
.IP \fB<ctrl-X>K\fR
(Kill)
Prompt for a buffer name and delete it.
.IP \fB<ctrl-X><ctrl-B>\fR
Display a window showing the change flag,
size, buffer name, and file name of each buffer.
.IP \fB<ctrl-X><ctrl-F>\fR
(File name)
Prompt for a file name for current buffer.
.IP \fB<ctrl-X><ctrl-R>\fR
(Read)
Prompt for a file name, delete current buffer,
and read the file.
.IP \fB<ctrl-X><ctrl-V>\fR
(Visit)
Prompt for a file name and
display the file in the current window.
.SH "Saving Text and Exiting"
.IP \fB<ctrl-X><ctrl-C>\fR 0.8i
Exit without saving text.
.IP \fB<ctrl-X><ctrl-S>\fR
(Save)
Save current buffer to the associated file.
.IP \fB<ctrl-X><ctrl-W>\fR
(Write)
Prompt for a file name and
write the current buffer to it.
.IP \fB<ctrl-Z>\fR
Save current buffer to associated file and exit.
.SH "Compilation Error Handling"
.IP \fB<ctrl-X>>\fR 0.8i
Move to next error.
.IP \fB<ctrl-X><\fR
Move to previous error.
.SH "Search and Replace"
.IP \fB<ctrl-R>\fR 0.8i
(Reverse)
Incremental search backward; a pattern is sought as each character is typed.
.IP \fB<esc>R\fR
(Reverse)
Search toward the beginning of the file.
Waits for entire pattern before search begins.
.IP \fB<ctrl-S>\fR
(Search) 
Incremental search forward; a pattern is sought as each character is typed.
.IP \fB<esc>S\fR
(Search)
Search toward the end of the file.
Waits for entire pattern before search begins.
.IP \fB<esc>%\fR
Search and replace.
Prompt for two strings; then search for the first
string and replace it with the second.
.IP \fB<esc>/\fR
Search for next occurrence of a string entered with the
\fB<esc>S\fR or \fB<esc>R\fR commands;
this remembers whether the previous search had been
forward or backward.
.IP \fB<esc>@\fR
Toggle case sensitivity for searches.
By default, searches are case insensitive.
.SH "Keyboard Macros"
.IP \fB<ctrl-X>(\fR 0.8i
Begin a macro definition.
\*(ME collects everything typed until the next \fB<ctrl-X>)\fR
for subsequent repeated execution.
.B <ctrl-G>
breaks the definition.
.IP \fB<ctrl-X>)\fR
End a macro definition.
.IP \fB<ctrl-X>E\fR
(Execute) Execute the keyboard macro.
.IP \fB<ctrl-X>M\fR
Bind a newly created keyboard macro to a given keystroke or set of
keystrokes.
.SH "Flexible Key Bindings"
.IP \fB<ctrl-X>R\fR 0.8i
Replace one binding with another.
.IP \fB<ctrl-X>X\fR
Rebind the prefix (meta) keys, and the multiple-execution key \fB<ctrl-U>\fR.
.IP \fB<ctrl-X>S\fR
Prompt for a file name, and write all
flexible keybindings and macros into it.
This command also saves information about how you have configured \*(ME;
for example, it notes whether you have turned on word-wrapping.
.IP \fB<ctrl-X>L\fR
Prompt for a file name, and read all
flexible keybindings and macros from it.
.IP \fB<ctrl-X>I\fR
Rebind current macro to the initialization macro.
.PP
.II "MicroEMACS^f option"
.II "MicroEMACS^.emacs.rc"
.II ".emacs.rc"
By default, \*(ME checks for the existence of file
.B "$HOME/.emacs.rc"
and executes it if found.
The \fB\-f\fR option lets you specify an alternate file of
keybindings macros from the
.B me
command line.
After loading the file,
\*(ME then executes the initialization macro, if one exists.
For example, to load the keybindings file \fBbindings\fR and edit file
\fBtextfile\fR, use the command:
.DM
	me -f bindings textfile
.DE
.SH "Change Case of Text"
.IP \fB<esc>C\fR 0.8i
(Capitalize) Capitalize the next word.
.IP \fB<ctrl-X><ctrl-L>\fR
(Lower) Convert all text from current position to mark into lower case.
.IP \fB<esc>L\fR
(Lower) Convert the next word to lower case.
.IP \fB<ctrl-X><ctrl-U>\fR
(Upper) Convert all text from current position to mark into upper case.
.IP \fB<esc>U\fR
(Upper) Convert the next word to upper case.
.SH "White Space"
.IP \fB<ctrl-I>\fR 0.8i
Insert a tab.
Default behavior is to move the cursor to the nearest 8's boundary; for
example, if the cursor is in the 62nd column on the screen, pressing
.B <ctrl-I>
moves it to column 64.
.sp \n(pDu
When used with a positive argument, change the behavior of the tab key.
For example,
.B <ctrl-U>4<ctrl-I>
commands \*(ME to insert enough
spaces for a tab key to reach a four's boundary.
.sp \n(pDu
When used with a negative argument, change the behavior of the tab
character.
For example,
.B <ctrl-U>\-4<ctrl-I>
says that a tab character on a file will take you to the nearest 4's boundary.
Thus, if you have a file with tabs in it and you use `\-4',
the appearance of the file on the screen will change; but if
you use `4' the appearance of the file on the screen will not change.
.sp \n(pDu
.II TABSIZE
To change the default size of a tab, set the environmental variable
.B TABSIZE
to a value other than eight.
.IP \fB<ctrl-J>\fR
Insert a new line and indent to current level.
This is often used in C programs to preserve the current
level of indentation.
.IP \fB<ctrl-M>\fR
(Return) If the following line is not empty, insert a new line;
if empty, move to next line.
.IP \fB<ctrl-O>\fR
Open a blank line;
that is, insert newline after the current position.
.IP \fB<tab>\fR
With argument, set tab fields at every \fIargument\fR characters.
An argument of zero restores the default of eight characters.
Setting the tab to any character other than eight causes
space characters to be set in your file instead of tab characters.
.SH "Send Commands to Operating System"
.IP \fB<ctrl-C>\fR 0.8i
Suspend \*(ME
and execute a subshell.
Typing
\fB<ctrl-D>\fR
returns you to \*(ME and allows you to resume editing.
.IP \fB<ctrl-X>!\fR
Prompt for
a shell
command and execute it.
.PP
These commands recognize the shell variable
.B SHELL
to determine the shell to which it should pass the command.
.SH "Setting the Mark"
.IP \fB<ctrl-@>\fR 0.8i
Set mark at current position.
.IP \fB<esc>.\fR
Set mark at current position.
.\".IP \fB<ctrl><space>\fR
.\"Set mark at current position.
.SH "Help Window"
.IP \fB<ctrl-X>?\fR 0.8i
Prompt for word for which information is needed.
.IP \fB<esc>?\fR
Search for word over which cursor is positioned.
.IP \fB<esc>2\fR
Erase help window.
.SH "Miscellaneous"
.IP \fB<ctrl-G>\fR 0.8i
Abort a command.
.IP \fB<ctrl-L>\fR
Redraw the screen.
.IP \fB<ctrl-Q>\fR
(Quote)
Insert the next character into text;
used to insert control characters.
.IP \fB<esc>Q\fR
Quote a character by numeric value.
When you type this command, \*(ME prompts you for a numeric value,
in decimal.
It then inserts into your text the character whose value you type.
This command is useful when you wish to enter characters with the
high bit set.
.IP \fB<ctrl-T>\fR
Transpose the characters before and after the current position.
.IP \fB<ctrl-U>\fR
Specify a numeric argument, as described above.
.IP \fB<ctrl-U><ctrl-X><ctrl-C>\fR
Abort editing and re-compilation.
Use this command to abort editing and return to \*(OS when you are
using the \fB\-A\fR option to the \fBcc\fR command.
.IP \fB<ctrl-X>H\fR
Use word-wrap on a region.
.IP \fB<ctrl-X>F\fR
Set word wrap to \fIargument\fR column.
If argument is one, set word wrap to cursor's current position.
.IP \fB<ctrl-X><ctrl-X>\fR
Mark the current position, then jump to the previous
setting of the mark.
This is useful when moving text from one place in a file to another.
.SH Diagnostics
\*(ME prints error messages on the bottom line of the screen.
It prints informational messages
(enclosed in square brackets \*(Ql[\*(Qr and \*(Ql]\*(Qr
to distinguish them from error messages) in the same place.
.PP
\*(ME manipulates text in memory rather than in a file.
The file on disk is not changed until you save the edited text.
\*(ME prints a warning and prompts you whenever a command
would cause it to lose changed text.
.SH "See Also"
.Xr "commands," commands
.Xr "ed," ed
.Xr "elvis," elvis
.Xr "ex," ex
.Xr "sed," sed
.Xr "TERM," term
.Xr "vi" vi
.SH Notes
Because \*(ME keeps text in memory, it does not work for extremely large files.
It prints an error message if a file is too large to edit.
If this happens when you first invoke a file, you should
exit from the editor immediately.
Otherwise, your file on disk will be truncated.
If this happens in the middle of an editing session, however,
delete text until the message disappears, then save your file
and exit.
Due to the way \*(ME works, saving a file after this error
message has appeared will take more time than usual.
.PP
.\"The current version of
.\"\*(ME, including source code, is proprietary to
.\"\*(MW.
.\"The code may be altered or otherwise changed for your personal use,
.\"but it may
.\".I not
.\"be used for commercial purposes, and it may not be distributed without
.\"prior written consent by \*(MW.
.\"The source code for \*(ME is included with \*(CO,
.\"and is kept in directory
.\".BR /usr/src/local .
.\"You are invited to experiment with source code, to modify existing
.\"features or add new ones for your own use.
.\".PP
\*(ME is based upon the public domain editor
by David G. Conroy.
