Initial import.

chapters/00.markdown

@@ -0,0 +1,38 @@
+Prerequisites
+=============
+
+To use this book you should have the latest version of Vim installed, which is
+version 7.3 at the time of this writing.  New versions of Vim are almost always
+backwards-compatible, so everything in this book should work just fine with
+newer versions.
+
+You should be comfortable editing files in Vim.  You should know basic Vim
+terminology like "buffer", "window", "normal mode", "insert mode" and "text
+object".
+
+If you're not at that point yet go through the `vimtutor` program, use Vim
+exclusively for a month or two, and come back when you've got Vim burned into
+your fingers.
+
+You should have some programming experience.  If you've never programmed before
+check out [Learn Python the Hard Way](http://learnpythonthehardway.org/) first.
+
+Creating a Vimrc File
+---------------------
+
+If you already know what a vimrc file is and have one, go on to the next
+chapter.
+
+A vimrc file is a file you create that contains some Vimscript code.  Vim will
+automatically run the code inside this file every time you open Vim.
+
+On Linux and Mac OS X this file is located in your home directory and named
+`.vimrc`.
+
+On Windows this file is located in your home folder and named `_vimrc`.
+
+To easily find the location and name of the file on *any* operating system, run
+`:echo $MYVIMRC` in Vim.  The path will be displayed at the bottom of the
+screen.
+
+Create this file if it doesn't already exist.

chapters/01.markdown

@@ -0,0 +1,62 @@
+Echoing Messages
+================
+
+The first piece of Vimscript we'll look at is `echom`.
+
+You can read the full documentation for the command by running `:help echom` in
+Vim.  As you go through this book you should try to read the `:help` for every
+new command you encounter to get a better understanding of how to use each one.
+
+Run the following command:
+
+    :echo "Hello, world!"
+
+You should see `Hello, world!` appear at the bottom of the window.
+
+Persistent Echoing
+------------------
+
+Now run the following command:
+
+    :echom "Hello again, world!"
+
+You should see `Hello again, world!` appear at the bottom of the window.
+
+To see the difference between these two commands, run one more new command:
+
+    :messages
+
+You should see a list of messages.  `Hello, world!` will *not* be in this list,
+but `Hello again, world!` *will* be in it.
+
+When you're writing more complicated Vim scripts later in this book you may find
+yourself wanting to "print some output" to help you debug problems.  Plain old
+`:echo`will print output, but it will often disappear by the time your script is
+done.  Using `:echom` will save the output and let you run `:messages` to view
+it later.
+
+Comments
+--------
+
+Before we move on we should mention comments.  When you write Vimscript code (in
+your `~/.vimrc` file or another one) you can add comments with the `"`
+character, like this:
+
+    " Make space more useful
+    nnoremap <space> za
+
+This doesn't *always* work (that's one of those ugly corners of Vimscript), but
+in most cases it does, and we'll talk about when it won't (and why that
+happens).
+
+Exercises
+---------
+
+Read `:help echo`.
+
+Read `:help echom`.
+
+Read `:help messages`.
+
+Add a line to your vimrc file that displays a friendly ASCII-art cat (`>^.^<`)
+whenever you open Vim.

chapters/02.markdown

@@ -0,0 +1,88 @@
+Setting Options
+===============
+
+Vim has many options you can set to change how it behaves.
+
+There are two main kinds of options: boolean options (either "on" or "off") and
+options that take a value.
+
+Run the following command:
+
+    :set number
+
+Line numbers should appear in Vim.  Now run this:
+
+    :set nonumber
+
+The line numbers should disappear.  `number` is a boolean option -- it can be
+off or on.  You turn it "on" by running `:set number` and "off" with `:set
+nonumber`.
+
+Toggling Options
+----------------
+
+You can also "toggle" boolean options to set them to the *opposite* of whatever
+they are now.  Run this:
+
+    :set number!
+
+The line numbers should reappear.  Now run it again:
+
+    :set number!
+
+They should disappear once more.  Adding a `!` (exclamation point or "bang") to
+a boolean option toggles it.
+
+Checking Options
+----------------
+
+You can ask Vim what an option is currently set to by using a `?`.  Run these
+commands and watch what happens after each:
+
+    :set number
+    :set number?
+    :set nonumber
+    :set number?
+
+Notice how the first `:set number?` command displayed `number` while the second
+displayed `nonumber`.
+
+Options with Values
+-------------------
+
+Some options take a value instead of just being off or on.  Run the following
+commands and watch what happens after each:
+
+    :set number
+    :set numberwidth=10
+    :set numberwidth=4
+    :set numberwidth?
+
+The `numberwidth` option changes how wide the column containing line numbers
+will be.
+
+Try checking what a few other common options are set to:
+
+    :set wrap?
+    :set numberwidth?
+
+Setting Multiple Options at Once
+--------------------------------
+
+Finally, you can specify more than one option in the same `:set` command.  Try
+running this:
+
+    :set number numberwidth=6
+
+Exercises
+---------
+
+Read `:help number`.
+
+Read `:help relativenumber`.
+
+Read `:help numberwidth`.
+
+Read `:help wrap`.
+
+Add a few lines to your vimrc file to set these four options however you like.

chapters/03.markdown

