Annotation of src/usr.bin/mg/tutorial, Revision 1.18
1.5 kjell 1: The mg Tutorial
2: ---------------
1.1 deraadt 3:
1.5 kjell 4: The mg editor is a public domain editor intended to loosely resemble GNU Emacs,
5: while still retaining fast speed and a small memory footprint.
1.1 deraadt 6:
1.5 kjell 7: Most mg commands involve using the Control (sometimes labelled "Ctrl") or the
8: Meta (sometimes labelled "Alt") key. We will use the following conventions in
9: this tutorial:
1.1 deraadt 10:
1.5 kjell 11: C-<chr> means hold down the Control key while typing the character <chr>.
12: M-<chr> means hold down the Meta key while typing the character <chr>.
1.1 deraadt 13:
1.5 kjell 14: If you don't have a Meta key, you can use Esc instead. Press and release the
15: Esc key and type <chr>. This is equivalent to M-<chr>.
1.1 deraadt 16:
1.5 kjell 17: The first thing to learn is how to move up and down a document. To move your
1.15 lum 18: cursor down a line, use the down-arrow cursor key or C-n (Control and n).
1.1 deraadt 19:
1.5 kjell 20: >> Now type C-n multiple times and move your cursor past this line.
1.1 deraadt 21:
1.15 lum 22: Congratulations. You have now learned how to move your cursor down. To move
23: your cursor up one line, you can use the up-arrow cursor key or C-p (Control
24: and p).
1.1 deraadt 25:
1.5 kjell 26: >> Try using C-p and C-n to move up and down and then move past this line.
1.1 deraadt 27:
1.5 kjell 28: The next commands to learn are how to move your cursor left and right. To do
29: this, you can use the left-arrow and right-arrow cursor keys. Alternatively,
30: you can use C-b and C-f to do this.
1.1 deraadt 31:
1.5 kjell 32: >> Practise using the arrow keys or C-b and C-f on this line.
1.1 deraadt 33:
1.5 kjell 34: To make it easy to remember these commands, it helps to remember by letter:
35: P - Previous line, N - Next line, B - Backwards and F - Forward.
1.1 deraadt 36:
1.5 kjell 37: Now that you've learned how to move single characters at a time, next we learn
38: how to move one word at a time. To do this, you can use M-f (Meta and f) or
39: M-b (Meta and b) to move forwards and backwards, one word at a time.
1.1 deraadt 40:
1.5 kjell 41: >> Try moving one word at a time by using M-f and M-b on this line.
1.1 deraadt 42:
1.5 kjell 43: Notice how the Ctrl and Meta key combinations perform related functions. C-f
44: moves one letter forward, whereas M-f moves one word forward. There are many
45: key combinations in mg, where C-<chr> will perform one function and M-<chr>
46: will perform a similar related function.
1.1 deraadt 47:
1.15 lum 48: Most probably by now you have moved passed the bottom of the text which was
49: initially shown to you when you opened this document. mg redraws your terminal
50: screen so that the cursor is in the middle. This is a feature of mg, which
51: allows you to see the lines before and after the current cursor position. The
52: same effect can be achieved manually.
1.1 deraadt 53:
1.5 kjell 54: >> Now move the cursor down to this line and then type C-l (that's Control and
1.15 lum 55: lowercase L).
1.1 deraadt 56:
1.5 kjell 57: Note that C-l refreshes the screen and centers it on the line you typed it on.
1.1 deraadt 58:
1.5 kjell 59: To move to the beginning or end of a line, you can use the Home and End keys,
60: or you can use C-a and C-e to move to the beginning and end.
1.1 deraadt 61:
1.5 kjell 62: >> Use C-a and C-e to move to the beginning and end of this line.
1.1 deraadt 63:
1.5 kjell 64: The next commands we will learn is how to move up and down, one page at a time.
65: To do this, you can use the Page Up (sometimes labelled PgUp) and Page Down
66: (sometimes labelled PgDn) keys. You can also use C-v and M-v to do this. C-v
67: moves the cursor down one page and M-v moves it up one page.
1.2 mickey 68:
1.5 kjell 69: >> Try using M-v and C-v to move up and down, one page at a time.
1.1 deraadt 70:
1.5 kjell 71: The final two motion commands we will learn are M-< (Meta-Less than) and
1.7 lum 72: M-> (Meta-Greater than) which move you to the beginning and end of a file,
73: respectively. You may not want to try that now as you will probably lose your
74: place in this tutorial. Note that on most terminals, < is above the , key, so
75: you'll need to press the Shift key to type <.
1.1 deraadt 76:
1.5 kjell 77: Movement Summary
1.1 deraadt 78: -----------------
79:
1.5 kjell 80: The following is a summary of the movement commands we've learned so far:
1.1 deraadt 81:
1.11 lum 82: C-f Move forward one character (can also use right arrow key).
83: C-b Move backward one character (can also use left arrow key).
84: C-p Move up one line (can also use up arrow key).
85: C-n Move down one line (can also use down arrow key).
86: M-f Move forward one word.
87: M-b Move backward one word.
88: C-a Move to beginning of line (can also use Home key).
89: C-e Move to end of line (can also use End key).
90: C-v Move forward one page (can also use PgDn/Page Down key).
91: M-v Move backward one page (can also use PgUp/Page Up key).
92: M-< Move to beginning of file.
1.5 kjell 93: M-> Move to end of file.
94:
95: Now that you've mastered the basics of moving around in mg, you can cause mg
1.11 lum 96: to execute these commands multiple times. The way to do this is to type C-u
97: followed by some digits followed by a movement command.
1.5 kjell 98:
99: >> Type C-u 5 C-f to move forward 5 characters.
100:
101: In general, C-u allows you to execute any command multiple times, not just
102: cursor motion commands. The only exception to this rule are C-v and M-v.
103: When using these two commands with an argument, they move the cursor by that
104: many lines instead of pages.
1.1 deraadt 105:
1.11 lum 106: Cancelling mg Commands
1.1 deraadt 107: ----------------------
108:
1.5 kjell 109: If you have started typing out a command that you didn't mean to finish, you
110: can use the C-g command to cancel the command immediately.
1.1 deraadt 111:
1.5 kjell 112: >> For example, type C-u 50 and then type C-g to cancel the C-u command.
113: >> Type Esc and then C-g to cancel the Esc key.
1.1 deraadt 114:
1.5 kjell 115: In general, you can use C-g to stop any mg commands. You may type it multiple
116: times if you wish. You should see the word "Quit" appear in the bottom of the
117: screen when you type C-g indicating that a command was cancelled.
1.1 deraadt 118:
1.5 kjell 119: In general, when in doubt, use C-g to get out of trouble.
1.1 deraadt 120:
1.5 kjell 121: Inserting/Deleting Text
122: -----------------------
123:
124: To insert text anywhere, simply move your cursor to the appropriate position
125: and begin typing. To delete characters, use the backspace key. If you use
1.7 lum 126: M-<backspace> (Meta and backspace key), you will delete one word instead
1.5 kjell 127: of one character at a time.
128:
129: To delete characters to the right of the cursor, you can use C-d to delete
130: characters to the right of the current position. If you use M-d instead of
131: C-d, you can delete one word at a time instead of one character at a time.
132:
133: >> Try inserting and deleting characters and words on this line.
134:
135: Note that if you type too many characters on a single line, the line will
136: scroll off the screen and you will see a $ on the line to indicate that the
137: line is too long to fit on the screen at one time.
138:
139: To delete a line at a time, you can use C-k to kill the line from the current
140: cursor position to the end of the line. You can type C-k multiple times to
141: kill many lines.
142:
143: You can issue insert or delete commands multiple times using C-u. For example,
144: C-u 10 e will type out eeeeeeeeee, C-u 4 M-d will delete four words to the
145: right of the cursor and so on.
146:
1.12 lum 147: To undo any operation, you can use C-_ (that's control-underscore).
1.5 kjell 148:
149: Now if you kill something that you didn't mean to, you can yank it back from
150: the dead by using C-y. In general, when you kill something bigger than a single
151: character, mg saves it in a buffer somewhere and you can restore it by using
152: C-y. This is useful for moving text around. You can kill text in one place,
153: move your cursor to the new location and then use C-y to paste it there.
154:
155: Search for Text
156: ---------------
157:
158: To search for text, type C-s followed by the text you wish to search for. Note
159: that as you start typing the characters, mg automatically searches as you type
160: the characters.
161:
162: To continue searching the text you're looking for, type C-s to find the next
163: instance. To search in reverse, type C-r instead of C-s. If you type C-s or
164: C-r twice, it will simply search for the last text that you searched for.
165:
166: To stop searching for text, simply use the cursor keys (or C-f, C-b etc.) or
167: C-g to stop the search operation.
168:
169: >> Use C-s foo to search for "foo" in the text. You can use C-s again to
170: find other instances of foo in the file.
171:
172: Note that if a word cannot be found, it will say Failing I-search: at the
173: bottom of the screen. Typing C-s again will wrap the search around from the
174: top of the file and begin searching from there.
175:
176: Replace Text
177: ------------
178:
179: To replace text, use M-%. You will be prompted for the text to search for and
180: the text to replace it with. You will then be taken to the first instance of
181: text from the current position. At this point you can do one of the following:
182:
1.11 lum 183: y - Replace the text at this instance and search for more items.
184: n - Skip this instance and search for more items.
1.12 lum 185: . or Enter - Stop replacing text (you can also use C-g).
1.5 kjell 186: ! - Replace all the instances without prompting at each one.
187:
188: >> Try replacing "frobnitz" with "zutwalt" on this line.
189:
190: Cut/Copy/Paste Text
191: -------------------
192:
193: As explained above, you can cut regions using C-k to kill multiple lines. To
194: paste the text that you just cut, simply move your cursor to the point and
195: then type C-y to restore the text. You may type C-y multiple times to restore
196: the text. Hence, to copy text, you can use C-k to kill all the lines, use C-y
197: to restore it immediately, then move to the region you want to copy it to and
198: then type C-y again to restore the last cut text block again.
199:
200: Another way to cut or copy chunks of text is to first position your cursor at
1.7 lum 201: the starting point of the chunk of text. Then type C-<space> to mark this as
202: the starting point to cut or copy. Then move the cursor to the end point of the
1.5 kjell 203: text chunk that you wish to manipulate. Then type C-w to cut the region, or
204: M-w to copy the region. If you wish to cancel marking a block of text, simply
205: type C-g to cancel the operation.
206:
207: To paste the region that you've cut or copied above, simply move your cursor
208: to the desired location and then type C-y to paste it.
209:
210: Status Line
211: -----------
212:
213: At the bottom of your screen is a reverse highlighted line. This is the status
214: line and lets you know some useful information about the file you're editing.
215:
216: On the status line, you should see "Mg: tutorial". This lets you know that
217: you're editing a file named "tutorial". If you've edited this file and not
218: saved it, it should have a "**" to the left of those words. If this file is
219: read-only, you should see a "%%" to the left of those words.
220:
1.18 ! bcallah 221: To the right of the status line, you should see L followed by digits
! 222: and, if column-number-mode is enabled, C followed by some more digits.
! 223: Type M-x column-number-mode Enter to enable it if it is disabled (the
! 224: default). These indicate the line number and column number of the file
! 225: that your cursor is currently on. If you move the cursor around, you
! 226: should see the line and column number change.
1.5 kjell 227:
228: In the middle of the screen, you should see the word "(fundamental)" which
229: indicates that the current editing mode is "fundamental-mode". The mg editor
230: also supports a c-mode that is more suited to editing C code. There are also
1.6 lum 231: some other useful editing modes for different situations. See the man page
1.5 kjell 232: for mg(1) to learn about the various editing modes.
233:
234: Opening and Saving Files
235: ------------------------
236:
237: To open a file, you can use C-x C-f. You will then be prompted for a file name.
238: If you type a file name that doesn't already exist, a new file will be opened
239: for you. If the file name already exists, then it will be opened for you and
240: you can begin editing it. Note that you do not need to type the whole file
241: name for an existing file. You can type part of the file name and then press
242: the TAB key. If there is only file name that matches, mg will fill in the rest
243: of the file name for you. If there are multiple files, mg will display that
244: the choice is ambiguous. If you type the TAB key again, mg will show you all
245: the available choices for file names.
246:
247: NOTE: If you type C-x f instead of C-x C-f, you can use C-g to cancel the
248: Set-Fill-Column command. You can also use C-g to cancel the C-x C-f command
249: if you don't wish to open a new file.
250:
251: To save the file once you've edited it, use C-x C-s to save the file. When
252: mg is done saving the file, you should see the words "Wrote /path/to/file"
253: in the bottom of your screen. In general, it is a good idea to save quite
254: often. When you save a file, mg saves a backup of the file with a tilde (~)
255: character at the end.
1.1 deraadt 256:
1.16 lum 257: If you decide to open a directory instead of a file, mg will transistion into a
258: mode called dired. Dired fills a buffer with the contents of the selected
259: directory, one file or sub-directory's details per line. Some basic file
260: management functions can be performed on the files and sub-directories in the
261: buffer. For example, with the cursor over a specific file:
262:
263: Pressing c will give you the opportunity to copy the file.
264: Pressing d will mark the file for deletion.
265: Pressing x will unlink files previously marked for deletion.
266: Pressing Return will open the highlighted file into it's own buffer for
267: editing.
268:
269: There are more dired commands, see the man page for further information.
270:
1.13 lum 271: Working with Buffers and Windows
272: --------------------------------
1.10 lum 273:
1.13 lum 274: Once a file is loaded into mg, it is often referred to as a buffer.
275:
276: The mg editor is capable of editing multiple buffers at the same time. When you
277: open a second file with C-x C-f, the first buffer is still being edited by mg.
278:
279: Both buffers can be viewed simultaneously because mg can support several windows
280: at the same time, each one displaying different text. To split a screen into two
281: horizontal windows use C-x 2. To return to one window, use C-x 1 to close the
282: other windows and only keep the current window.
1.10 lum 283:
284: >> Use C-x 2 to split the screen into two windows.
285:
286: >> Use C-x o to move from one window to the other. You can scroll up and down
287: in each window using the cursor keys or C-n and C-p keys.
288:
289: >> Use C-x 1 to restore back to one window.
290:
1.5 kjell 291: You can list all the buffers that are opened by mg by typing C-x C-b. The
292: screen should divide into two and the top window will list the buffers that
1.13 lum 293: are currently open. Use C-x o to switch to the top window, then use the arrow
294: keys to move to the buffer you wish to switch to, and then type the Enter key to
1.5 kjell 295: select that buffer. Then use C-x 1 to switch back to only one window.
296:
297: You may also move back to the last opened buffer by using C-x b to toggle back
298: and forth between two buffers. Note the difference between C-x b and C-x C-b.
299:
300: >> Use C-x C-f to open a new file
301: >> Use C-x b to switch back and forth between that buffer and this one.
302:
303: To kill any buffer, use C-x k. You will be prompted for the buffer to kill.
304: By default, the current buffer is selected as the one to kill. You may also
305: type another buffer name or use C-g to cancel the operation.
1.1 deraadt 306:
1.5 kjell 307: Extended Commands
308: -----------------
1.1 deraadt 309:
1.5 kjell 310: The mg editor has several extended commands, more than what can be covered
311: by the Control and Meta keys. The mg editor gets around this by using what is
312: called the X (eXtend) command. There are two forms of this:
313:
314: C-x Character eXtension. Followed by one character.
315: M-x Named character eXtension. Followed by a long command.
316:
317: You've already seen C-x C-f and C-x C-s to open and save a file. There are
318: other longer commands. For instance, you can also open a file by typing
1.17 tb 319: M-x find-file Enter. When you type a command using M-x, mg prompts you for
1.5 kjell 320: the command at the bottom of the screen. You can type out the whole command
321: if you wish, or you can type out part of the command and then use the TAB key
322: for autocompleting the command.
1.1 deraadt 323:
1.5 kjell 324: For instance, to replace text, you can type M-x repl TAB enter to execute
325: the replace-text command. To cancel this command, type C-g.
1.1 deraadt 326:
1.6 lum 327: To see a list of all available mg(1) commands, consult the man page.
1.1 deraadt 328:
1.5 kjell 329: Exiting mg
330: ----------
1.1 deraadt 331:
1.5 kjell 332: To exit mg temporarily and return to the shell, use C-z. This will take you
333: back to the command shell. To return back to mg, type fg in the shell and you
334: will be returned to your mg session.
1.1 deraadt 335:
1.5 kjell 336: To exit mg permanently, type C-x C-c. If you have any unsaved buffers, you
337: will be asked if you wish to save them or not.
1.1 deraadt 338:
1.5 kjell 339: Conclusion
340: ----------
1.1 deraadt 341:
1.5 kjell 342: This tutorial is meant to get new users up and running with mg. There is more
1.6 lum 343: information available via the mg(1) man page. If you have any suggestions for
1.5 kjell 344: improvement, please don't hesitate to drop a message or (better still) submit
1.6 lum 345: a diff to tech@openbsd.org.
1.1 deraadt 346:
1.5 kjell 347: Author Info
348: -----------
1.1 deraadt 349:
1.5 kjell 350: Original Author of this document: Mayukh Bose,
1.18 ! bcallah 351: Date last updated: 2018-05-27
1.1 deraadt 352:
1.5 kjell 353: Copyright
1.1 deraadt 354: ---------
355:
1.5 kjell 356: None. This document is in the public domain.
![[BACK]](/icons/back.gif){kind=icon}
Return to tutorial CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mg