# HG changeset patch # User Steve Losh # Date 1321225262 18000 # Node ID f78c198a9fd8fd921a87d4a16067c44fe32fc5d5 # Parent 58b4bcf3112fe06f54bf130a5b94a2e840bd6752# Parent ca0dbc1378a97fe06281450f9170ae12a3190f8e Merge. diff -r ca0dbc1378a9 -r f78c198a9fd8 chapters/16.markdown --- a/chapters/16.markdown Sun Nov 06 03:40:30 2011 +0100 +++ b/chapters/16.markdown Sun Nov 13 18:01:02 2011 -0500 @@ -162,7 +162,7 @@ What's different about this mapping? Let's look at them side by side: :onoremap ih :execute "normal! ?^==\\+$\r:nohlsearch\rkvg_" - :onoremap ah :execute "normal! ?^==\\+\r:nohlsearch\rg_vk0" + :onoremap ah :execute "normal! ?^==\\+$\r:nohlsearch\rg_vk0" The only difference from the previous mapping is the very end, where we select the text to operate on: diff -r ca0dbc1378a9 -r f78c198a9fd8 chapters/41.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/chapters/41.markdown Sun Nov 13 18:01:02 2011 -0500 @@ -0,0 +1,59 @@ +Creating a Full Plugin +====================== + +We've covered a lot of ground in the last forty or so chapters. In the final +part of the book we're going to walk through creating a Vim plugin for +a language from scratch. + +This is not for the faint of heart. It's going to take a lot of effort. + +If you want to stop now, that's completely fine! You've already learned enough +to make serious enhancements to your own `~/.vimrc` file and to fix bugs you +find in other people's plugins. + +There's no shame in saying "that's enough for me -- I don't want to spend hours +of my life creating plugins I won't use very often". Be practical. If you +can't think of a full plugin you want to make, stop now and come back when you +do. + +If you *do* want to continue make sure you're ready to devote some time. The +rest of the book is going to be intense, and I'm going to assume you actually +want to *learn*, not just coast through the chapters reading them on your couch. + +Potion +------ + +The plugin we're going to make is going to add support for the [Potion][] +programming language. + +Potion is a toy language created by \_why the lucky stiff before his +disappearance. It's an extremely small language which makes it ideal for our +purposes. + +Potion feels a lot like [Io][], with some ideas from Ruby, Lua and other +languages mixed in. If you've never tried Io it may seem weird. I strongly +recommend playing with Potion for at least an hour or two. You won't use it in +real life, but it might change the way you think and expose you to new ideas. + +The current implementation of Potion has a lot of rough edges. For example: if +you mess up the syntax it usually segfaults. Try not to get too hung up on this +-- I'll provide you with lots of sample code that works so you can focus mostly +on the Vimscript and not Potion. + +The goal is not to learn Potion (though I think doing so *will* make you +a better programmer). The goal is to use Potion as a small example so we can +touch on a lot of different aspects of writing Vim plugins. + +Exercises +--------- + +Download and install [Potion][]. You're on your own for this one. It should be +fairly simple. + +Make sure you can get the first couple examples in the pamphlet working in the +Potion interpreter and by putting them in a `.pn` file. If it seems like the +interpreter isn't working check out [this +issue](https://github.com/fogus/potion/issues/12) for a possible cause. + +[Potion]: http://fogus.github.com/potion/index.html +[Io]: http://iolanguage.com/ diff -r ca0dbc1378a9 -r f78c198a9fd8 chapters/42.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/chapters/42.markdown Sun Nov 13 18:01:02 2011 -0500 @@ -0,0 +1,129 @@ +Plugin Layout in the Dark Ages +============================== + +The first thing we need to talk about is how to structure our plugin. In the +past this was a messy affair, but now there's a tool that makes the process of +installing Vim plugins much, *much* saner. + +We need to go over the basic layout first, then we'll talk about how to restore +our sanity. + +Basic Layout +------------ + +Vanilla Vim supports splitting plugins into multiple files. There are a number +of different directories you can create under `~/.vim` that mean various things. + +We'll cover the most important directories now, but don't stress out too much +about them. We'll go over them one at a time as we create our Potion plugin. + +Before we continue we need to talk about some vocabulary. + +I've been using the word "plugin" to mean "a big ol' hunk of Vimscript that does +a bunch of related stuff". Vim has a more specific meaning of "plugin", which +is "a file in `~/.vim/plugins/`". + +Most of the time I'll be using the first definition, but if something is unclear +please [let me know](http://twitter.com/stevelosh/) and I'll try to reword it. + +~/.vim/colors/ +-------------- + +Files inside `~/.vim/colors/` are treated as color schemes. For example: if you +run `:color mycolors` Vim will look for a file at `~/.vim/colors/mycolors.vim` +and run it. That file should contain all the Vimscript commands necessary to +generate your color scheme. + +We're not going to cover color schemes in this book. If you want to create your +own you should copy an existing scheme and modify it. Remember that `:help` is +your friend. + +~/.vim/plugin/ +-------------- + +Files inside `~/.vim/plugin/` will each be run once *every time* Vim starts. +These files are meant to contain code that you always want loaded whenever you +start Vim. + +~/.vim/ftdetect/ +---------------- + +Any files in `~/.vim/ftdetect/` will *also* be run every time you start Vim. + +"ftdetect" stands for "filetype detection". The files in this directory should +set up autocommands that detect and set the `filetype` of files, and *nothing +else*. This means they should never be more than one or two lines long. + +~/.vim/ftplugin/ +---------------- + +Files in `~/.vim/ftplugin/` are different. + +The naming of these files matters. When Vim sets a buffer's `filetype` to +a value it then looks for a file in `~/.vim/ftplugin/` that matches. For +example: if you run `set filetype=derp` Vim will look for +`~/.vim/ftplugin/derp.vim`. If that file exists, it will run it. + +Vim also supports directories inside `~/.vim/ftplugin/`. To continue our +example: `set filetype=derp` will also make Vim run any and all `*.vim` files +inside `~/.vim/ftplugin/derp/`. This lets you split up your plugin's `ftplugin` +files into logical groups. + +Because these files are run every time a buffer's `filetype` is set they *must* +only set buffer-local options! If they set options globally they would +overwrite them for all open buffers! + +~/.vim/indent/ +-------------- + +Files in `~/.vim/indent/` are a lot like `ftplugin` files -- they get loaded +based on their names. + +`indent` files should set options related to indentation for their filetypes, +and those options should be buffer-local. + +Yes, you could simply put this code in the `ftplugin` files, but it's better to +separate it out so other Vim users will understand what you're doing. It's just +a convention, but please be a considerate plugin author and follow it. + +~/.vim/compiler/ +---------------- + +Files in `~/.vim/compiler/` work exactly like `indent` files. They should set +compiler-related options in the current buffer based on their names. + +Don't worry about what "compiler-related options" means right now. We'll cover +that later. + +~/.vim/after/ +------------- + +The `~/.vim/after/` directory is a bit of a hack. Files in this directory will +be loaded every time Vim starts, but *after* the files in `~/.vim/plugin/`. + +This allows you to override Vim's internal files. In practice you'll rarely +need this, so don't worry about it until you find yourself thinking "Vim sets +option X and I want something different". + +~/.vim/autoload/ +---------------- + +The `~/.vim/autoload/` directory is an incredibly important hack. It sounds +a lot more complicated than it actually is. + +In a nutshell: `autoload` is a way to delay the loading of your plugin's code +until it's actually needed. We'll cover this in more detail later when we +refactor our plugin's code to take advantage of it. + +~/.vim/doc/ +----------- + +Finally, the `~/.vim/doc/` directory is where you can add documentation for your +plugin. Vim has a huge focus on documentation (as evidenced by all the `:help` +commands we've been running) so it's important to document your plugins. + +Exercises +--------- + +Reread this chapter. I'm not kidding. Make sure you understand (in a very +rough way) what each directory we've talked about does. diff -r ca0dbc1378a9 -r f78c198a9fd8 outline.org --- a/outline.org Sun Nov 06 03:40:30 2011 +0100 +++ b/outline.org Sun Nov 13 18:01:02 2011 -0500 @@ -43,7 +43,8 @@ ** TODO functions again ** TODO command! * part 3 - creating a full plugin -** TODO intro and plugin layout +** TODO intro +** TODO plugin layout ** TODO pathogen ** TODO autoload ** TODO folding