@@ -0,0 +1,77 @@
+Basic Mapping
+=============
+
+If there's one feature of Vimscript that will let you bend Vim to your will it's
+the ability to map keys.  Mapping keys lets you tell Vim: "when I press this
+key, I want you to do this stuff instead of whatever you would normally do".
+
+We're going to start off by mapping keys in normal mode.  We'll talk about how
+to map keys in insert and other modes in the next chapter.
+
+Type a few lines of text into a file, then run:
+
+    :map \ x
+
+Put your cursor somewhere in the text and press `\`.  Notice how Vim deleted the
+character under the cursor, just like if you had pressed `x`.
+
+We already have a key for "delete that character under the cursor", so let's
+change that mapping to something slightly more useful.  Run this command:
+
+    :map \ dd
+
+Now put your cursor on a line somewhere and press `\` again.  This time Vim
+deletes the entire line, because that's what `dd` does.
+
+Special Characters
+------------------
+
+You can use `<keyname>` to tell Vim about special keys that are hard to type.
+Try running this command:
+
+    :map <space> viw
+
+Put your cursor on a word in your text and press the space bar.  Vim will
+visually select the word.
+
+You can also map modifier keys like Ctrl and Alt.  Run this:
+
+    :map <c-d> dd
+
+Now pressing `Ctrl+d` on your keyboard will run `dd`.
+
+Commenting
+----------
+
+Remember in the first lesson where we talked about comments?  Mapping keys is
+one of the places where Vim comments don't work.  Try running this command:
+
+    :map <space> viw " Use space to select a word
+
+If you try pressing `<space>` now, something horrible will almost certainly
+happen.  Why?
+
+When you press the space bar now, Vim thinks you want it to do what
+`viw<space>"<space>Use<space>space<space>to<space>select<space>a<space>word`
+would do.  Obviously, this isn't what we want.
+
+This mapping is even more interesting though, because if you look closely at its
+effect you might notice something strange.  Take a few minutes to try to figure
+out what it is before you move on.  Don't worry if you don't get it now, because
+we'll talk about it more later.
+
+Exercises
+---------
+
+Map the `-` key to "delete the current line, then paste it below the one we're
+on now".  This will let you move lines downward in your file with one keystroke.
+
+Add that mapping command to your `~/.vimrc` file so you can use it any time
+you start Vim.
+
+Figure out how to map the `_` key to move the line up instead of down.
+
+Add that mapping to your `~/.vimrc` file too.
+
+Try to guess how you might remove a mapping and reset a key to its normal
+function.

chapters/04.markdown

@@ -0,0 +1,103 @@
+Modal Mapping
+=============
+
+In the last chapter we talked about how to map keys in Vim.  We used the `map`
+command which made our keys work in normal mode.  If you played around a bit
+before moving on to this chapter, you may have noticed that our mappings also
+took effect in visual mode.
+
+We can be more specific about when we want our mappings to work by using `nmap`,
+`vmap`, and `imap`.  These tell Vim to only use the mapping in normal, visual,
+or insert mode respectively.
+
+Run this command:
+
+    nmap \ dd
+
+Now put your cursor in your text file, make sure you're in normal mode, and
+press `\`.  Vim will delete the current line.
+
+Now enter visual mode and try pressing `\`.  Nothing will happen, because we
+told Vim to only use that mapping in normal mode (and `\` doesn't do anything by
+default).
+
+Run this command:
+
+    vmap \ U
+
+Enter visual mode and select some text, then press `\`.  Vim will convert the
+text to uppercase!
+
+Try the `\` key a few times in normal and visual modes and notice that it now
+does something completely different depending on which mode you're in.
+
+Muscle Memory
+-------------
+
+At first the idea of mapping the same key to do different things depending on
+which mode you're in may sound like a terrible idea.  Why would you want to
+have to stop and think which mode you're in before pressing the key?  Wouldn't
+that negate any time you saved from the mapping itself?
+
+In practice it turns out that this isn't really a problem.  Once you start using
+Vim a lot you won't be thinking about the individual keys you're typing any
+more.  You'll think: "delete a line" and not "press `dd`".  Your fingers and
+brain will learn your mappings and the keys themselves will become subconscious.
+
+Insert Mode
+-----------
+
+Now that we've covered how to map keys in normal and visual mode, let's move on
+to insert mode.  Run this command:
+
+    imap <c-d> dd
+
+You might think that this would let you press `Ctrl+d` whenever you're in insert
+mode to delete the current line.  This would be nice, because now you don't need
+to go back into normal mode to cut out lines!
+
+Go ahead and try it.  It won't work -- instead it will just put two `d`s in your
+file!  That's pretty useless.
+
+The problem is that Vim is doing exactly what we told it to.  We said: "when
+I press `<c-d>` I want you to do what pressing `d` and `d` would normally do".
+
+Well, normally when you're in insert mode and press the `d` key twice, you get
+two `d`s in a row!
+
+To make this mapping do what we intended we need to be very explicit.  Run this
+command to change the mapping:
+
+    imap <c-d> <esc>dd
+
+The `<esc>` is our way of telling Vim to press the Escape key, which will take
+us out of insert mode.
+
+Now try the mapping.  It works!  But notice how you're now back in normal mode.
+This makes sense, because we told Vim that `<c-d>` should exit insert mode and
+delete a line, but we never told it to go back into insert mode.
+
+Run one more command to fix the mapping once and for all:
+
+    imap <c-d> <esc>ddi
+
+The `i` at the end reenters insert mode for us, and our mapping is finally
+complete.
+
+Exercises
+---------
+
+Set up a mapping so that you can press `<c-u>` to convert the current word to
+uppercase when you're in insert mode.  Remember that `U` in visual mode will
+uppercase the selection.  I find this mapping extremely useful when I'm writing
+out the name of a long constant -- I type out the constant in lower case and
+then uppercase it.
+
+Add that mapping to your `~/.vimrc` file.
+
+Set up a mapping so that you can uppercase the current word with `<c-u>` when in
+*normal* mode.  This will be slightly different than the previous mapping
+because you don't need to enter normal mode and you should end up back in normal
+mode instead of in insert mode.
+
+Add that mapping to your `~/.vimrc` file as well.