Update excerpt documentation and examples

Shows how to pass a function to the excerpt option parameter in the
.verb README and in the examples folder.

.verb.md

@@ -168,26 +168,66 @@ $ node examples/<example_name>
 
 ### options.excerpt
 
-**Type**: `Object`
+**Type**: `Boolean|Function`
 
 **Default**: `undefined`
 
 Extract an excerpt that directly follows front-matter, or is the first thing in the string if no front-matter exists.
 
+If set to `excerpt: true`, it will look for the frontmatter delimiter, `---` by default and grab everything leading up to it.
+
+**Example**
+
+```js
+var file = matter([
+  '---',
+  'foo: bar',
+  '---',
+  'This is an excerpt.',
+  '---',
+  'This is content'
+].join('\n'), {excerpt: true});
+```
+
+Results in:
+
+```js
+{ 
+	content: 'This is an excerpt.\n---\nThis is content',
+	data: { foo: 'bar' },
+	excerpt: 'This is an excerpt.\n' 
+}
+```
+
+You can also set `excerpt` to a function. This function uses the 'file' and 'options' that were initially passed to gray-matter as parameters, so you can control how the excerpt is extracted from the content.
+
 **Example**
 
 ```js
-var str = '--\ntitle: Home\n---\nAn excerpt\n---\nOther stuff';
-console.log(matter(str, {excerpt: true}));
+// returns the first 4 lines of the contents
+function firstFourLines(file, options) {
+    file.excerpt = file.content.split('\n').slice(0, 4).join(' ');
+}
+
+var file =  matter([
+  '---',
+  'foo: bar',
+  '---',
+  'Only this',
+  'will be',
+  'in the',
+  'excerpt',
+  'but not this...'
+].join('\n'), {excerpt: firstFourLines});
 ```
 
 Results in:
 
 ```js
 { 
-  data: { title: 'Home'}, 
-  excerpt: '\nAn excerpt', 
-  content: '\nAn excerpt\n---\nOther stuff' 
+	content: 'Only this\nwill be\nin the\nexcerpt\nbut not this...',
+	data: { foo: 'bar' },
+	excerpt: 'Only this will be in the excerpt'
 }
 ```
 

examples/excerpt.js

@@ -3,7 +3,8 @@ var matter = require('..');
 var fixture = path.join.bind(path, __dirname, 'fixtures');
 var magenta = require('ansi-magenta');
 
-var file = matter([
+// excerpt as a boolean
+var file1 = matter([
   '---',
   'foo: bar',
   '---',
@@ -12,5 +13,26 @@ var file = matter([
   'This is content'
 ].join('\n'), {excerpt: true});
 
-console.log(magenta('/* excerpt */'));
-console.log(file);
+console.log(magenta('/* excerpt: true */'));
+console.log(file1);
+
+// excerpt as a function
+
+// returns the first 4 lines of the contents
+function firstFourLines(file, options) {
+  file.excerpt = file.content.split('\n').slice(0, 4).join(' ');
+}
+
+var file2 =  matter([
+'---',
+'foo: bar',
+'---',
+'Only this',
+'will be',
+'in the',
+'excerpt',
+'but not this...'
+].join('\n'), {excerpt: firstFourLines });
+
+console.log(magenta('/* excerpt: function(file, options) { ... } */'));
+console.log(file2);