X-Git-Url: https://pd.if.org/git/?p=pd_readline;a=blobdiff_plain;f=mg%2Ftutorial;fp=mg%2Ftutorial;h=f025f67f2a36311918ad116a6e4da543670faf3a;hp=0000000000000000000000000000000000000000;hb=a9843085ec916c175bd245a8398f30e6cc03f984;hpb=26fe4e09c6c3c250334fdeed60ce3061febecde2 diff --git a/mg/tutorial b/mg/tutorial new file mode 100644 index 0000000..f025f67 --- /dev/null +++ b/mg/tutorial @@ -0,0 +1,349 @@ +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, 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. Note how +mg has redrawn your screen so that the cursor is now in the middle of the +screen. This is a feature of mg, which allows you to see the lines before and +after the current cursor position. + +To move your cursor up, 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. + +Next, we will learn how to refresh and redraw the screen. + +>> Now move the cursor down to this line and then type C-l (that's Control and + lowercase L) to refresh the screen. + +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 C +followed by some more digits. 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. + +Windows +------- + +The mg editor 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 do +this. 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. + +Buffers +------- + +The mg editor is capable of editing multiple files at the same time. When you +open a second file with C-x C-f, the first file is still being edited by mg. +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 (we already learned +this key combination above in the Windows section) and 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 edit files in multiple windows, use C-x 2 to split the screen into two +windows. Then use C-x C-f to open a new file in one of the two windows. You +can then switch between the two windows using C-x o. You can switch between +buffers in any window using C-x b. To go back to one window, use C-x 1. + +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 open-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: 2012-05-25 + +Copyright +--------- + +None. This document is in the public domain. + +