# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1323991901 18000
# Node ID b0e538f6533dbd53efd3063a14a1b5fc00ea69a6
# Parent  e66e6a4e104d3e57814263813114995e61609958
Folding.

diff -r e66e6a4e104d -r b0e538f6533d chapters/48.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/chapters/48.markdown	Thu Dec 15 18:31:41 2011 -0500
@@ -0,0 +1,126 @@
+Basic Folding
+=============
+
+If you've never used code folding in Vim, you don't know what you're missing.
+Read `:help usr_28` and spend some time playing around with it in your normal
+work.  Come back to this chapter once you've got it in your fingers.
+
+Types of Folding
+----------------
+
+Vim supports six different ways of defining how your text should be folded.
+
+### Manual
+
+You create the folds by hand and they're stored in RAM by Vim.  When you close
+Vim they go away and you have to recreate them the next time you edit the file.
+
+This method can be handy if you combine it with some custom mappings to make it
+easy to create folds.  We won't do that in this book, but keep it in the back
+of your mind in case you run across a case where it could be handy.
+
+### Marker
+
+Vim folds your code based on characters in the actual text.
+
+Usually these characters are put in comments (like `// {{{`), but in some
+languages you can get away with using something in the language's syntax itself,
+like `{` and `}` in Javascript files.
+
+It may seem ugly to clutter up your code with comments that are purely for your
+text editor, but the advantage is that it lets you hand-craft folds for
+a specific file.  This can be really nice if you're working with a large file
+that you want to organize in a very specific way.
+
+### Diff
+
+A special folding mode used when diff'ing files.  We won't talk about this one
+at all because Vim automatically handles it.
+
+### Expr
+
+This lets you use a custom piece of Vimscript to define where folds occur.  It's
+the most powerful method, but also requires the most work.  We'll talk about
+this in the next chapter.
+
+### Indent
+
+Vim uses your code's indentation to determine folds.  Lines at the same
+indentation level fold together, and lines with only whitespace (and blank
+lines) are simply folded with their neighbors.
+
+This is essentially free to use because your code is already indented; all you
+have to do is turn it on.  This will be our first method of adding folding to
+Potion files.
+
+Potion Folding
+--------------
+
+Let's take a look at our sample Potion file once again:
+
+    :::text
+    factorial = (n):
+        total = 1
+        n to 1 (i):
+            total *= i.
+        total.
+
+    10 times (i):
+        i string print
+        '! is: ' print
+        factorial (i) string print
+        "\n" print.
+
+The bodies of the function and loop are both indented.  This means we can get
+some basic folding with very little effort by using indent folding.
+
+Create an `ftplugin` folder in your Potion plugin's repository, and create
+a `potion.vim` file inside of it.
+
+Remember that Vim will run the code in this file whenever it sets a buffer's
+`filetype` to `potion` (because it's named `potion.vim`).
+
+Add the following line to this file:
+
+    :::vim
+    setlocal foldmethod=indent
+
+Close Vim and open the `factorial.pn` file again.  It may or may not be folded
+immediately, but go ahead and try folding and unfolding the indented blocks.
+
+One line of Vimscript gave us some useful folding!  That's pretty cool!
+
+Let's add one more line to the `ftplugin/potion.vim` file to make Vim
+automatically fold everything whenever we open a Potion file:
+
+    :::vim
+    setlocal foldlevel=0
+
+Close and reopen your example file and now the folds will all be closed (if they
+weren't already).
+
+Exercises
+---------
+
+Read `:help foldmethod`.
+
+Read `:help fold-manual`.
+
+Read `:help fold-marker` and `:help foldmarker`.
+
+Read `:help fold-indent`.
+
+Read `:help fdl` and `:help foldlevelstart`.
+
+Read `:help foldminlines`.
+
+Add a line to `ftplugin/potion.vim` that uses `foldminlines` to allow
+single-line blocks to be "folded", for consistency.  Make sure it works on the
+`total *= i.` line of the example file.
+
+Some people might not want to automatically fold everything when they open
+a Potion file.  We want our plugin to be useful to everyone, so remove the
+`foldlevel` line from `ftplugin/potion.vim`.
+
+Add a `Filetype` autocommand to your `~/.vimrc` file that sets `foldlevel` to
+0 to replace the line we removed from the plugin.
diff -r e66e6a4e104d -r b0e538f6533d outline.org
--- a/outline.org	Wed Dec 07 20:16:52 2011 -0500
+++ b/outline.org	Thu Dec 15 18:31:41 2011 -0500
@@ -47,9 +47,9 @@
 ** DONE plugin layout
 ** DONE pathogen
 ** DONE ftdetect
-** TODO syntax
+** DONE syntax
+** TODO folding
 ** TODO autoload
-** TODO folding
 ** TODO compilers
 *** makeprg
 *** errorformat