MICROEMACS - the manual. Author: Rob Peck draft date: 1-22-86 TABLE OF CONTENTS About MicroEMACS Notational Conventions Used In This Manual Special Terminology Starting MicroEMACS Some Basic Keystrokes MicroEMACS Mini-Tutorial Menus The Project Menu The Edit Menu The Window Menu The Move Menu The Line Menu The Word Menu The Search Menu The Extras Menu Operational Controls Macro Commands Keyboard Redefinition Commands Not Installed In Menus Command Summary Functional Summary Alphabetical Summary Trouble-Shooting Guide (error message summary) Glossary Index ABOUT MicroEMACS MicroEMACS is a screen-oriented line editor. This means that it normally treats a document as a collection of individual lines of text. Depending on the text font that you are using, you will be able to edit text lines that are a maximum of either 60 or 80 columns wide. It is possible to edit a file whose lines exceed either of those lengths. However, if any line exceeds the available length, excess characters will not show onscreen. If a line is too long to show onscreen, the excess characters are not lost. However, at the rightmost margin MicroEMACS will place a dollar-sign ($) indicating that one or more characters could not be shown onscreen for a particular line. Characters beyond this limit are not lost, they simply do not show on the line. The tutorial section shows you how to view and edit these (temporarily) invisible characters. MicroEMACS lets you edit multiple files at one time if you wish. The only limitation it imposes is that the entire body of each file must be able to fit into memory at the same time, since MicroEMACS performs all of its operations on memory resident text. If MicroEMACS runs out of memory to do a particular operation, such as reading a new file, it will display an error message indicating an out-of-memory condition. MicroEMACS incorporates mouse controls, both for cursor positioning and menu selection. MicroEMACS assigns the mouse functions exactly as normally utilized under the Amiga Workbench. The left mouse button is the selection button. Clicking this left button on a character moves the cursor to that position. The right mouse button is the menu button. Holding down the menu button shows the operations menu across the top of the screen. You move the mouse pointer onto the menu strip and select from the available items. The effect of each of the menu items is described in this manual. NOTATIONAL CONVENTIONS USED IN THIS MANUAL ^ followed by a character is a "control-key combination". This means hold down the CTRL-key, then press that character. stands for the ESC-key on the Amiga keyboard. stands for the DEL-key on the Amiga keyboard. stands for the TAB-key on the Amiga keyboard. stands for the SHIFT-key on the Amiga keyboard. stands for the RETURN-key on the Amiga. SPECIAL TERMINOLOGY There are some special terms associated with MicroEMACS that you should know: BUFFER: A memory area that MicroEMACS manages. There is always at least one buffer used by MicroEMACS, and it contains zero or more characters of text. DOT: Where the cursor is right now. Always referred to by the name "dot" in this manual. MARK: Where you have set a mark in a buffer. Each buffer has its own dot and mark. SET MARK allows you to ask MicroEMACS to "set a mark", that is, remember the current position at which the cursor is resting. The mark is not visible, but is simply a MicroEMACS variable that stores the current position in the buffer. REGION: That block of text between the DOT and the MARK. You can quickly move from the one end of a region to the other by using the command SWAP DOT & MARK. You can also operate on the region using various commands such as COPY REGION or KILL REGION. KILL: Commands that include the name "kill" remove text from a buffer. However, the text you remove is saved in a special memory area called a kill-buffer. You can restore text from the kill-buffer at a later time by using a YANK command. YANK: Copy the contents of the current kill buffer inserting it into the line at which the cursor is currently resting. The combination of kill and yank can be used to copy or move text within a buffer or between buffers. WINDOW: A "window" in MicroEMACS is not the same as a window in Intuition. MicroEMACS splits the screen into multiple slices, allowing you to edit a separate file (memory buffer) in each MicroEMACS window. MODIFIED BUFFERS: When you ask to QUIT MicroEMACS, it sometimes tells you that "modified buffers exist, do you really want to quit?". MicroEMACS keeps track of whether you have made any changes to the contents of the memory buffers, such as typing a character or anything else. It shows you by using an asterisk (*) to the left of the status line as well as in the LIST BUFFERS display if the contents of a buffer have been modified since you last did a SAVE or SAVE AS command. When you save a buffer to a disk file, the asterisk disappears, since MicroEMACS knows your data is safe. BUFFER NAME: MicroEMACS keeps two names associated with a memory buffer. The first name is called the "buffer name". This is the name you use to SELECT a buffer. The other name is called the "file name", which generally refers to a disk file that you are editing in a memory buffer. When you first start up MicroEMACS, it creates a single memory buffer named "main". If you type characters into that memory buffer, then issue the command SAVE AS, MicroEMACS will ask for the name of a file into which the memory buffer (main) will be saved. You give it a "pathname" for the save command. From that time on, MicroEMACS associates this pathname with the current buffer name. If you issue further SAVE commands, then, MicroEMACS will know into which file the current buffer contents are to be saved. PATHNAME: A pathname is the complete pathway into a file that is provided by AmigaDOS. It consists of a "volume name" or disk identifier, followed by zero or more directory names, followed by the name of a file in which the data is actually stored. Example: df0:myfolder/goodstuff/mytextfile where df0: represents the diskette currently in the internal disk drive, myfolder is a subdirectory in the root directory of this disk, goodstuff is a subdirectory located in the myfolder subdirectory, mytextfile is the actual file. If this file actually exists, and you ask MicroEMACS to OPEN a file using this pathname, MicroEMACS lists this pathname as the "File name" for a memory buffer and uses just "mytextfile" as the name of the buffer itself. Thus, MicroEMACS makes it possible to SELECT this buffer by using a shortened version of the full pathname. STARTING MicroEMACS If you are starting MicroEMACS for the first time, or have no current text file to edit, from the Command Line Interface (CLI), type: run emacs and the program loads and starts running. The tutorial section, below, tells you how to create a new file and shows some of the basics of MicroEMACS. If you have already created a text file, you can ask that MicroEMACS start up using this file by specifying that file name on the command line. From your CLI, type: run emacs myfile At the top of the screen, you see a title bar that shows the program's name "MicroEMACS" and its version number. At the bottom of the screen, you see the program's name, and another name following it. The name you see on the bottom line is "main". This is the name of the memory area, called a buffer, that is currently in use. A memory buffer contains zero or more characters of text. You can have several buffers in use if you wish, switching back and forth between them or showning one or more onscreen at the same time. At all times, what you see onscreen is what is actually in the memory buffer (except in the case of a line that is too long to be displayed... other than that, what you see is what you get). If the contents of a memory buffer has been either read in or written to a file, that memory buffer will also be associated with a file name. In this case, the status line will contain not only the memory buffer name, but also the file name with which it is associated. SOME BASIC KEYSTROKES Before explaining any of the special features of MicroEMACS, lets look at the basics. There are two modes of operation: normal mode and command mode. MicroEMACS is in normal mode anytime that it is not in process of actually executing a command you have entered. After completing that command, it returns to this normal mode. In normal mode, you can: a. Insert characters simply by typing them. The program is always in "insert-mode". b. Use the TAB and space bar to insert TAB's and spaces. c. Delete the character the cursor is on by using the DEL key, d. Delete the character to the left of the cursor by using the BACKSPACE key (drags all other characters to the left as it goes), e. Reposition the cursor using the arrow keys. The cursor will not move to the right, past the current end of a line, or up or down beyond the current ends of the document. f. Position the cursor by moving the mouse pointer to the desired place and and click the lefthand mouse button, g. Move the cursor to the left margin, rightmost edge of the text on a line, top edge or bottom edge of the current window by holding down the key and pressing the appropriate arrow key. h. Perform other special functions as explained in the menu section and command summaries that follow. Command Mode is entered from many of the menu items. In command mode, the cursor jumps to the bottommost line of the display and MicroEMACS asks for certain additional information. The required information is explained for each of MicroEMACS menu items. When the command is completed, MicroEMACS returns to normal mode. EMACS MENUS MicroEMACS offers the following main menu items when you hold down the menu button on the mouse: PROJECT - system and file oriented items EDIT - primarily file editing commands WINDOW - controls the characteristics of the MicroEMACS windows MOVE - menu for quick cursor moves within a buffer LINE - line-oriented operations WORD - word-oriented operations SEARCH - lets you specify search or search/replace options EXTRAS - lets you set left and right margins, specify where wordwrap is going to occur, and lets you define and execute a series of operations as though it was a single special command. Here is an explanation of each of the menus. Each of the command items that can be selected from the menu can also be selected by a special sequence of keystrokes, actually listed in each menu item. As you become more familiar with various operations that you normally perform, you may find it more convenient to use the keystrokes as shortcuts, rather than lift your hands from the keyboard to use the mouse. The menu operation and its keystroke shortcut each perform exactly the same function. THE PROJECT MENU The project menu includes the menu items shown below. Except where noted, these commands all have some effect on the memory buffer in which the cursor is currently located. OPEN (READ): Read the contents of a file into the currently selected memory buffer. If the buffer is empty: ----------------------- just read the file into the memory buffer. When you select this menu item, MicroEMACS moves the cursor to the bottom line of the display and requests Read File: Type the complete name of the file to read, then press . That file is read into the current memory buffer. If the buffer has been modified: -------------------------------- MicroEMACS asks Discard changes [y/n]? Any response other than typing y causes MicroEMACS to ignore the OPEN command. If the buffer has not been modified: ------------------------------------ If you have some characters already in the memory buffer, but you haven't modified the buffer at all, MicroEMACS knows your data is safe, and it will empty the buffer before reading your file into this buffer. If you wish add the contents of a file to the current contents of a memory buffer, use the command INSERT FILE instead of OPEN. If you do not want to read a file, simply press without specifying a file name. MicroEMACS returns to normal mode. VISIT FILE: You must already be editing something before you can visit yet another file. This command is the equivalent of "I want to edit something else while I am editing this file." This command is useful, for example, to programmers who are creating a program and perhaps extracting pieces of other programs or refering to online documentation while they are creating the program. When you issue this command, MicroEMACS moves the cursor to the bottom line and asks: Visit File: Type the complete name of the file to use. If that file name is not already associated with a memory buffer being managed by MicroEMACS, and the file is found, a new buffer is created and is displayed onscreen. The old buffer, if any, is still available and can be selected at any time. If you have already visited or opened this file, instead of creating a new buffer for editing of the file, MicroEMACS switches the current window to display the old buffer that is already assigned for editing of this file name. INSERT FILE: You can insert the contents of a file into the current buffer. When you issue this command, MicroEMACS moves the cursor to the bottom line and asks: Insert file: Type the complete name of the file to be inserted and press . MicroEMACS will read it into a the current memory buffer at the point at which the cursor is currently located. SAVE AS: If there is no name currently associated with a memory buffer, this command establishes that name. On the command line, MicroEMACS asks: Write File: MicroEMACS is requesting the name of the file in which it should save the current contents of the memory buffer. If you provide no name and press , nothing happens. MicroEMACS returns to normal mode. If you provide a name (including a pathname if you wish), and press , this memory buffer will be written out to that file. Now, on the status line for the buffer, there appears a notation: File: yourfilename specifying the name of the file which will, from now on, be used to save the current contents of this buffer if you issue a SAVE command rather than a SAVE AS. After you have issued a SAVE or SAVE AS, the buffer is no longer marked as modified and the asterisk marker on the status line is erased. RENAME: Change the name of the file associated with this memory buffer. This command is useful if you are saving versions of a program or text file as you go along. You can perform a SAVE AS command for the first version, modify a few things, RENAME the file associated with this buffer and then SAVE the new version. When you issue this command, MicroEMACS prompts: New file name: If you simply press without specifying a file name, the memory buffer will then have no name. You must specify a name here if you wish the buffer to be appropriately associated with a file. SAVE: Write the contents of the currently selected memory buffer into the file whose name is associated with this buffer. If there is no file name specified on the status line, MicroEMACS tells you: No file name and refuses to perform the save. The file name becomes associated with the memory buffer either by opening (reading) the contents of an existing file or by renaming the file associated with this current buffer. If you perform a SAVE AS command, the file name also becomes associated with the buffer. After a successful SAVE, MicroEMACS uses the bottom line of the screen to tell you how many lines it has written out to the file name associated with the current buffer. Example: [Wrote 100 lines] SAVE MODS: Write the contents of all modified buffers to the disk. Use this item with caution so that you do not accidently modify a file you may have visited without intending to change it. QUIT: Exit the program. If one or more of the memory buffers has been modified since you last saved it to a file, MicroEMACS prompts: Modified buffers exist, do you really want to exit? [y/n]? MicroEMACS is giving you a last chance to save your work. If you really want to quit, press the y-key and press . If you don't want to exit, simply press any other key, then press or simply alone. On the EDIT menu, the item LIST BUFFERS can be selected to see which buffers have been modified. MicroEMACS lists the names associated with each buffer and shows an asterisk by each that has been modified since you last saved it to disk. SAVE/QUIT: This menu item is simply a combination of the SAVE and QUIT items. It saves ALL modified buffers before it exits the program. Use this item with caution so that you do not accidently modify a buffer associated with a file you have visited without intending to change it. This command has the same effect as issuing a SAVE MODS, followed by a QUIT. COMMAND: You select this menu item when you wish to perform an AmigaDOS command while you are still in MicroEMACS. The AmigaDOS commands are listed in the AmigaDOS User's Manual. COMMAND performs the same function as the "RUN" command when you are in the CLI. When you select this menu item, MicroEMACS moves the cursor to the bottom of the screen and provides, as a prompt, an exclamation point (!). You are expected to type a command for AmigaDOS to process on this bottom line. Example (COMMAND selected): ! info MicroEMACS temporarily suspends operation, returning the display to the CLI that spawned MicroEMACS in the first place. AmigaDOS executes your command (which may be running another program entirely if you wish, or simply issuing a simple AmigaDOS utility) and copies the output from the command into a memory buffer called "spawn.output", displayed onscreen immediately to show the AmigaDOS output from the command. This gives you time to examine the screen and see the results of the command. This memory buffer is treated as any other memory buffer. It can be named, it can be saved, it can be discarded. Any time you run a COMMAND, this same buffer will be used to display the output from the COMMAND. Note: When you modify other memory buffers and attempt to overwrite the current contents, MicroEMACS normally warns you when you have not saved your changes. This special buffer is an exception. MicroEMACS always emptys this buffer before running the COMMAND, and presents you only the results of the COMMAND in the latest version of this buffer. Thus, if you wish to save the results of a previous COMMAND, you must do so before issuing another COMMAND. NEWCLI: This command has an effect similar to that shown for the menu item COMMAND, above. However, instead of only providing an opportunity to issue a single command, it brings up an entirely new CLI window called "SPAWN WINDOW" and lets you issue as many commands as you wish before you return to MicroEMACS. To return to MicroEMACS from the spawn window, simply type: endcli The spawn window disappears and MicroEMACS is restored to its original state. THE EDIT MENU The EDIT menu contains a variety of selections that effect editing of your memory buffers and possibly their associated files. The edit menu lets you show and/or select the buffer in which you will work (as the current buffer) or setup for other editing operations. Here is a description of the items in this menu. SET MARK: Asks MicroEMACS, for the currently selected buffer, to remember where the cursor is right now. You can continue to move the cursor and instantly return to this marked position by using the MOVE menu, SWAP DOT & MARK. The MARK specifies one delimiter (either the beginning or the end) of a block of text. MicroEMACS knows that the opposite end of the block is wherever the cursor is located at the moment (DOT). In addition to using this menu item to SET MARK, you can also SET MARK by pointing the mouse cursor to the character on which the cursor is currently resting, and click the selection button, or by pointing to a character on which the cursor is not sitting, and double-clicking the selection button. (The first click moves the cursor to the selected position; the second click sets the MARK.) Also as noted above, a REGION is the area between the DOT and the MARK. Double-click to set the MARK at one end of a region. Then move the cursor to the opposite end of the region you wish to delineate and single click on the character that ends the region (moves the cursor to that position). This establishes the region that other commands can operate upon. KILL REGION: This command removes a marked REGION from the memory buffer and places that text into the kill-buffer. The kill buffer is emptied of all prior contents before the new block of text is added. If you are using KILL REGION to copy a block from one section of the buffer to another, you can restore the block to its original position by not moving the cursor, and immediately selecting YANK. The block you removed is restored, but there is still a copy of the block in the "kill-buffer". YANK: Copy the contents of the kill-buffer to a position immediately to the left of the current cursor location in the current buffer. The contents of the kill buffer is established either by a KILL REGION or KILL TO EOL selection. YANK does not change the contents of the kill buffer. The menu items SET MARK, KILL REGION and YANK are sequentially placed at the top of the EDIT menu to provide an easy cut-and-paste facility. COPY REGION: Copy the contents of the marked region to the kill buffer. This replaces any previous contents of the kill buffer. QUOTE CHAR: This menu selection lets you "QUOTE" a character and thereby make it a part of the text file. Some keyboard selections have been assigned as MicroEMACS control characters. Therefore when you press CTRL and press a character (example CTRL-L), instead of inserting this character into the text file you are creating, MicroEMACS would normally take this character as a command to redraw the display. Since a character such as CTRL-L, among others, is useful as a printing control (CTRL-L is a formfeed character), you may wish to insert it into your text file. By selecting QUOTE CHAR, the next character you type will be taken "literally" by MicroEMACS and inserted into the file rather than be treated as a command. CONTROL characters are displayed by MicroEMACS as the character, preceeded by a caret (^). Example: ^L As MicroEMACS manipulates this buffer, the combination of the caret and the character is treated, by the arrow keys and the character counter as a single character, which indeed it is. You can use this QUOTE CHARACTER facility to insert a key into a keyboard macro if you wish, or to insert any other control character that may be needed during a macro command. Even ^Q itself may be inserted by typing it twice. LIST BUFFERS: If there is no buffer list currently onscreen, MicroEMACS splits the current buffer's window and provides you with a list of the buffers it is currently maintaining. The list has 4 columns. Example: C Size Buffer File - ---- ------ ---- * 17260 emacs.doc df0:emacs.doc where C is short for "Changed", a column that will contain an asterisk if the buffer has been modified since it was last saved to a file. Size shows how many characters there are currently in a particular buffer. Buffer shows the name by which MicroEMACS calls this particular buffer. If you have read in a file, this will usually be the name of the file itself, minus the pathname from which it was obtained. For example, if the file you are editing is df1:docfiles/emacs.doc, then its buffer name will be emacs.doc. File is the name of the file, including the pathname. This shows you where emacs will write this file if you say SAVE or SAVE/QUIT while your cursor is in this buffer as the current buffer. The status line at the bottom of the list simply says MicroEMACS -- [List] Even though this brings up a window display, to which you can move, it is not listed among the available buffers. If you edit the display that appears in the list buffer window, however, it can be made to act just like any other buffer. If, for example, you open a file in this window, the name of the buffer will continue to be [List], and the file name you have opened will become associated with this window. If you leave this list onscreen and use a different window to modify the listed buffers, the LIST BUFFERS display will not be continously updated to reflect current status. To get current information, you must select LIST BUFFERS again. Note that this is an exception to the "what you see is what you get". SELECT BUFFER: For whichever window your cursor is presently occupying, this menu item can be used to select which buffer you wish to edit in that current window. MicroEMACS moves the cursor to the bottom line and asks: Use buffer: You must provide a name that is the same as one of those shown in the LIST BUFFERS listing. If you simply press return, the command is ignored. If you specify one of the available names, that buffer replaces the current contents of the window your cursor was located in. If you specify an entirely different name than any in the LIST BUFFERS list, you are asking MicroEMACS to create a new buffer and give it this new name. In such a case, there is no file name associated with the new buffer and you will have to select SAVE AS or RENAME when you are prepared to save its contents to a file. KILL BUFFER: If you are finished with a particular buffer, you may wish to get rid of it. As mentioned above, MicroEMACS can only edit a file if there is room enought to hold it entirely in memory. You may need to delete the contents of one or more buffers just to make room enough to edit a file of a particular size. This command returns the buffer's memory to the memory manager for reuse. You cannot kill a buffer if its contents are currently being displayed. When you select this item, MicroEMACS asks: Kill buffer: Type the name of the buffer to be removed. If the buffer has been modified without being saved, MicroEMACS asks: Discard changes [y/n]? You must respond with y if you wish to remove a modified buffer. INSERT BUFFER: Insert the contents of a named buffer into the current buffer, a position immediately to the left of the position occupied by the cursor. When you select this item, MicroEMACS asks: Insert buffer: Type the name of the buffer to insert, then press . JUSTIFY BUFFER: Remove all blank spaces or tabs from the lefthand edge of all lines in this buffer, and move all text to align itself with the current lefthand margin of this buffer. UPPER REGION: LOWER REGION: Change the capitalization of the entire marked region (between dot and mark) to upper case (UPPER REGION) or lower case (LOWER REGION). REDISPLAY: This menu item simply causes a complete refresh (redrawing) of the entire screen. THE WINDOW MENU The window menu lets you control how you view your buffers onscreen. You can be working in a single MicroEMACS window. You can split the window into two parts. You can make your current window larger or smaller, scroll up or down on a page-by-page basis within a window, or move between windows using these menu items. ONE WINDOW: Selecting this item makes the current buffer a single full-sized window on your MicroEMACS screen. All other buffers remain invisible, allowing you maximum space to work on this single buffer. SPLIT WINDOW: Cut the size of the current window in half, editing the same buffer in both of the resulting windows. When MicroEMACS splits a window, the buffer is positioned identically for both windows (the character position for the upper lefthand corner is the same for each). If you wish, you can then continue to edit within one window and scroll up and down in the other window to be able to see and/or copy things from other sections of this document. Since both windows are capable of editing the same buffer, any change you make in either window is immediately reflected in the buffer. If both windows are showing the same line in the buffer, a change in one will show as an invisible cursor making an identical change in the other window. NEXT WINDOW: PREV WINDOW: These items move the cursor from window to window, changing which one is the currently active one for editing. NEXT WINDOW moves the cursor "down" each time you select it. PREV WINDOW moves the cursor "up" to another window. Down and up are in quotes because these commands wrap-over. In other words, if you move the cursor down as far as it can go (no more windows below this one), the cursor next moves to the topmost window. Likewise, going up one more step wraps the cursor to the bottommost window. GROW WINDOW: SHRINK WINDOW: These items respectively make the current window one line longer or shorter. Since there is a limit to the number of lines onscreen at one time, making a window larger by one line also makes an adjacent window smaller by one line (growing one window shrinks another and vice versa). NEXT W-PAGE: PREV W-PAGE: Normally, if you want to scroll a window to look at a later portion of a buffer, you have to move the cursor into that window and make it the current window. Then you issue a NEXT PAGE command. These menu items let you stay in your current edit window and still scroll forward a window above or below (PREV, NEXT) the current window. If there are two windows onscreen, the "other" window is treated as both the previous and as the next window. If you have only one window onscreen, these commands page-forward this current window. THE MOVE MENU This menu has items that let you move rapidly around in the current buffer. TOP OF BUFFER: Move to the top line of the current buffer. END OF BUFFER: Move to the bottom line of the current buffer. TOP OF WINDOW: END OF WINDOW: Move the cursor as each command specifies, within the current window. GO TO LINE: Move to a specific line number. When you select this item, MicroEMACS moves the cursor to the bottom line of the screen and asks: goto-line You should enter a line number and press return. MicroEMACS moves the cursor directly to that line. If you specify a line number larger than the total number of lines in the buffer, MicroEMACS simply moves the cursor to the last line of the buffer. SWAP DOT & MARK: Place the MARK where the cursor is now and move the DOT to where the mark was set previously. This moves the cursor to the place where the MARK was set before, creating a rapid movement within the buffer directly to a previously remembered location. If you have not yet set a mark in this window, MicroEMACS reports: No mark in this window NEXT PAGE: PREV PAGE: Moves the text within the window toward the end of the buffer (NEXT) or towards the beginning of the buffer (PREV) by a full window, less one line. The cursor is repositioned so as to stay onscreen. NEXT WORD: PREV WORD: Moves the cursor forward to the first letter of the next word or backward to the first letter of the previous word. SCROLL UP: SCROLL DOWN: Moves the text within the window towards the end of the buffer (UP) or towards the beginning of the buffer (DOWN) by a single line rather than a full window height. THE LINE MENU This menu contains items that move the cursor within lines, between lines, or operate on lines. OPEN LINE: Selecting this item splits the line the cursor is in, forcing the character on which the cursor rests to become the first character of the following line. Leaves the cursor in the original line so that you can type new characters at and following the current cursor position. If you did not want to select this item, you can undo this OPEN LINE selection by pressing the DEL key immediately. It will close up the line for you. KILL LINE: Copy the line in which the cursor is now located to the kill-buffer. Delete this line from the current edit window's buffer. Note: KILL LINE clears the kill buffer first, then the line you killed enters the buffer. To restore or move the line, you can YANK it into position in the current window. KILL TO EOL: Kill the text between the cursor location and the end of the line. This text is appended to the current contents of the kill buffer if there has been no intervening YANK. After a YANK, any new kill command causes the kill buffer to be cleared before the killed line or region is added. START OF LINE: Move the cursor to the leftmost position on a line. END OF LINE: Move the cursor to the rightmost position on a line. If you have typed too many characters on a line, a dollar-sign ($) shows at the right hand edge of the line. Moving to the end of the line places your text cursor logically on the rightmost character even though you cannot see it. Physically the cursor is positioned over the dollar sign. If you use the left-arrow key to move the cursor to the left, you will see that it will take as many left-arrow key presses as there are characters off the right hand edge before the cursor actually begins to move. If you wish to see these offline characters, you can use the OPEN LINE command or press RETURN at any cursor position to the left of the $-sign. This will push those extra characters onto a new line just below the existing line and terminate the old line at the position at which it was opened. PREV LINE: NEXT LINE: Move the cursor up (PREV) or down (NEXT) onscreen. DELETE BLANKS: If you have several blank lines in a row in your buffer and want to delete all of them at one time, you use this function. Position the cursor on the first blank line you want to delete and issue this command. MicroEMACS deletes all blank lines up to the next line on which it finds text. THE WORD MENU This menu contains word-associated operations. DELETE FORW: Delete forward. Treat the character on which the cursor is sitting as the initial character of a word. Delete this and all characters to the right of this word until the next blank, tab, punctuation, linefeed, or embedded control character is located. If the cursor is sitting on a blank space, move forward to the start of the first character of a word and proceed to delete that word. You can delete the end of a word by moving to the first character within the word to be deleted, and select this item. Example: wordsuffix To delete the suffix, move the cursor to the "s" and select DELETE FORW. DELETE BACKW: Same as delete forward, except that cursor moves to the left until it finds the first character of the word to the left of the cursor and deletes that word. UPPER WORD: Change a word to upper case, starting at the character on which the cursor is sitting and proceding to the last character of the word. LOWER WORD: Operates as UPPER WORD, but changes all letters to lower case. CAP WORD: Change the first character of a word (or the character the cursor is on if in the middle of a word) to upper case, and change the characters to the right of the cursor, to the end of the word, to lower case. SWITCH CASE: If a character of the word is upper case, change it to lower case. If a character of the word is lower case, change it to upper case. Starts at the cursor position, and proceeds to the right until the end of the word is reached. THE SEARCH MENU This menu has items that let you search forward or backward for specific text strings. The case of the search (upper case, lower case) is not significant for the search itself. However, if you are using a text substitution (search and replace), it literally substitutes the text you have requested for the text string it finds. You can ask that MicroEMACS search and replace special characters, such as tabs or embedded control characters by preceding the character by a QUOTE CHARACTER command (^Q). For example, to search for the next TAB character, you would type: ^Q Other special characters, such as control characters normally treated by MicroEMACS as commands, are treated in the same way. SEARCH FORW: When you select this item, MicroEMACS moves the cursor to the bottommost line and asks: Search: You must type the string of characters to search for, then press return. MicroEMACS searches for this character string from the current cursor position to the end of the buffer. If the string is found, MicroEMACS positions the cursor immediately following the last character of the string. If it cannot locate the string, MicroEMACS reports, on the bottommost line: Not found SEARCH BACK: This menu item performs the search for the string backwards from the cursor position towards the beginning of the file. SEARCH/REPLACE: Operates the same way as SEARCH FORW. If it finds the first occurence of this string, it asks: Replace: You must type the string of characters that should replace this string. When you press return, MicroEMACS will forward-search the rest of the file and replace the search-string with the replacement-string without asking for any more information. After MicroEMACS completes this command, it reports: Replaced (xx) occurrences QUERY S & R: This item is a Query-Search-and-Replace. It operates just like SEARCH/REPLACE, except that it asks: Query replace: instead of Replace, and, as it finds a matching string, it always asks: Change string ? [y/n]? This gives you a chance to control the replacement process. After MicroEMACS completes this command, it reports: Replaced (xx) occurrences THE EXTRAS MENU Most of the items on the extras menu tell MicroEMACS how to operate. Some of the commands let you combine commands into control sequences that are called macros. The command selections that control MicroEMACS each require that you give MicroEMACS a number value to tell it exactly how to set the value into the selected parameter. You must specify a numeric argument before you select the command itself. If you don't specify the numeric argument, you may get unpredictable results. These command selections are: Set the current Left Margin, the current Right Margin, the position at which Word Wrap begins, the Tab value, and the S-Level. Specifying a numeric argument is covered later in this manual, under the topic "Commands Not Installed In Menus" Operational Controls Here are the menu items, in the EXTRAS menu, that control MicroEMACS. LEFT MARGIN: You set the current left margin value by specifying an argument value from 1 to 80 if you are using an 80 column screen or 1 to 60 if your screen is 60 columns wide. After specifying the value, select this item. This item has no effect on any text you have already typed into the buffer. However, any time you press , the cursor will move to the current left margin position. Your cursor will not be restricted from moving to the left of this new margin value. It affects only the placement of the cursor after a . MicroEMACS inserts blank spaces from the left edge of the edit line to establish the left margin value you requested for each new line you type. The default value is 1 (means leftmost edge). A value of 0 also selects the leftmost edge. RIGHT MARGIN: You select an argument value from 1 to 80. Then select this item. MicroEMACS treats this column number as the rightmost on the page, substituting a dollar-sign for the rightmost character if the line is longer than this number of characters measured from the leftmost edge of the screen. If you do not select an argument before you select this item, MicroEMACS asks for the value for the right margin by moving to the command line and asking: Arg: You should specify the correct value between 1 and 80 and press . If you select a value greater than the maximum that can currently be displayed (60 or 80), or a value that is less than the current value of the LEFT MARGIN, MicroEMACS sets this argument to the maximum. WORDWRAP: You select an argument value, then select this item. MicroEMACS will automatically remove a word from the line on which you are typing and move it to the line below if the word is too long to place its rightmost character within the wordwrap column limit you established. In other words, with WORDWRAP enabled, you can type no line whose rightmost character goes beyond the column number at which wordwrap is set. If you do not select an argument before you select this item, MicroEMACS asks for the value for the wordwrap position by moving to the command line and asking: Arg: You should specify the correct value between 1 and 80 and press . If you wish to disable wordwrap, specify an argument value of 0. As with RIGHT MARGIN, the value you select should exceed the value you have specified for the LEFT MARGIN. S LEVEL: This is the SAVE LEVEL; it tells MicroEMACS what to do when you are trying to save a file if MicroEMACS finds that a file by that name already exists. The arg-value possibilities for S LEVEL are: 1 Write the buffer to the file. In other words, delete the current version of the file and replace it with the new buffer contents. 0 Copy the contents of the old file to a file named edit.backup on the t directory in the root of the current working directory. -1 Refuse to perform the SAVE, reporting an error as: Cannot move file for backup The value of 1 is the default. If you do not set this value, when you say SAVE, it will write the file, thereby erasing prior contents. Macro Commands A macro command is basically a sequence of commands or other keystrokes that you may wish to have executed just by selecting the single item execute-macro. START: Tell MicroEMACS to begin recording your keystrokes. STOP: Tell MicroEMACS to stop recording your keystrokes. EXECUTE: Any keystrokes (or menu selections) that happened between START and STOP are repeated, just as though you had freshly entered the entire sequence. When you define a macro, you are defining the sequence of keystrokes or commands that you want MicroEMACS to look at as though you had just then typed them all yourself. Thus, the execution of the macro is simply an abbreviated form of entering this sequence. For example, you can define your macro to execute the following sequence: 1. Type 4 RETURN-keys, 2. Type INSERT ILLUSTRATION HERE 3. Type 4 more RETURN-keys You would enter this macro as follows: 1. Select START 2. type ^Q^U^Q^M^Q^I INSERT ILLUSTRATION HERE^Q^U^Q^M 3. Select STOP In step #2, the sequences mean: ^Q^U - install the character control-U in the string. This is the Argument specifier. When an argument is requested, it automatically selects a value of 4 as the default. If you wanted a value other than 4, the value you wanted to use could follow the ^U. ^Q^M - install the character control-M in the string. This is the RETURN-key that you are asking MicroEMACS to type automatically. ^Q^I - install the character control-I in the string. This is the TAB-key that you are asking MicroEMACS to type automatically. Then comes the characters INSERT ILLUSTRATION HERE Finally another argument specifier and a RETURN-key. Besides this single define and execute facility, you can define the function keys and the keypad keys by providing MicroEMACS with a particular file. See the topic "Keyboard Redefinition" for more details. Keyboard Redefinition In addition to the EXECUTE facility described above, MicroEMACS allows you to redefine all of the function keys, the help key, or any key on the numeric keypad as keyboard macros. Thus, you can select the specific functions that each of these keys is to perform. One definition, having as many as 80 keystrokes, can be recorded for each of these keys. There are two different ways to perform the redefinition: setting the value of an individual key, or loading a new key definition file. Both methods are available from the EXTRAS menu. CAUTION: If you want to embed the SET MARK command in any of your keyboard macro definitions, you must specify a different key sequence than that shown in the SET MARK item in the EDIT menu. In particular, set mark is shown as CTRL-@. This does not function correctly when used in a macro. You must use the alternate form of SET MARK, specifically: - (escape, then a minus sign). This alternate set mark is acceptable for use in key macros. SET KEY: When you select this item, MicroEMACS asks: key to define: You then press one of the 10 function keys, or the help key or one of the keypad keys. MicroEMACS responds: def: You type the string of characters (up to 80) that you wish to have MicroEMACS respond to when this key is again touched. Pressing terminates the key definition entry. Remember that if you want to enter commands as a function key definition, for example, assign F1 as < (go to top of buffer) you will have to use the ^Q (quote character) to insert the keystroke into the key definition. This particular key would be defined by the keystroke sequence: ^Q < LOAD KEYS: If you want to load all of the keys at one time, you can create a file containing the key definitions. The format of that file is as follows (a definition, followed by a tilde (~) that is used to separate the definitions. Example: ~^A^X^D^Y^M^Y~^Xe (and so on) The example implements the first two function keys default assignments. The tilde that precedes the definition string above indicates that the string has no default initialization string present. SEQUENCE DEFAULT VALUE -------- ------------- auto-start-string fkey 1 clone line fkey 2 delete line fkey 3 execute keyboard macro fkey 4 next screen fkey 5 previous screen fkey 6 split window fkey 7 one window fkey 8 roll window up fkey 9 roll window down fkey 10 save file and exit help line feed keypad 0 0 keypad 1 1 keypad 2 2 keypad 3 3 keypad 4 4 keypad 5 5 keypad 6 6 keypad 7 7 keypad 8 8 keypad 9 9 keypad . . keypad enter line feed keypad - - The auto-start-string is the string of commands that is automatically executed when MicroEMACS first starts up. A file with this layout is placed into the s-directory as: s/emacs_fkeys Clone line is a macro that means duplicate the current line and copy it to the line below this one. It is defined as: go-to-beginning-of-line kill-line yank-line insert-return yank-line Line feed is ^J, the function that moves the cursor down one line and indents to the current level. As you can see, both the HELP key and the ENTER key are mapped to this function. Your loadable key definition file can have any name and can be stored any place you like on your disk. If you want it autoloaded when MicroEMACS starts, simply move it to the s-directory and give it the name shown above. COMMANDS NOT INSTALLED IN MENUS The following commands have not been installed in the menus. SPECIFYING A NUMERIC ARGUMENT FOR OTHER COMMANDS: You specify a numeric argument by pressing ^U (CTRL-key held down, then press the U-key). MicroEMACS responds by moving to the command line and says: Arg: 4_ (underscore shows cursor position) If you press control-U again, MicroEMACS multiplies the argument value by 4. If you press a numeric key (0-9), MicroEMACS begins to accept an integer argument. If, instead of a numeric key, the first key you press (other than control-U) is a minus sign, MicroEMACS begins to accept a negative integer as a parameter. Starting value is -1. Examples: (each started by a single press of ^U): Arg: -1 (pressed "-" as the first key) Arg: -23 (pressed "- 2 3" as a 3-key sequence) Arg: 12 (pressed " 3 ^U" as a 2-key sequence) MicroEMACS accepts this argument as the specifier for whatever you do next. To add 12 blank lines at the cursor position, specify an argument of 12, and press . To add 30 minus signs, instead of typing them on the keyboard, select an argument number of 30 and press the minus-sign on the keyboard (note: don't use the keypad "-".... it is mapped to a different value). To set one of the MicroEMACS operational parameters, select the value of argument, then select the appropriate menu item (or use the keyboard shortcut) and the system uses that argument to set the value. QUICK MOVE TO EDGES OF WINDOW: Hold down the SHIFT-key and press the arrow key to tell MicroEMACS to go up to the top edge, down to the bottom edge, left to the left edge, or right to the right edge. TRANSPOSE TWO CHARACTERS: You can swap the positions of two adjacent characters by placing the cursor on the rightmost of the two characters and pressing ^T. Lets you correct spelling errors such as "hte" to "the" by placing the cursor on the "t" of "hte" and pressing ^T. INDENT: As you are typing computer programs, you may often wish to indent the text to more clearly delineate function definitions and logical groups of lines. Instead of pressing to go on to the next line, press ^J. This command goes to the next line, but measures the number of spaces between the left edge and the first character on the previous line, and duplicates that spacing. Thus, it indents to the current indent level. For your convenience, the HELP key and the ENTER key, at entry to MicroEmacs are redefined to provide the INDENT function. QUERY CURSOR POSITION: This command is executed by the keystroke sequence: ^X = On the status line, it provides a display such as: X=1 Y=1 CH=0x66 .=0 (0% of 72) where the status information presented means: X= the x-coordinate of the cursor with respect to the line in which it resides. This would normally range from 1 to 60 for a 60-column screen or 1 to 80 for an 80 column screen. However, if the cursor is sitting on the $-sign at the rightmost edge of the screen, you can continue to type "past the edge" of the line and though you cannot see the characters, the X coordinate position continues to increase. If you move the cursor to the left, until it moves off of the $-sign, you can press return and make visible the characters that MicroEMACS could not display on this too-narrow line. Y= the y-coordinate of the cursor position, with respect to the current window. CH= the ASCII value of the character on which the cursor resides. .= the current value of DOT. (N% of M) The cursor position represents a position N percent of the way from the top of the buffer, where there are M characters in the buffer. ABORT: This command is executed by the keystroke: ^G This command can be used, for example, to end a query search and replace. MOVE CURSOR BY CHARACTERS: Move forward a specified number of characters: ^F Move backward a specified number of characters: ^B The default size of move is one character, and this is more easily done using the arrow keys. To move more than one character position, use ^U to establish the argument value, then use ^F or ^B to perform the actual cursor move. COMMAND SUMMARY This function summary lists commands that are accessible from the menus as well as certain commands that are accessible only by way of the keyboard shortcuts. There are two function summaries provided. The first is a functional summary, where the access to a routine is grouped by function. The second summary is strictly alphabetical. Functional Summary In this table of functions, the key combination column sometimes specifies a sequence of characters, for example, "^X e". The space between the two characters is not part of the sequence. It simply serves to separate the characters for ease of reading. Change Text: Transpose characters ^T Upper case word. u Lower case word. l Upper case region. ^X ^U Lower case region. ^X ^L Initial capitalize word. c Insert tab Insert literal ^Q Insert CR-LF ^M Insert CR-LF, then indent ^J Open up a blank line ^O Windows: Move to the next window ^X n Move to the previous window ^X p Make current window only one ^X 1 Split current window ^X 2 Move window down ^Z Move window up Z Enlarge display window.(grow) ^X z Shrink window. ^X^Z Display list of buffers ^X^B Switch a window to a buffer ^X b Make a buffer go away. ^X k Reposition (line-to-top) ! Refresh the screen ^L scroll other window forward ^V scroll other window backward ^X v Search: Search forward ^S Search backwards ^R forward search & replace r forw. query search & replace q Movement: Move to start of line ^A Move forward by characters ^F Move to end of line ^E Move backward by characters ^B Move forward by lines ^N Move backward by lines ^P Move forward by pages ^V Move backward by pages V Move to start of buffer < Move to end of buffer > Backup by words f Advance by words b go to line ^X^G Miscellaneous: Abort out of things ^G Quit ^C Get a file, read/write ^X^R Get a file, read/write ^X^V Write a file ^X^W Save current file ^X^S Adjust file name ^X F Set mark ^@ or - Swap "." and mark ^X^X Show the cursor position ^X = Run a command in a subjob. ^X ! low keystroke style exit. ^X^F load function key macros execute macro ^X e Yank back from killbuffer. ^Y Copy region to kill buffer. W Run CLI in a subjob. ^- Macros: Begin macro ^X ( End macro ^X ) Execute macro ^X 'e' Delete: Delete blank lines ^X^O Forward delete Backward delete ^H or Kill forward ^K Delete forward word. d Delete backward word. h Kill region. ^W kill entire line ^X^D Alphabetical Summary In this list, the vertical bar simply serves to say "logically-OR'ed-with". This means that this listing contains single-character combinations formed from holding down the CTRL-key, then pressing another key. The key is shown in single quotes, which means that it is the keycap that is signficant, rather than the case (upper case/lower case) of the character itself. Key Combination Function It Performs ------------ -------------------- CTRL|'@' Set mark CTRL|'A' Goto beginning of line CTRL|'B' Move left a character CTRL|'C' Quit CTRL|'D' Forward delete CTRL|'E' Goto end of line CTRL|'F' Move right a character CTRL|'G' Cancel the current operation CTRL|'H' (backspace), backward delete CTRL|'I' Tab, CTRL|'J' Next line and indent to current level CTRL|'K' Kill to end of a line CTRL|'L' Refresh, (redraw the screen) CTRL|'M' Newline, (the return key), move down one line and move to left margin CTRL|'N' Move down a line CTRL|'O' Open line CTRL|'P' Move up a line CTRL|'Q' Quote, enter the next character as a literal CTRL|'R' Reverse search CTRL|'S' Forward search CTRL|'T' Transpose, swap 2 characters CTRL|'U' Enter numeric argument or multiply current argument value by 4. CTRL|'V' Next page CTRL|'W' Kill region, kill from mark to dot CTRL|'Y' Yank, pull from killbuffer CTRL|'Z' Scroll window up CTRL|'-' Spawn cli, run CLI in subjob. Delete character at cursor Here are the commands that begin with a CTRL-X: Command Function It Performs ------- --------------------------------- ^X ^B Display list of buffers ^X ^C Hard quit ^X ^D Delete entire line ^X ^F Quick save and exit ^X ^G Go to line ^X ^L Lower case region. ^X ^O Delete blank lines ^X ^R Get a file, read/write ^X ^S Save a file to current name ^X ^U Upper case region. ^X ^V Get a file, read write ^X ^W Write a file ^X ^X Swap "." and mark ^X ^Z Shrink window. ^X '! Run 1 command. ^X '= Show the cursor position ^X '( Begin macro ^X ') End macro ^X '1 Make current window only one ^X '2 Split current window ^X 'B Switch a window to a buffer ^X 'E Execute macro ^X 'F Rename file for this buffer ^X 'K Make a buffer go away. ^X 'N Move to the next window ^X 'P Move to the previous window ^X 'Q Insert literal (alt to ^Q) ^X 'R Search backwards (alt to ^R) ^X 'S Search forwards (alt to ^S) ^X 'V Scroll other window backward ^X 'Z Enlarge display window. Here are the functions that begin with the key: Command Function It Performs ------- ------------------------------ ^C Hard quit ^V Scroll other window forward ! Current Line to Top of Window - Set mark (alternate to ^@) > Move to end of buffer < Move to start of buffer B Backup by words C Capitialize initial letter of word D Delete forward word. F Advance by words H Delete backward word. L Lower case word. Q Forward query search & replace R Forward search & replace U Upper case word. V Move backward by pages W Copy region to kill buffer. Z Move current window up ~ Execute macro (alt to ^X e) Delete backward word. TROUBLE-SHOOTING GUIDE (error summary) GLOSSARY INDEX