The mg Tutorial --------------- The mg editor is a public domain editor intended to loosely resemble GNU Emacs, while still retaining fast speed and a small memory footprint. Most mg commands involve using the Control (sometimes labelled "Ctrl") or the Meta (sometimes labelled "Alt") key. We will use the following conventions in this tutorial: C- means hold down the Control key while typing the character . M- means hold down the Meta key while typing the character . If you don't have a Meta key, you can use Esc instead. Press and release the Esc key and type . This is equivalent to M-. The first thing to learn is how to move up and down a document. To move your cursor down a line, use the down-arrow cursor key or C-n (Control and n). >> Now type C-n multiple times and move your cursor past this line. Congratulations. You have now learned how to move your cursor down. To move your cursor up one line, you can use the up-arrow cursor key or C-p (Control and p). >> Try using C-p and C-n to move up and down and then move past this line. The next commands to learn are how to move your cursor left and right. To do this, you can use the left-arrow and right-arrow cursor keys. Alternatively, you can use C-b and C-f to do this. >> Practise using the arrow keys or C-b and C-f on this line. To make it easy to remember these commands, it helps to remember by letter: P - Previous line, N - Next line, B - Backwards and F - Forward. Now that you've learned how to move single characters at a time, next we learn how to move one word at a time. To do this, you can use M-f (Meta and f) or M-b (Meta and b) to move forwards and backwards, one word at a time. >> Try moving one word at a time by using M-f and M-b on this line. Notice how the Ctrl and Meta key combinations perform related functions. C-f moves one letter forward, whereas M-f moves one word forward. There are many key combinations in mg, where C- will perform one function and M- will perform a similar related function. Most probably by now you have moved passed the bottom of the text which was initially shown to you when you opened this document. mg redraws your terminal screen so that the cursor is in the middle. This is a feature of mg, which allows you to see the lines before and after the current cursor position. The same effect can be achieved manually. >> Now move the cursor down to this line and then type C-l (that's Control and lowercase L). Note that C-l refreshes the screen and centers it on the line you typed it on. To move to the beginning or end of a line, you can use the Home and End keys, or you can use C-a and C-e to move to the beginning and end. >> Use C-a and C-e to move to the beginning and end of this line. The next commands we will learn is how to move up and down, one page at a time. To do this, you can use the Page Up (sometimes labelled PgUp) and Page Down (sometimes labelled PgDn) keys. You can also use C-v and M-v to do this. C-v moves the cursor down one page and M-v moves it up one page. >> Try using M-v and C-v to move up and down, one page at a time. The final two motion commands we will learn are M-< (Meta-Less than) and M-> (Meta-Greater than) which move you to the beginning and end of a file, respectively. You may not want to try that now as you will probably lose your place in this tutorial. Note that on most terminals, < is above the , key, so you'll need to press the Shift key to type <. Movement Summary ----------------- The following is a summary of the movement commands we've learned so far: C-f Move forward one character (can also use right arrow key). C-b Move backward one character (can also use left arrow key). C-p Move up one line (can also use up arrow key). C-n Move down one line (can also use down arrow key). M-f Move forward one word. M-b Move backward one word. C-a Move to beginning of line (can also use Home key). C-e Move to end of line (can also use End key). C-v Move forward one page (can also use PgDn/Page Down key). M-v Move backward one page (can also use PgUp/Page Up key). M-< Move to beginning of file. M-> Move to end of file. Now that you've mastered the basics of moving around in mg, you can cause mg to execute these commands multiple times. The way to do this is to type C-u followed by some digits followed by a movement command. >> Type C-u 5 C-f to move forward 5 characters. In general, C-u allows you to execute any command multiple times, not just cursor motion commands. The only exception to this rule are C-v and M-v. When using these two commands with an argument, they move the cursor by that many lines instead of pages. Cancelling mg Commands ---------------------- If you have started typing out a command that you didn't mean to finish, you can use the C-g command to cancel the command immediately. >> For example, type C-u 50 and then type C-g to cancel the C-u command. >> Type Esc and then C-g to cancel the Esc key. In general, you can use C-g to stop any mg commands. You may type it multiple times if you wish. You should see the word "Quit" appear in the bottom of the screen when you type C-g indicating that a command was cancelled. In general, when in doubt, use C-g to get out of trouble. Inserting/Deleting Text ----------------------- To insert text anywhere, simply move your cursor to the appropriate position and begin typing. To delete characters, use the backspace key. If you use M- (Meta and backspace key), you will delete one word instead of one character at a time. To delete characters to the right of the cursor, you can use C-d to delete characters to the right of the current position. If you use M-d instead of C-d, you can delete one word at a time instead of one character at a time. >> Try inserting and deleting characters and words on this line. Note that if you type too many characters on a single line, the line will scroll off the screen and you will see a $ on the line to indicate that the line is too long to fit on the screen at one time. To delete a line at a time, you can use C-k to kill the line from the current cursor position to the end of the line. You can type C-k multiple times to kill many lines. You can issue insert or delete commands multiple times using C-u. For example, C-u 10 e will type out eeeeeeeeee, C-u 4 M-d will delete four words to the right of the cursor and so on. To undo any operation, you can use C-_ (that's control-underscore). Now if you kill something that you didn't mean to, you can yank it back from the dead by using C-y. In general, when you kill something bigger than a single character, mg saves it in a buffer somewhere and you can restore it by using C-y. This is useful for moving text around. You can kill text in one place, move your cursor to the new location and then use C-y to paste it there. Search for Text --------------- To search for text, type C-s followed by the text you wish to search for. Note that as you start typing the characters, mg automatically searches as you type the characters. To continue searching the text you're looking for, type C-s to find the next instance. To search in reverse, type C-r instead of C-s. If you type C-s or C-r twice, it will simply search for the last text that you searched for. To stop searching for text, simply use the cursor keys (or C-f, C-b etc.) or C-g to stop the search operation. >> Use C-s foo to search for "foo" in the text. You can use C-s again to find other instances of foo in the file. Note that if a word cannot be found, it will say Failing I-search: at the bottom of the screen. Typing C-s again will wrap the search around from the top of the file and begin searching from there. Replace Text ------------ To replace text, use M-%. You will be prompted for the text to search for and the text to replace it with. You will then be taken to the first instance of text from the current position. At this point you can do one of the following: y - Replace the text at this instance and search for more items. n - Skip this instance and search for more items. . or Enter - Stop replacing text (you can also use C-g). ! - Replace all the instances without prompting at each one. >> Try replacing "frobnitz" with "zutwalt" on this line. Cut/Copy/Paste Text ------------------- As explained above, you can cut regions using C-k to kill multiple lines. To paste the text that you just cut, simply move your cursor to the point and then type C-y to restore the text. You may type C-y multiple times to restore the text. Hence, to copy text, you can use C-k to kill all the lines, use C-y to restore it immediately, then move to the region you want to copy it to and then type C-y again to restore the last cut text block again. Another way to cut or copy chunks of text is to first position your cursor at the starting point of the chunk of text. Then type C- to mark this as the starting point to cut or copy. Then move the cursor to the end point of the text chunk that you wish to manipulate. Then type C-w to cut the region, or M-w to copy the region. If you wish to cancel marking a block of text, simply type C-g to cancel the operation. To paste the region that you've cut or copied above, simply move your cursor to the desired location and then type C-y to paste it. Status Line ----------- At the bottom of your screen is a reverse highlighted line. This is the status line and lets you know some useful information about the file you're editing. On the status line, you should see "Mg: tutorial". This lets you know that you're editing a file named "tutorial". If you've edited this file and not saved it, it should have a "**" to the left of those words. If this file is read-only, you should see a "%%" to the left of those words. To the right of the status line, you should see L followed by digits and, if column-number-mode is enabled, C followed by some more digits. Type M-x column-number-mode Enter to enable it if it is disabled (the default). These indicate the line number and column number of the file that your cursor is currently on. If you move the cursor around, you should see the line and column number change. In the middle of the screen, you should see the word "(fundamental)" which indicates that the current editing mode is "fundamental-mode". The mg editor also supports a c-mode that is more suited to editing C code. There are also some other useful editing modes for different situations. See the man page for mg(1) to learn about the various editing modes. Opening and Saving Files ------------------------ To open a file, you can use C-x C-f. You will then be prompted for a file name. If you type a file name that doesn't already exist, a new file will be opened for you. If the file name already exists, then it will be opened for you and you can begin editing it. Note that you do not need to type the whole file name for an existing file. You can type part of the file name and then press the TAB key. If there is only file name that matches, mg will fill in the rest of the file name for you. If there are multiple files, mg will display that the choice is ambiguous. If you type the TAB key again, mg will show you all the available choices for file names. NOTE: If you type C-x f instead of C-x C-f, you can use C-g to cancel the Set-Fill-Column command. You can also use C-g to cancel the C-x C-f command if you don't wish to open a new file. To save the file once you've edited it, use C-x C-s to save the file. When mg is done saving the file, you should see the words "Wrote /path/to/file" in the bottom of your screen. In general, it is a good idea to save quite often. When you save a file, mg saves a backup of the file with a tilde (~) character at the end. If you decide to open a directory instead of a file, mg will transition into a mode called dired. Dired fills a buffer with the contents of the selected directory, one file or sub-directory's details per line. Some basic file management functions can be performed on the files and sub-directories in the buffer. For example, with the cursor over a specific file: Pressing c will give you the opportunity to copy the file. Pressing d will mark the file for deletion. Pressing x will unlink files previously marked for deletion. Pressing Return will open the highlighted file into it's own buffer for editing. There are more dired commands, see the man page for further information. Working with Buffers and Windows -------------------------------- Once a file is loaded into mg, it is often referred to as a buffer. The mg editor is capable of editing multiple buffers at the same time. When you open a second file with C-x C-f, the first buffer is still being edited by mg. Both buffers can be viewed simultaneously because mg can support several windows at the same time, each one displaying different text. To split a screen into two horizontal windows use C-x 2. To return to one window, use C-x 1 to close the other windows and only keep the current window. >> Use C-x 2 to split the screen into two windows. >> Use C-x o to move from one window to the other. You can scroll up and down in each window using the cursor keys or C-n and C-p keys. >> Use C-x 1 to restore back to one window. You can list all the buffers that are opened by mg by typing C-x C-b. The screen should divide into two and the top window will list the buffers that are currently open. Use C-x o to switch to the top window, then use the arrow keys to move to the buffer you wish to switch to, and then type the Enter key to select that buffer. Then use C-x 1 to switch back to only one window. You may also move back to the last opened buffer by using C-x b to toggle back and forth between two buffers. Note the difference between C-x b and C-x C-b. >> Use C-x C-f to open a new file >> Use C-x b to switch back and forth between that buffer and this one. To kill any buffer, use C-x k. You will be prompted for the buffer to kill. By default, the current buffer is selected as the one to kill. You may also type another buffer name or use C-g to cancel the operation. Extended Commands ----------------- The mg editor has several extended commands, more than what can be covered by the Control and Meta keys. The mg editor gets around this by using what is called the X (eXtend) command. There are two forms of this: C-x Character eXtension. Followed by one character. M-x Named character eXtension. Followed by a long command. You've already seen C-x C-f and C-x C-s to open and save a file. There are other longer commands. For instance, you can also open a file by typing M-x find-file Enter. When you type a command using M-x, mg prompts you for the command at the bottom of the screen. You can type out the whole command if you wish, or you can type out part of the command and then use the TAB key for autocompleting the command. For instance, to replace text, you can type M-x repl TAB enter to execute the replace-text command. To cancel this command, type C-g. To see a list of all available mg(1) commands, consult the man page. Exiting mg ---------- To exit mg temporarily and return to the shell, use C-z. This will take you back to the command shell. To return back to mg, type fg in the shell and you will be returned to your mg session. To exit mg permanently, type C-x C-c. If you have any unsaved buffers, you will be asked if you wish to save them or not. Conclusion ---------- This tutorial is meant to get new users up and running with mg. There is more information available via the mg(1) man page. If you have any suggestions for improvement, please don't hesitate to drop a message or (better still) submit a diff to tech@openbsd.org. Author Info ----------- Original Author of this document: Mayukh Bose, Date last updated: 2018-05-27 Copyright --------- None. This document is in the public domain.