In the next part of the book we're going to dive into Vimscript as a real
programming language, but before we do that I want to talk a bit about how to
-stay sane while writing large
r chun ks of Vimscript.
+stay sane while writing largeuns of Vimscript.
Vimscript is extremely powerful, but has grown organically over the years into
-a twisty maze ready to ensnare the unwary who enter it.
+a twisty maze ready to ensnare the unwary who enter it.
Options and commands are often terse and hard to read, and working around
compatibility issues can increase the complexity of your code. Writing a plugin
Be defensive when writing anything that takes more than a few lines of
Vimscript. Add a comment explaining what it does, and if there is a relevant
+help topic mention it!
This not only benefits you when you try to maintain it months or years later,
but also helps other people understand it if you share your `~/.vimrc` file on
-GitHub (which I highly recommend).
+GitHub (which I highly recommend).
to grow out of control and become hard to navigate.
One way to combat this is to use Vim's code folding capabilities and group lines
-into sections. If you've never used Vim's folding before check out this great
+into sections. If you've never used Vim's folding you should look into it as
+soon as you can. Some people (myself included) find it indispensable in our day
First we need to set up folding for Vimscript files. Add the following lines to
This will tell Vim to use the `marker` method of folding for any Vimscript
-files. Go ahead and run `:setlocal foldmethod=marker` the window with your
+Go ahead and run `:setlocal foldmethod=marker` in the window with your
`~/.vimrc` now. Sourcing the file won't work, because Vim has already set the
FileType for this file and the autocommand only fires when that happens. In the
future you won't need to do it manually.
code with folding comments is just noisy to anyone else looking at the code in
something other than Vim.
-Vimscript files a special case, though. It's highly unlikely that someone who
+Vimscript files a special case, though. It's highly unlikely that someone who
doesn't use Vim will be reading your code, and it's especially important to
-group things explicitly and thoughtfully when writing Vimscript.
+group things explicitly and thoughtfully when writing Vimscript so you don't go
it out for a while and there's a good chance the idea will grow on you.
I'd like to *strongly* caution you against using these abbreviations in your
`~/.vimrc` file and in plugins that you write. Vimscript is terse and cryptic
-enough to begin with
-- shortening things further is only going to make it even
+enough to begin with shortening things further is only going to make it even
harder to read. Even if *you* know what a certain short command means, someone
else reading your code might not.
information inside. Create a git or Mercurial repository, move the file into
it, and symlink that file to `~/.vimrc`.
-Commit the repository you just made and put it on Bit
Bucket or GitHub so other
+Commit the repository you just made and put it on Bitucket or GitHub so other
people can see it and get ideas for their own. Be sure to commit and push the
repository fairly often so your changes are recorded.