# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1318029930 14400
# Node ID c608cbb9aaaaa9a16e09730ffee0950ce9843343
# Parent  c05078bf9c7f992e193911beef902c5d348cf312
Initial import.

diff -r c05078bf9c7f -r c608cbb9aaaa chapters/00.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/00.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -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.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/01.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/01.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -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.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/02.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/02.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -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.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/03.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/03.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -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.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/04.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/04.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -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.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/05.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/05.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,110 @@
+Strict Mapping
+==============
+
+Hold on, things are about to get a little wild.
+
+So far we've used `map`, `nmap`, `vmap`, and `imap` to create key mappings that
+will save time.  These work, but they have a downside.
+
+Run the following commands:
+
+    :nmap - dd
+    :nmap \ -
+
+Now try pressing `\` (in normal mode).  What happens?
+
+When you press `\` Vim sees the mapping and says "I should run `-` instead".
+But we've already mapped `-` to do something else!  Vim sees that and says "oh,
+now I need to run `dd`", and so it deletes the current line.
+
+When you map keys with these commands Vim will take *other* mappings into
+account.  This may sound like a good thing at first but in reality it's pure,
+unadulterated evil.  Let's talk about why.
+
+Recursion
+---------
+
+Run this command:
+
+    :nmap dd O<esc>jddk
+
+You might think that this would change `dd` to:
+
+* Open a new line above this one.
+* Exit insert mode.
+* Move back down.
+* Delete the current line.
+* Move up to the blank line just created.
+
+In effect, this should "clear the current line".  Try it.
+
+Vim will seem to freeze when you press `dd`.  If you press `<c-c>` you'll get
+Vim back, but there will be a ton of empty lines in your file!  What happened?
+
+This mapping is actually *recursive*!  When you press `dd`, Vim says:
+
+* `dd` is mapped, so perform the mapping.
+    * Open a line.
+    * Exit insert mode.
+    * Move down a line.
+    * `dd` is mapped, so perform the mapping.
+        * Open a line.
+        * Exit insert mode.
+        * Move down a line.
+        * `dd` is mapped, so perform the mapping.
+            * ...
+
+This mapping can never finish running!
+
+Side Effects
+------------
+
+Not only do the `*map` commands we've learned so far run the danger of
+recursing, but because they take other mappings into account they can change
+when we install various plugins.
+
+When you install a new Vim plugin there's a good chance that you won't use and
+memorize every mapping it uses.  Even if you *do*, you'd have to go back and
+look through your `~/.vimrc` file to make sure none of your custom mappings use
+something that the plugin has mapped, and vice versa.
+
+This would make installing plugins tedious and error-prone.  There must be
+a better way.
+
+Nonrecursive Mapping
+--------------------
+
+Vim offers another set of mapping commands that will *not* take mappings into
+account when they perform their actions.  Run these commands:
+
+    :nmap x dd
+    :nnoremap \ x
+
+Now press `\` and see what happens.
+
+When you press `\` Vim ignores the `x` mapping and does whatever it would do for
+`x` by default.  Instead of deleting the current line, it deletes the current
+character.
+
+Each of the `*map` commands has a `*noremap` counterpart that ignores other
+mappings: `nnoremap`, `vnoremap`, and `inoremap`.
+
+When to Use
+-----------
+
+When should you use these nonrecursive variants instead of their normal
+counterparts?  The answer is: always.
+
+**Always.**
+
+**No, seriously, ALWAYS.**
+
+Using a bare `nmap` is just *asking* for pain down the road when you install
+a plugin or add a new custom mapping.  Save yourself the trouble and type the
+extra characters to make sure it never happens.
+
+Exercises
+---------
+
+Convert all the mappings you added to your `~/.vimrc` file in the previous
+chapters to their nonrecursive counterparts.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/06.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/06.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,96 @@
+Leaders
+=======
+
+We've learned how to map keys in a way that won't make us want to tear our hair
+out later, but you might have noticed one more problem.
+
+Every time we do something like `:nnoremap <space> dd` we've overwritten what
+`<space>` normally does.  What if we need that key later?
+
+There are a bunch of keys that you don't normally need in your day-to-day Vim
+usage.  `\` doesn't do anything.  `-`, `H`, `L`, and `<space>` do things that
+you almost never need.  Depending on how you work you may find others that you
+never use.
+
+Those are safe to map, but that only gives us five keys to work with.  What
+happened to Vim's legendary customizability?
+
+Mapping Key Sequences
+---------------------
+
+Unlike Emacs, Vim makes it easy to map more than just single keys.  Run these
+commands:
+
+    :nnoremap -d dd
+    :nnoremap -c ddO
+
+Try them out by typing `-d` and `-c` (quickly) in normal mode.  The first
+creates a custom mapping to delete a line, while the second "clears" a line and
+puts you into insert mode.
+
+This means we can pick a key that we don't care about (like `-`) as a "prefix"
+key and create mappings on top of it.  It means we have to type an extra key to
+activate our mappings, but one extra keystroke can easily be absorbed into
+muscle memory.
+
+If you think this might be a good idea, you're right, and it turns out that Vim
+already has mechanisms for this "prefix" key!
+
+Leader
+------
+
+Vim calls this "prefix" key "leader".  You can set your leader key to whatever
+you like.  Run this command:
+
+    :let mapleader = "-"
+
+You can replace `-` with any key you like.  I personally like `,` even though it
+shadows a useful function, because it's very easy to type.
+
+When you're creating new mappings you can use `<leader>` to mean "whatever
+I have my leader key set to".  Run this command:
+
+    :nnoremap <leader>d dd
+
+Now try it out by pressing your leader key and then `d`.  Vim will delete the
+current line.
+
+Why bother with setting `<leader>` at all, though?  Why not just include your
+"prefix" key directly in your mapping commands?
+
+First, you may decide you need the normal function of your leader later on down
+the road.  Defining it in one place makes it easy to change later.
+
+Second, when someone else is looking at your `~/.vimrc` file they'll immediately
+know what you mean when you say `<leader>`, and they can simply copy your
+mapping into their own `~/.vimrc` if they like it.
+
+Finally, many Vim plugins map things on top of your `<leader>`, so if you've
+already got it set up they will just work.
+
+Local Leader
+------------
+
+Vim has a second "leader" key called "localleader".  This is meant to be
+a prefix for mappings that only take effect for certain types of files, like
+Python files or HTML files.
+
+We'll talk about how to make mappings for specific types of files later in the
+book, but you can go ahead and set your "localleader" now:
+
+    :let maplocalleader = "\"
+
+You can use `<localleader>` in mappings and it will work just like `<leader>`
+does, except for resolving to a different key.
+
+Exercises
+---------
+
+Read `:help mapleader`.
+
+Read `:help maplocalleader`.
+
+Set `mapleader` and `maplocalleader` in your `~/.vimrc` file.
+
+Convert all the mappings you added to your `~/.vimrc` file in the previous
+chapters to be prefixed with `<leader>` so they don't shadow existing commands.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/07.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/07.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,123 @@
+Editing Your Vimrc
+==================
+
+Before we move on to learning more Vimscript lets find a way to make it easier
+to add new mappings to our `~/.vimrc` file.
+
+When you're coding away furiously at a problem and realize a new mapping would
+make your life easier, you should add it to your `~/.vimrc` file right then and
+there to make sure you don't forget, but you *don't* want to lose your
+concentration.
+
+The idea is that you want to make it easier to make it easier to edit text.
+
+That's not a typo.  Read it again.
+
+The idea is that you want to (make it easier to (make it easier to (edit
+text))).
+
+Editing Mapping
+---------------
+
+Lets add a mapping that will open our `~/.vimrc` file in a split so we can edit
+it and get back to coding.  Run this command:
+
+    :nnoremap <leader>ev <c-w>v:edit $MYVIMRC<cr>
+
+I like to think of this command as "**e**dit my **v**imrc file".
+
+`$MYVIMRC` is a special Vim variable that points to your `~/.vimrc` file.  Don't
+worry about that for right now, just trust me that that variable works.
+
+Pressing `<c-w>v` in Vim opens a new vertical split.  If you'd prefer
+a horizontal split replace the `v` with an `s`, but in this age of widescreen
+monitors I don't know why you would.
+
+Take a minute and think through that command in your mind.  The goal is: "open
+my `~/.vimrc` file in a new split".  Why does it work?  Why is every single
+piece of that mapping necessary?
+
+With that mapping you can open up your `~/.vimrc` file with three keystrokes.
+Once you use it a few times it will burn its way into your muscle memory and
+take less than half a second to type.
+
+When you're in the middle of coding and come up with a new mapping that would
+save you time it's now trivial to add it to your `~/.vimrc` file.
+
+Meta Efficiency
+---------------
+
+This is important because part of becoming more efficient is making it *easier*
+for yourself to become more efficient!
+
+Think of it this way: suppose you're trying to become a better digital
+photographer.  When you're practicing taking photos and want to see how they
+came out, you:
+
+* Take a photo.
+* Upload it to your computer.
+* Open it and see how it looks.
+
+That process probably takes a minute.  What if you could improve that?
+
+Let's say you invest $50 and buy an [Eye-Fi](http://www.eye.fi/) memory card.
+The Eye-Fi is a memory card for your camera that has a built-in wifi card, so as
+soon as you snap a photo it gets transferred to your computer.
+
+I know, we're definitely living in the future.  Isn't it awesome?
+
+Now you spend an hour and write a little script to automatically open the photos
+that get transferred to your computer by the Eye-Fi.
+
+You've spent $50 and one hour, but now instead of taking a full minute to check
+your work, it takes ten seconds.
+
+Assuming you charge $100 per hour for freelance work, you've got to make up one
+an a half hours of time for this investment to be worthwhile.  If you're saving
+50 seconds per photo, you need to take about 109 photos for project to pay for
+itself.
+
+109 photos is *nothing*.  It's a drop in the ocean.  A blip that doesn't even
+register on the radar.  You'd blow past that number in a day's practice without
+even noticing.  Hell, you'd take more photos than that in two hours!
+
+The same goes for our new mapping.  It saves us only a few seconds each time we
+use it, but it takes far, *far* less than an hour and a half to set up.
+
+Sourcing Mapping
+----------------
+
+Once you've added a mapping to your `~/.vimrc` file, it doesn't immediately take
+effect.  Your `~/.vimrc` file is only read when you start Vim.  This means you
+need to also run the command manually to make it work in the current session,
+which is a pain.
+
+Let's add a mapping to make this easier:
+
+    :nnoremap <leader>sv :source $MYVIMRC<cr>
+
+I like to think of this command as "**s**ource my **v**imrc file".
+
+The `source` command tells Vim to take the contents of the given file and
+execute it as Vimscript.
+
+Now we can easily add new mappings during the heat of coding.  We:
+
+* Use `<leader>ev` to open the file.
+* Add the mapping.
+* Use `:wq` to write the file and close the split, bringing us back to where we
+  were.
+* Use `<leader>sv` to source the file and make our changes take effect.
+
+That's six keystrokes plus whatever it takes to define the mapping.  It's very
+little overhead, which reduces the chance that we break our concentration.
+
+Exercises
+---------
+
+Add mappings to "edit my `~/.vimrc`" and "source my `~/.vimrc`" to your
+`~/.vimrc` file.
+
+Try them out a few times, adding dummy mappings each time.
+
+Read `:help myvimrc`.
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/08.markdown
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/09.markdown
diff -r c05078bf9c7f -r c608cbb9aaaa chapters/10.markdown
diff -r c05078bf9c7f -r c608cbb9aaaa config.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/config.py	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,3 @@
+title = 'Learn Vimscript the Hard Way'
+author = 'Steve Losh'
+author_url = 'http://stevelosh.com'
diff -r c05078bf9c7f -r c608cbb9aaaa introduction.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/introduction.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,14 @@
+[Learn Vimscript the Hard Way][book] is a short book for users of the Vim editor who
+want to learn how to customize Vim.
+
+Before reading this book you should be comfortable using Vim and know what terms like
+"buffer", "window" and "insert mode" mean.
+
+The source code to the book is available [on BitBucket][hg] and [on GitHub][git]
+under an [MIT/X11 license][license].  If you find any mistakes or feel you could
+improve it feel free to send a pull request.
+
+[book]: /
+[hg]: http://bitbucket.org/sjl/learnvimscriptthehardway/
+[git]: http://github.com/sjl/learnvimscriptthehardway/
+[license]: /license.html
diff -r c05078bf9c7f -r c608cbb9aaaa license.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/license.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,1 @@
+license *here*
diff -r c05078bf9c7f -r c608cbb9aaaa preface.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/preface.markdown	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,49 @@
+Preface
+=======
+
+Programmers shape ideas into text.
+
+That text gets turned into numbers and those numbers bump into other numbers
+and *make things happen*.
+
+To get our ideas out of our heads and the chunks of text we call "programs" we
+use text editors.  Full-time programmers will easily spend thousands of hours
+of their lives interacting with their text editor doing many things:
+
+* Getting raw text from brains into computers.
+* Correcting mistakes in that text.
+* Restructuring the text to formulate a problem in a different way.
+* Recording how and why something was done a particular way.
+* Communicating with other programmers about all of these things.
+
+Vim is incredibly powerful out of the box, but it doesn't truly shine until you
+take some time to customize it for your particular work, habits, and fingers.
+This book will introduce you to Vimscript, the main programming language used to
+customize Vim.  You'll be able to mold Vim around your own personal text editing
+and make the rest of your time in Vim more efficient.
+
+Along the way I'll also mention things that aren't strictly about Vimscript, but
+are more about learning and being more efficient in general.  Learning Vimscript
+isn't going to help you much if you wind up fiddling with your editor all day
+instead of working, so you must strike a balance.
+
+Each chapter of the book focuses on a single topic.  They're short but packed
+with information, so don't just skim them.  If you really want to learn the most
+you can from this book, you need to *type in* all of the commands.
+
+You may already be an experienced programmer who's used to reading code and
+understanding it straight away.  If so: it doesn't matter.  Learning Vim and
+Vimscript is a different experience from learning a normal programming language.
+
+**Type.  In.  The.  Exercises.**
+
+First, Vimscript is old and has a lot of dusty corners and twisty hallways.  One
+configuration option can change how the entire language works.  By typing
+*every* command in *every* exercise you'll discover problems with your Vim build
+or configuration on the simpler commands, which will be easier to diagnose and
+fix.
+
+Second, Vimscript *is* Vim.  To save a file in Vim, you type `:write` (or `:w`
+for short) and press return.  To save a file in a Vimscript, you use `write`.
+Mastering a text editor means developing muscle memory, which you simply can't
+get from just reading.
diff -r c05078bf9c7f -r c608cbb9aaaa publish.sh
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/publish.sh	Fri Oct 07 19:25:30 2011 -0400
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -e
+../../bookmarkdown/bookmarkdown/bookmarkdown build
+rsync --delete -az build/html/ sl:/var/www/vimscript/