boon/TUTORIAL.txt

Boon tutorial.   See end for copying conditions.

This tutorial assumes that you know Emacs already.

Make sure boon is installed. Load the colemak configuration with:

(require 'boon-colemak)

You may also

(require 'boon-extras)

if you like.

Turn on boon globally with

(boon-mode)

If you just eval'ed the above, Boon may not be active in the current
buffer. If it is not activated, activate it by

M-x turn-on-boon-mode

Boon indicates the difference between command mode and insert mode in
several ways:

- The modeline says Boon:STATE (where state can be INS or CMD)

- The cursor is a box in command mode, and a bar in insert mode.

- The modeline is red in insert mode (and its regular color in command
  mode)

You can switch to insert mode by typing v (mnemonic: v looks like an
insert mark) and back to command mode by typing <ESC>.

Most Emacs keychord commands via M-... and C-... are accessible as
normal.  For example, M-x turn-off-boon-mode reverts to your regular
experience.

The characters ">>" at the left margin indicate directions for you to
try using a command.  For instance:




[Middle of page left blank for didactic purposes.   Text continues below]


>> You can also type C-u and C-y to scroll


* BASIC CURSOR CONTROL
----------------------

How do you move to a specific place within the text on the screen?

The whole right-hand side of the keyboard is dedicated to this
purpose.


There are several ways you can do this.  You can still use the arrow keys,
but it's more efficient to keep your hands in the standard position
and use the commands: e i u y. These characters
are equivalent to the four arrow keys, like this:

			  Previous line, u
				  :
				  :
   Backward, e  .... Current cursor position .... Forward, i
				  :
				  :
			    Next line, y

>> Move the cursor to the line in the middle of that diagram.

You'll find it easy to remember these letters by their location on the
keyboard.  Note that, when you navigate within a line your hand stays
on the home row.  Navigating lines happens on the top row. Soon you
will forget the letters that your hand is typing when moving the
cursor.  You will be using these basic cursor positioning commands a
lot, but there are faster ways to go about moving the cursor.

The movement of cursor across lines is the same as in regular Emacs.

If moving by characters is too slow, you can move by words. The key "o"
moves forward a word and "n" moves back a word.

>> Type a few o's and n's.

As in regular Emacs, when you are in the middle of a word, o moves to
the end of the word.  When you are in white space between words, o
moves to the end of the following word.  "n" works likewise in the
opposite direction. In fact, o and n move by whole syntactic units.

>> Type o and n a few times within a parenthesized expression. Combine
   it with e and i to get to the place you want.


54 / ((8 + y) * (x - 3))

Notice that you can quickly move in the expression while staying
comfortably on the home row.

You can move to the beginning or end of a line by typing "l" or ";".
As u and y, these line-based commands are on the top row.  Emacs tries
to manage the cursor position inside a line intelligently.  This often
works, but one sometimes need to quickly move to the beginning or end
of line after moving up or down. You can do all this by staying on the
top row.

If you want to speed up moving up and down, use the shift key: "U" and
"Y" move by whole paragraphs.

>> Try a couple of "U", and then a couple of "Y".
   Try a couple of "l", and then a couple of ";"

Checkout the cheat sheet (linked from README) for a summary of
movement operations.

>> Try all of these commands now a few times for practice.
   These are the most often used commands.

Two other (less important) cursor motion commands are "<d" (two
characters), which moves to the beginning of the whole text, and ">d",
which moves to the end of the whole text.

>> Try <d now, to move to the beginning of the tutorial.
   Then use Y repeatedly to move back here.

In fact, the 'd' character in the above sequences is the argument to
the commands < and >. We will see later more commands taking arguments
which can be specified in this way.

>> Try >p and <p to move to the beginning and end of a paragraph.

You can type a prefix argument by using "\" (backslash).

* OTHER MOVEMENT COMMANDS
-------------------------

There are three other movement commands, bound to j, h and k.
- j (mnemonic: jump) expects a character an jumps to it

>> Move to this line and type j-

- k (mnemonic: bacK to marK) jumps pops a mark and jumps to it. (If a region is active, exchange point and mark)

- h (mnemonic: hop) activates ace-jump-mode (if installed)

* IF EMACS STOPS RESPONDING
---------------------------

If Emacs stops responding to your commands, you can stop it safely by
typing C-g.  You can use C-g to stop a command which is taking too
long to execute.

You can also use C-g to discard a numeric argument or the beginning of
a command that you do not want to finish.

<ESC> is an alternative which works in many contexts.


* C-x prefix
-------------

Instead of the C-x prefix; you may just type 'x'

>> Type x 2 to split this window
>> Type x 1 to close the other windows

* INSERTING AND DELETING
------------------------

If you want to insert text, type 'v' (can you remember the mnemonic?).
Ordinary characters, like A, 7, *, etc., are then inserted as you type
them.  To insert a Newline character, type <Return>.

In insert mode, regular Emacs editing commands can be used.

>> Type v to insert some text; then <ESC> to go back to command mode.


Deleting text is mostly done with the 't' command (mnemonic: take).

>> Type "te" to delete the character before the cursor

In the above "e" is the argument to the "t" command.


>> Type "tn" to delete backwards, up to the beginning of a word

You can also use a left-hand region specifier to delete

>> Type "ts" to delete the symbol where the cursor is (even if in the
   middle of the symbol)


The region specifiers are defined in the boon-select-map keymap. (Type
C-h v boon-select-map to inspect it)

* MULTIPLYING
-------------

Arguments can be given a repeat count.

>> Type "t7e" to delete seven characters forward.

To insert a character several times, you can use the escaping
command "q" (mnemonic: quote).

>> Try that now -- type \ 8 q * to insert ********.

You can also kill a segment of text with one uniform method.  Move to
one end of that part, and type <SPC>.  (<SPC> is the Space bar.)
Next, move the cursor to the other end of the text you intend to kill.
As you do this, Emacs highlights the text between the cursor and the
position where you typed C-<SPC>.  Finally, type "t".  This kills all
the text between the two positions.

>> Move the cursor to the Y at the start of the previous paragraph.
>> Type <SPC>.  Emacs should display a message "mark 0"
   at the bottom of the screen.
>> Move the cursor to the n in "end", on the second line of the
   paragraph.
>> Type t.  This will kill the text starting from the Y,
   and ending just before the n.

Selecting text with <SPC> actually takes an argument.

>> Type <SPC> p to select a paragraph

>> Type <SPC> again to undo the selection

The command for yanking is "s". (mnemonic: splice)  

>> Try it; type s to yank the text back.

Shifted "S" does yank-pop.


* UNDO
------

Undo is bound to "-" (minus); while redo is bound to "_" (underscore).

* PARENS
--------

Boon provides help to manipulate parentheses.

The command 'a' (mnemonic: around) adds parentheses around a region.
It takes two arguments:

1. the kind of parentheses to use ('p' for regular parentheses)
2. the region (specified by the same language as the 't' command)

>> Move the cursor inside a word and type 'aps' to
   enclose it in parens.

>> Inspect the kind of parentheses available by typing 'C-h v boon-enclosures <RET>'

It is possible to remove parentheses by using the 'a' operator, which
transforms a region spec to its enclosure.

>> Move the cursor inside a (sexp), and type 'tx' to delete the
   expression.

>> Move the cursor inside another (sexp), and type 'tax' to delete the
   parens.

Region specifiers can be freely combined.



* SEARCHING
-----------

Searching is bound to "f?" (search forward) and "w?" (search backward).

The question mark stands for the kind of thing you want to search. For example
"fe" moves to the next error. "f<spc>" does incremental search.
Use "f C-h" to see all the things you can search.

* HELM
-------

Helm is a very useful package. Boon provides special support for it.

>> If you have not done it yet, install helm now. (package-install 'helm)

The command 'p' starts helm-occur; which does a quick search for all
occurrences of a pattern in the current buffer.

>> Type 'p' now

You are now in a helm "command" state, which accepts a number of
commands to govern helm. One of the most used commands is to revert to
helm insert state. This can be done by typing "v" or "<spc>".

>> type <spc>

then

>> type "helm" <return> to jump to the beginning of this section.

You can search for the current symbol by typing "s" while in helm
command state.

>> Move the cursor to an occurrence of the helm word, and type "ps".

>> Use y and u to select an occurrence, then type <return> to jump to
   the currently selected occurrence

The keymap for this helm command state is boon-helm-command-map.

Other, less common uses for helm are bound to "g?".

>> Type "g C-h" to see the bound helm variants.

* COPYING
---------

This tutorial descends from a long line of Emacs tutorials
starting with the one written by Stuart Cracraft for the original Emacs.

This version of the tutorial is not a part of GNU Emacs, but derived
from the standard Emacs tutorial,


  Copyright (C) 1985, 1996, 1998, 2001-2013 Free Software Foundation,
  Inc.