path: root/usr.bin/mg/tutorial

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-<chr>   means hold down the Control key while typing the character <chr>.
  M-<chr>   means hold down the Meta key while typing the character <chr>.

If you don't have a Meta key, you can use Esc instead. Press and release the
Esc key and type <chr>. This is equivalent to M-<chr>.

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-<chr> will perform one function and M-<chr>
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-<backspace> (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-<space> 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.

If you decide to open a directory instead of a file, mg will transistion 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: 2015-12-21

Copyright
---------

None. This document is in the public domain.