* proof-reading the documentation

* added link to the new screencast
2025-10-13 13:13:03 +00:00 · 2009-09-24 15:59:45 +00:00 · 2009-09-24 15:59:45 +00:00 · 037f8fd3ee
commit 037f8fd3ee
parent 5d0b9657e3
12 changed files with 361 additions and 333 deletions
--- a/doc/changelog.html
+++ b/doc/changelog.html
@ -54,8 +54,8 @@
              for other versions can be found <a title=""
              href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
            </p>
-            <div class="section" id="upcoming-0-6-1c">
-<h1>Upcoming 0.6.1c</h1>
+            <div class="section" id="c-2009-08-13">
+<h1>0.6.1c / 2009-08-13</h1>
 <ul class="simple">
 <li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues">issues</a> 99, 98, 93,
 90, 91, 88, 87. Thanks everybody.</li>
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@ -7,8 +7,8 @@ ChangeLog
 .. _Writing Snippets: snippet-development.html
 .. _The YASnippet Menu: snippet-menu.html

-Upcoming 0.6.1c
-===============
+0.6.1c / 2009-08-13
+===================

 * Fixed `issues <http://code.google.com/p/yasnippet/issues>`_ 99, 98, 93,
  90, 91, 88, 87. Thanks everybody.
--- a/doc/index.html
+++ b/doc/index.html
@ -59,7 +59,7 @@
 <ul class="simple">
 <li><a class="reference internal" href="#video-demo" id="id1">Video Demo</a></li>
 <li><a class="reference internal" href="#installation" id="id2">Installation</a><ul>
-<li><a class="reference internal" href="#bundle-install" id="id3">Bundle Install</a></li>
+<li><a class="reference internal" href="#install-with-yasnippet-bundle-el" id="id3">Install with <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt></a></li>
 <li><a class="reference internal" href="#normal-install" id="id4">Normal Install</a></li>
 </ul>
 </li>
@ -67,16 +67,14 @@
 <li><a class="reference internal" href="#bugs-contribution-and-support" id="id6">Bugs, Contribution and Support</a></li>
 </ul>
 </div>
-<p><strong>YASnippet</strong> is a template system for Emacs. It allows you to type a
-abbreviation and automatically expand the abbreviation into function
-templates.</p>
-<p>Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
-SQL, LaTeX, HTML, CSS and more.</p>
-<p>The snippet syntax is inspired from TextMate's syntax, you can
-even <a class="reference external" href="snippet-development.html#importing-textmate-snippets">import</a>
-import most TextMate templates to YASnippet.</p>
-<p>YASnippet is a re-write of the extension <a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. Both are
-original creations of <a class="reference external" href="http://pluskid.lifegoo.org">pluskid</a>.</p>
+<p><strong>YASnippet</strong> is a template system for Emacs. It allows you to type an
+abbreviation and automatically expand it into function
+templates. Bundled language templates includes: C, C++, C#, Perl,
+Python, Ruby, SQL, LaTeX, HTML, CSS and more.</p>
+<p>The snippet syntax is inspired from TextMate's syntax, you can even
+<a class="reference external" href="snippet-development.html#importing-textmate-snippets">import</a>
+import most TextMate templates. YASnippet is a re-write of the
+extension <a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. Both are original creations of <a class="reference external" href="http://pluskid.lifegoo.org">pluskid</a>.</p>
 <div class="section" id="video-demo">
 <h1><a class="toc-backref" href="#id1">Video Demo</a></h1>
 <object type="application/x-shockwave-flash"
@ -84,21 +82,21 @@ original creations of <a class="reference external" href="http://pluskid.lifegoo
        height="344"
        align="right"
        class="youtube-embed"
-        data="http://www.youtube.com/v/vOj7btx3ATg">
-    <param name="movie" value="http://www.youtube.com/v/vOj7btx3ATg"></param>
+        data="http://www.youtube.com/v/76Ygeg9miao">
+    <param name="movie" value="http://www.youtube.com/v/76Ygeg9miao"></param>
    <param name="wmode" value="transparent"></param>
 </object>
-<p>Watch the <a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">demo at YouTube</a> (download a higher
+<p>Watch the <a class="reference external" href="http://www.youtube.com/watch?v=76Ygeg9miao">demo at YouTube</a> (download a higher
 resolution version: <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">yasnippet.avi</a>).</p>
 </div>
 <div class="section" id="installation">
 <h1><a class="toc-backref" href="#id2">Installation</a></h1>
-<p>There are two archives of YASnippet. One is a single file compiled
-“bundle”, and the other is normal. If all you need is to use the
-built-in templates, download the bundle one. If you want to add your
-own templates, download the normal one.</p>
-<div class="section" id="bundle-install">
-<h2><a class="toc-backref" href="#id3">Bundle Install</a></h2>
+<p>There are two archives you can download. To quickly tryout YASnippet,
+download the simpler &quot;bundle&quot; version. If you plan to modify the
+bundled templates and/or build your own, download the &quot;normal&quot;
+package.</p>
+<div class="section" id="install-with-yasnippet-bundle-el">
+<h2><a class="toc-backref" href="#id3">Install with <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt></a></h2>
 <ol class="arabic simple">
 <li>Download the latest <tt class="docutils literal"><span class="pre">yasnippet-bundle-x.y.z.el.tgz</span></tt> and unpack it.</li>
 <li>You'll get a file named <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt>, put it under
@ -107,7 +105,7 @@ own templates, download the normal one.</p>
 </ol>
 <p>That's it. Now open any one of your language file, you'll see a menu
 YASnippet. you can pull the menu to insert a template. Or, you can
-type the pre-defined abbrev and press <tt class="docutils literal"><span class="pre">TAB</span></tt> to expand it.</p>
+type the a <em>trigger key</em> then press <tt class="docutils literal"><span class="pre">TAB</span></tt> to expand it.</p>
 <p>To have Emacs load YASnippet automatically when it starts, put the
 following in your <tt class="docutils literal"><span class="pre">~/.emacs</span></tt> file:</p>
 <blockquote>
@ -116,13 +114,15 @@ following in your <tt class="docutils literal"><span class="pre">~/.emacs</span>
 (<span style="color: #008000">require</span> <span style="color: #19177C">&#39;yasnippet-bundle</span>)
 </pre></div>
 </blockquote>
+<p>The <a class="reference external" href="http://www.youtube.com/watch?v=76Ygeg9miao">youtube video</a>
+demonstrates this quick installation.</p>
 </div>
 <div class="section" id="normal-install">
 <h2><a class="toc-backref" href="#id4">Normal Install</a></h2>
-<p>For full install of the normal archive, just download and unpack the
-latest <tt class="docutils literal"><span class="pre">yasnippet-x.y.z.tar.bz2</span></tt>. You'll get a directory named
-<tt class="docutils literal"><span class="pre">yasnippet-x.y.z</span></tt>, put it in your <tt class="docutils literal"><span class="pre">~/.emacs.d/plugins</span></tt> and add the
-following in your <tt class="docutils literal"><span class="pre">.emacs</span></tt> file:</p>
+<p>To install YASnippet as a normal emacs package, download and unpack
+the latest <tt class="docutils literal"><span class="pre">yasnippet-x.y.z.tar.bz2</span></tt>. You'll get a directory named
+<tt class="docutils literal"><span class="pre">yasnippet-x.y.z</span></tt>, which you can put it in your
+<tt class="docutils literal"><span class="pre">~/.emacs.d/plugins</span></tt> and add the following in your <tt class="docutils literal"><span class="pre">.emacs</span></tt> file:</p>
 <blockquote>
 <div class="highlight"><pre>(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">&#39;load-path</span>
              <span style="color: #BA2121">&quot;~/.emacs.d/plugins/yasnippet-x.y.z&quot;</span>)
@ -167,7 +167,7 @@ TextMate snippets.</blockquote>
 <li><a class="reference external" href="snippet-menu.html">The YASnippet menu</a></li>
 </ol>
 <blockquote>
-Explains how to use the YASnippet menu to explore and learn new
+Explains how to use the YASnippet menu to explore, learn and modify
 snippets.</blockquote>
 </div>
 <div class="section" id="bugs-contribution-and-support">
--- a/doc/index.rst
+++ b/doc/index.rst
@ -9,43 +9,40 @@ Yet Another Snippet extension

 .. contents::

-**YASnippet** is a template system for Emacs. It allows you to type a
-abbreviation and automatically expand the abbreviation into function
-templates.
+**YASnippet** is a template system for Emacs. It allows you to type an
+abbreviation and automatically expand it into function
+templates. Bundled language templates includes: C, C++, C#, Perl,
+Python, Ruby, SQL, LaTeX, HTML, CSS and more.

-Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
-SQL, LaTeX, HTML, CSS and more.
-
-The snippet syntax is inspired from TextMate's syntax, you can
-even `import <snippet-development.html#importing-textmate-snippets>`_
-import most TextMate templates to YASnippet.
-
-YASnippet is a re-write of the extension `smart-snippet`_. Both are
-original creations of `pluskid <http://pluskid.lifegoo.org>`_.
+The snippet syntax is inspired from TextMate's syntax, you can even
+`import <snippet-development.html#importing-textmate-snippets>`_
+import most TextMate templates. YASnippet is a re-write of the
+extension `smart-snippet`_. Both are original creations of `pluskid
+<http://pluskid.lifegoo.org>`_.

 .. _smart-snippet: http://code.google.com/p/smart-snippet/

 Video Demo
 ==========

-.. youtube:: vOj7btx3ATg
+.. youtube:: 76Ygeg9miao
   :align: right

 Watch the `demo at YouTube
-<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ (download a higher
+<http://www.youtube.com/watch?v=76Ygeg9miao>`_ (download a higher
 resolution version: `yasnippet.avi
 <http://yasnippet.googlecode.com/files/yasnippet.avi>`_).

 Installation
 ============

-There are two archives of YASnippet. One is a single file compiled
-“bundle”, and the other is normal. If all you need is to use the
-built-in templates, download the bundle one. If you want to add your
-own templates, download the normal one.
+There are two archives you can download. To quickly tryout YASnippet,
+download the simpler "bundle" version. If you plan to modify the
+bundled templates and/or build your own, download the "normal"
+package.

-Bundle Install
--------------
+Install with ``yasnippet-bundle.el``
+------------------------------------

 1. Download the latest ``yasnippet-bundle-x.y.z.el.tgz`` and unpack it.
 2. You'll get a file named ``yasnippet-bundle.el``, put it under
@ -54,7 +51,7 @@ Bundle Install

 That's it. Now open any one of your language file, you'll see a menu
 YASnippet. you can pull the menu to insert a template. Or, you can
-type the pre-defined abbrev and press ``TAB`` to expand it.
+type the a *trigger key* then press ``TAB`` to expand it.

 To have Emacs load YASnippet automatically when it starts, put the
 following in your ``~/.emacs`` file:
@ -65,13 +62,16 @@ following in your ``~/.emacs`` file:
                   "~/.emacs.d/plugins")
     (require 'yasnippet-bundle)

+The `youtube video <http://www.youtube.com/watch?v=76Ygeg9miao>`_
+demonstrates this quick installation.
+
 Normal Install
 --------------

-For full install of the normal archive, just download and unpack the
-latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named
-``yasnippet-x.y.z``, put it in your ``~/.emacs.d/plugins`` and add the
-following in your ``.emacs`` file:
+To install YASnippet as a normal emacs package, download and unpack
+the latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named
+``yasnippet-x.y.z``, which you can put it in your
+``~/.emacs.d/plugins`` and add the following in your ``.emacs`` file:

   .. sourcecode:: common-lisp

@ -114,7 +114,7 @@ Hence this section has been split into separate documents:

 4. `The YASnippet menu`_

-  Explains how to use the YASnippet menu to explore and learn new
+  Explains how to use the YASnippet menu to explore, learn and modify
  snippets.

 Bugs, Contribution and Support
--- a/doc/snippet-development.html
+++ b/doc/snippet-development.html
@ -66,46 +66,45 @@
 <li><a class="reference internal" href="#key-snippet-abbrev" id="id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></li>
 <li><a class="reference internal" href="#name-snippet-name" id="id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></li>
 <li><a class="reference internal" href="#condition-snippet-condition" id="id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></li>
-<li><a class="reference internal" href="#expand-env-expand-environment" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li>
-<li><a class="reference internal" href="#binding-direct-keybinding" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></li>
-<li><a class="reference internal" href="#contributor-snippet-author" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></li>
+<li><a class="reference internal" href="#group-snippet-menu-grouping" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></li>
+<li><a class="reference internal" href="#expand-env-expand-environment" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li>
+<li><a class="reference internal" href="#binding-direct-keybinding" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></li>
+<li><a class="reference internal" href="#contributor-snippet-author" id="id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#template-syntax" id="id13">Template syntax</a><ul>
-<li><a class="reference internal" href="#plain-text" id="id14">Plain Text</a></li>
-<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id15">Embedded Emacs-lisp code</a></li>
-<li><a class="reference internal" href="#tab-stop-fields" id="id16">Tab stop fields</a></li>
-<li><a class="reference internal" href="#placeholder-fields" id="id17">Placeholder fields</a></li>
-<li><a class="reference internal" href="#id2" id="id18">Mirrors</a></li>
-<li><a class="reference internal" href="#mirrors-with-transformations" id="id19">Mirrors with transformations</a></li>
-<li><a class="reference internal" href="#fields-with-transformations" id="id20">Fields with transformations</a></li>
-<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id21">Choosing fields value from a list</a></li>
-<li><a class="reference internal" href="#nested-placeholder-fields" id="id22">Nested placeholder fields</a></li>
+<li><a class="reference internal" href="#template-syntax" id="id14">Template syntax</a><ul>
+<li><a class="reference internal" href="#plain-text" id="id15">Plain Text</a></li>
+<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id16">Embedded Emacs-lisp code</a></li>
+<li><a class="reference internal" href="#tab-stop-fields" id="id17">Tab stop fields</a></li>
+<li><a class="reference internal" href="#placeholder-fields" id="id18">Placeholder fields</a></li>
+<li><a class="reference internal" href="#id2" id="id19">Mirrors</a></li>
+<li><a class="reference internal" href="#mirrors-with-transformations" id="id20">Mirrors with transformations</a></li>
+<li><a class="reference internal" href="#fields-with-transformations" id="id21">Fields with transformations</a></li>
+<li><a class="reference internal" href="#choosing-fields-value-from-a-list-and-other-tricks" id="id22">Choosing fields value from a list and other tricks</a></li>
+<li><a class="reference internal" href="#nested-placeholder-fields" id="id23">Nested placeholder fields</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#customizable-variables" id="id23">Customizable variables</a><ul>
-<li><a class="reference internal" href="#yas-trigger-key" id="id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li>
-<li><a class="reference internal" href="#yas-next-field-key" id="id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li>
-<li><a class="reference internal" href="#yas-prev-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li>
-<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li>
-<li><a class="reference internal" href="#yas-good-grace" id="id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
-<li><a class="reference internal" href="#yas-indent-line" id="id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li>
-<li><a class="reference internal" href="#yas-wrap-around-region" id="id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li>
-<li><a class="reference internal" href="#yas-triggers-in-field" id="id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li>
-<li><a class="reference internal" href="#yas-snippet-revival" id="id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li>
-<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li>
+<li><a class="reference internal" href="#customizable-variables" id="id24">Customizable variables</a><ul>
+<li><a class="reference internal" href="#yas-trigger-key" id="id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li>
+<li><a class="reference internal" href="#yas-next-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li>
+<li><a class="reference internal" href="#yas-prev-field-key" id="id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li>
+<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li>
+<li><a class="reference internal" href="#yas-good-grace" id="id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
+<li><a class="reference internal" href="#yas-indent-line" id="id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li>
+<li><a class="reference internal" href="#yas-wrap-around-region" id="id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li>
+<li><a class="reference internal" href="#yas-triggers-in-field" id="id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li>
+<li><a class="reference internal" href="#yas-snippet-revival" id="id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li>
+<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#importing-textmate-snippets" id="id34">Importing TextMate snippets</a></li>
+<li><a class="reference internal" href="#importing-textmate-snippets" id="id35">Importing TextMate snippets</a></li>
 </ul>
 </div>
 <div class="section" id="snippet-development">
 <h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
 <div class="section" id="quickly-finding-snippets">
 <h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2>
-<p>There are some ways you can quickly find a snippet file. Once you find
-this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead) and you can
-start editing your snippet.</p>
+<p>There are some ways you can quickly find a snippet file:</p>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt></p>
 <p>Prompts you for a snippet name, then tries to guess a suitable
@ -115,7 +114,8 @@ so you can write your snippet.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p>
 <p>Lets you find the snippet file in the directory the snippet was
-loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>.</p>
+loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>. The
+directory searching logic is similar to <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt>.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p>
 <p>Prompts you for possible snippet expansions like
@ -123,6 +123,8 @@ loaded from (if it exists) like <tt class="docutils literal"><span class="pre">f
 directly to the snippet definition's file, if it exists.</p>
 </li>
 </ul>
+<p>Once you find this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead)
+and you can start editing your snippet.</p>
 </div>
 <div class="section" id="using-the-snippet-mode-major-mode">
 <h2><a class="toc-backref" href="#id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h2>
@ -147,31 +149,26 @@ can see what it looks like. This is bound to <tt class="docutils literal"><span
 </blockquote>
 </li>
 </ul>
-<p>There are also snippets for making snippets: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">field</span></tt> and
-<tt class="docutils literal"><span class="pre">mirror</span></tt>.</p>
+<p>There are also <em>snippets for writing snippets</em>: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">$f</span></tt> and
+<tt class="docutils literal"><span class="pre">$m</span></tt> :-).</p>
 </div>
 </div>
 <div class="section" id="file-content">
 <h1><a class="toc-backref" href="#id6">File content</a></h1>
-<p>A file defining a snippet may just contain the template for the
-snippet. Optionally it can also contains some meta data for the
-snippet as well as comments.</p>
-<p>Generally speaking, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, then all
-contents above that line are considered directives (meta data) and
-comments; below that line lies the snippet template.</p>
-<p>If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found, the whole file content is considered as the
-template.</p>
+<p>A file defining a snippet generally contains the template to be
+expanded.</p>
+<p>Optionally, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, the lines above
+it count as comments, some of which can be <em>directives</em> (or meta
+data). Snippet directives look like <tt class="docutils literal"><span class="pre">#</span> <span class="pre">property:</span> <span class="pre">value</span></tt> and tweak
+certain snippets properties described below. If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found,
+the whole file is considered the snippet template.</p>
 <p>Here's a typical example:</p>
 <div class="highlight"><pre>#contributor : pluskid &lt;pluskid@gmail.com&gt;
 #name : __...__
 # --
 __${init}__
 </pre></div>
-<p>Meta data are specified in the syntax of</p>
-<div class="highlight"><pre>#data-name : data value
-</pre></div>
-<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
-ignored. Here's a list of currently supported directives:</p>
+<p>Here's a list of currently supported directives:</p>
 <div class="section" id="key-snippet-abbrev">
 <h2><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></h2>
 <p>This is the probably the most important directive, it's the
@ -200,7 +197,9 @@ loaded from.</p>
 will only be expanded when the condition code evaluate to some non-nil
 value.</p>
 <p>See also <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> in <a class="reference external" href="snippet-expansion.html">Expanding snippets</a></p>
-<p><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group</span></tt> snippet menu grouping</p>
+</div>
+<div class="section" id="group-snippet-menu-grouping">
+<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></h2>
 <p>When expanding/visiting snippets from the menu-bar menu, snippets for a
 given mode can be grouped into sub-menus . This is useful if one has
 too many snippets for a mode which will make the menu too
@ -215,10 +214,11 @@ special file (for this see <a class="reference external" href="snippet-organizat
 which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p>
 </div>
 <div class="section" id="expand-env-expand-environment">
-<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2>
-<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt> <em>varlist</em>
-form, i.e. a list of lists assigning values to variables. It can be
-used to override variable values while the snippet is being expanded.</p>
+<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2>
+<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt>
+<em>varlist form</em>, i.e. a list of lists assigning values to variables. It
+can be used to override variable values while the snippet is being
+expanded.</p>
 <p>Interesting variables to override are <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> and
 <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> (see <a class="reference external" href="snippet-expansion.html">Expanding Snippets</a>).</p>
 <p>As an example, you might normally have <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to
@ -241,7 +241,7 @@ your hard work. You can then use:</p>
 </pre></div>
 </div>
 <div class="section" id="binding-direct-keybinding">
-<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></h2>
+<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></h2>
 <p>You can use this directive to expand a snippet directly from a normal
 Emacs keybinding. The keybinding will be registered in the Emacs
 keymap named after the major mode the snippet is active
@ -267,38 +267,39 @@ you want to record the keybinding.</p>
 # --
 &lt;p&gt;`(when yas/prefix &quot;\n&quot;)`$0`(when yas/prefix &quot;\n&quot;)`&lt;/p&gt;
 </pre></div>
-<p><em>Note</em> that this feature is still <strong>experimental</strong>, it might go away,
-be changed in future release, and should be used with caution: It is
-easy to override important keybindings for many basic modes and it is
-hard to undefine them. For the moment, the variable
-<tt class="docutils literal"><span class="pre">yas/active-keybinding</span></tt> can tell you what snippet keybindings are
-active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt to
-undefine all the keybindings.</p>
+<p><strong>Note</strong>: this feature is still <strong>experimental</strong>, it might go away, be
+changed in future release, and should be used with caution: It is easy
+to override important keybindings for many basic modes and it is hard
+to undefine them. For the moment, the variable
+<tt class="docutils literal"><span class="pre">yas/active-keybindings</span></tt> can tell you what snippet keybindings are
+active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt
+to undefine all the keybindings.</p>
 </div>
 <div class="section" id="contributor-snippet-author">
-<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></h2>
+<h2><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></h2>
 <p>This is optional and has no effect whatsoever on snippet
 functionality, but it looks nice.</p>
 </div>
 </div>
 <div class="section" id="template-syntax">
-<h1><a class="toc-backref" href="#id13">Template syntax</a></h1>
+<h1><a class="toc-backref" href="#id14">Template syntax</a></h1>
 <p>The syntax of the snippet template is simple but powerful, very
 similar to TextMate's.</p>
 <div class="section" id="plain-text">
-<h2><a class="toc-backref" href="#id14">Plain Text</a></h2>
+<h2><a class="toc-backref" href="#id15">Plain Text</a></h2>
 <p>Arbitrary text can be included as the content of a template. They are
 usually interpreted as plain text, except <tt class="docutils literal"><span class="pre">$</span></tt> and <tt class="docutils literal"><span class="pre">`</span></tt>. You need to
 use <tt class="docutils literal"><span class="pre">\</span></tt> to escape them: <tt class="docutils literal"><span class="pre">\$</span></tt> and <tt class="docutils literal"><span class="pre">\`</span></tt>. The <tt class="docutils literal"><span class="pre">\</span></tt> itself may also
 needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p>
 </div>
 <div class="section" id="embedded-emacs-lisp-code">
-<h2><a class="toc-backref" href="#id15">Embedded Emacs-lisp code</a></h2>
-<p>Emacs-Lisp code can be embedded inside the template. They are written
-inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p>
-<p>They are evaluated when the snippet is being expanded. The evaluation
-is done in the same buffer as the snippet being expanded. Here's an
-example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard dynamically:</p>
+<h2><a class="toc-backref" href="#id16">Embedded Emacs-lisp code</a></h2>
+<p>Emacs-Lisp code can be embedded inside the template, written inside
+back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>). The lisp forms are evaluated when the snippet is
+being expanded. The evaluation is done in the same buffer as the
+snippet being expanded.</p>
+<p>Here's an example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard
+dynamically:</p>
 <div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
 #define $1

@ -306,7 +307,7 @@ $0

 #endif /* $1 */
 </pre></div>
-<p>From version 0.6.0, snippets expansions are run with some special
+<p>From version 0.6, snippets expansions are run with some special
 Emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You
 can therefore define a snippet like:</p>
 <div class="highlight"><pre>for ($1;$2;$3) {
@ -318,7 +319,7 @@ snippet. Alternatively, you can also customize the variable
 <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt> which will do this automatically.</p>
 </div>
 <div class="section" id="tab-stop-fields">
-<h2><a class="toc-backref" href="#id16">Tab stop fields</a></h2>
+<h2><a class="toc-backref" href="#id17">Tab stop fields</a></h2>
 <p>Tab stops are fields that you can navigate back and forth by <tt class="docutils literal"><span class="pre">TAB</span></tt>
 and <tt class="docutils literal"><span class="pre">S-TAB</span></tt>. They are written by <tt class="docutils literal"><span class="pre">$</span></tt> followed with a
 number. <tt class="docutils literal"><span class="pre">$0</span></tt> has the special meaning of the <em>exit point</em> of a
@ -330,7 +331,7 @@ fields. Here's a typical example:</p>
 </pre></div>
 </div>
 <div class="section" id="placeholder-fields">
-<h2><a class="toc-backref" href="#id17">Placeholder fields</a></h2>
+<h2><a class="toc-backref" href="#id18">Placeholder fields</a></h2>
 <p>Tab stops can have default values -- a.k.a placeholders. The syntax is
 like this:</p>
 <div class="highlight"><pre>${N:default value}
@ -341,7 +342,7 @@ typing. The number can be omitted if you don't want to create
 <a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
 </div>
 <div class="section" id="id2">
-<span id="mirrors"></span><h2><a class="toc-backref" href="#id18">Mirrors</a></h2>
+<span id="mirrors"></span><h2><a class="toc-backref" href="#id19">Mirrors</a></h2>
 <p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
 mirrors. Its mirrors will get updated when you change the text of a
 field. Here's an example:</p>
@ -357,7 +358,7 @@ none of the tab stops has an initial value, the first one is selected
 as the field and others mirrors.</p>
 </div>
 <div class="section" id="mirrors-with-transformations">
-<span id="transformations"></span><h2><a class="toc-backref" href="#id19">Mirrors with transformations</a></h2>
+<span id="transformations"></span><h2><a class="toc-backref" href="#id20">Mirrors with transformations</a></h2>
 <p>If the value of an <tt class="docutils literal"><span class="pre">${n:</span></tt>-construct starts with and contains <tt class="docutils literal"><span class="pre">$(</span></tt>,
 then it is interpreted as a mirror for field <tt class="docutils literal"><span class="pre">n</span></tt> with a
 transformation. The mirror's text content is calculated according to
@ -405,7 +406,7 @@ $0
 </pre></div>
 </div>
 <div class="section" id="fields-with-transformations">
-<h2><a class="toc-backref" href="#id20">Fields with transformations</a></h2>
+<h2><a class="toc-backref" href="#id21">Fields with transformations</a></h2>
 <p>From version 0.6 on, you can also have lisp transformation inside
 fields. These work mostly mirror transformations but are evaluated
 when you first enter the field, after each change you make to the
@ -428,8 +429,8 @@ the value of the field and sets it its internal modification state to
 <tt class="docutils literal"><span class="pre">true</span></tt>. As a consequence, the auto-deletion behaviour of normal
 fields does not take place. This is by design.</p>
 </div>
-<div class="section" id="choosing-fields-value-from-a-list">
-<h2><a class="toc-backref" href="#id21">Choosing fields value from a list</a></h2>
+<div class="section" id="choosing-fields-value-from-a-list-and-other-tricks">
+<h2><a class="toc-backref" href="#id22">Choosing fields value from a list and other tricks</a></h2>
 <p>As mentioned, the field transformation is invoked just after you enter
 the field, and with some useful variables bound, notably
 <tt class="docutils literal"><span class="pre">yas/field-modified-p</span></tt> and <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Because of this
@ -441,11 +442,21 @@ you select default values for it.</p>
 &lt;/div&gt;
 </pre></div>
 <p>See the definition of <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> to see how it was written
-using the two variables. Also check out <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> for
-another neat trick.</p>
+using the two variables.</p>
+<p>Here's another use, for LaTeX-mode, which calls reftex-label just as
+you enter snippet field 2. This one makes use of <tt class="docutils literal"><span class="pre">yas/modified-p</span></tt>
+directly.</p>
+<div class="highlight"><pre>\section{${1:&quot;Titel der Tour&quot;}}%
+\index{$1}%
+\label{{2:&quot;waiting for reftex-label call...&quot;$(unless yas/modified-p (reftex-label nil &#39;dont-
+insert))}}%
+</pre></div>
+<p>The function <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> has another neat trick, and makes
+use of <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Try it and see! Also, check out this
+<a class="reference external" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662">thread</a></p>
 </div>
 <div class="section" id="nested-placeholder-fields">
-<h2><a class="toc-backref" href="#id22">Nested placeholder fields</a></h2>
+<h2><a class="toc-backref" href="#id23">Nested placeholder fields</a></h2>
 <p>From version 0.6 on, you can also have nested placeholders of the type:</p>
 <div class="highlight"><pre>&lt;div${1: id=&quot;${2:some_id}&quot;}&gt;$0&lt;/div&gt;
 </pre></div>
@ -460,9 +471,9 @@ performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-
 </div>
 </div>
 <div class="section" id="customizable-variables">
-<h1><a class="toc-backref" href="#id23">Customizable variables</a></h1>
+<h1><a class="toc-backref" href="#id24">Customizable variables</a></h1>
 <div class="section" id="yas-trigger-key">
-<h2><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
 <p>The key bound to <tt class="docutils literal"><span class="pre">yas/expand</span></tt> when function <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is
 active.</p>
 <p>Value is a string that is converted to the internal Emacs key
@ -470,7 +481,7 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
 <p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
 </div>
 <div class="section" id="yas-next-field-key">
-<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
 <p>The key to navigate to next field when a snippet is active.</p>
 <p>Value is a string that is converted to the internal Emacs key
 representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
@ -478,7 +489,7 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
 <p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
 </div>
 <div class="section" id="yas-prev-field-key">
-<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
 <p>The key to navigate to previous field when a snippet is active.</p>
 <p>Value is a string that is converted to the internal Emacs key
 representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
@ -486,7 +497,7 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
 <p>Default value is <tt class="docutils literal"><span class="pre">(&quot;&lt;backtab&gt;&quot;</span> <span class="pre">&quot;&lt;S-tab&gt;)&quot;</span></tt>.</p>
 </div>
 <div class="section" id="yas-skip-and-clear-key">
-<h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2>
 <p>The key to clear the currently active field.</p>
 <p>Value is a string that is converted to the internal Emacs key
 representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
@ -494,12 +505,12 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
 <p>Default value is <tt class="docutils literal"><span class="pre">&quot;C-d&quot;</span></tt>.</p>
 </div>
 <div class="section" id="yas-good-grace">
-<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
 <p>If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
 snippet definitions. An error string &quot;[yas] error&quot; is returned instead.</p>
 </div>
 <div class="section" id="yas-indent-line">
-<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
 <p>The variable <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> controls the indenting. It is bound
 to <tt class="docutils literal"><span class="pre">'auto</span></tt> by default, which causes your snippet to be indented
 according to the mode of the buffer it was inserted in.</p>
@ -520,7 +531,7 @@ $0$&gt;
 </pre></div>
 </div>
 <div class="section" id="yas-wrap-around-region">
-<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
 <p>If non-nil, YASnippet will try to expand the snippet's exit marker
 around the currently selected region. When this variable is set to t,
 this has the same effect has using the <tt class="docutils literal"><span class="pre">`yas/selected-text`</span></tt> inline
@ -534,18 +545,18 @@ the region), then press <tt class="docutils literal"><span class="pre">yas/trigg
 spring back to life inside your new snippet.</p>
 </div>
 <div class="section" id="yas-triggers-in-field">
-<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
 <p>If non-nil, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> can trigger stacked expansions,
 that is a snippet expansion inside another snippet
 expansion. Otherwise, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> just tries to move on to
 the next field.</p>
 </div>
 <div class="section" id="yas-snippet-revival">
-<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
 <p>Non-nil means re-activate snippet fields after undo/redo.</p>
 </div>
 <div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook">
-<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2>
 <p>These hooks are called, respectively, before the insertion of a
 snippet and after exiting the snippet. If you find any strange but
 functional use for them, that's probably a design flaw in YASnippet,
@ -553,7 +564,7 @@ so let us know.</p>
 </div>
 </div>
 <div class="section" id="importing-textmate-snippets">
-<h1><a class="toc-backref" href="#id34">Importing TextMate snippets</a></h1>
+<h1><a class="toc-backref" href="#id35">Importing TextMate snippets</a></h1>
 <p>There are a couple of tools that take TextMate's &quot;.tmSnippet&quot; xml
 files and create YASnippet definitions:</p>
 <blockquote>
--- a/doc/snippet-development.rst
+++ b/doc/snippet-development.rst
@ -15,9 +15,7 @@ Snippet development
 Quickly finding snippets
 ------------------------

-There are some ways you can quickly find a snippet file. Once you find
-this file it will be set to ``snippet-mode`` (see ahead) and you can
-start editing your snippet.
+There are some ways you can quickly find a snippet file:

 * ``M-x yas/new-snippet``

@ -29,7 +27,8 @@ start editing your snippet.
 * ``M-x yas/find-snippets``

  Lets you find the snippet file in the directory the snippet was
-  loaded from (if it exists) like ``find-file-other-window``.
+  loaded from (if it exists) like ``find-file-other-window``. The
+  directory searching logic is similar to ``M-x yas/new-snippet``.

 * ``M-x yas/visit-snippet-file``

@ -37,6 +36,9 @@ start editing your snippet.
  ``yas/insert-snippet``, but instead of expanding it, takes you
  directly to the snippet definition's file, if it exists.

+Once you find this file it will be set to ``snippet-mode`` (see ahead)
+and you can start editing your snippet.
+

 Using the ``snippet-mode`` major mode
 -------------------------------------
@ -60,22 +62,20 @@ Two commands are defined in this mode:
    can see what it looks like. This is bound to ``C-c C-t`` while in
    ``snippet-mode``.

-There are also snippets for making snippets: ``vars``, ``field`` and
-``mirror``.
+There are also *snippets for writing snippets*: ``vars``, ``$f`` and
+``$m`` :-).

 File content
 ============

-A file defining a snippet may just contain the template for the
-snippet. Optionally it can also contains some meta data for the
-snippet as well as comments.
+A file defining a snippet generally contains the template to be
+expanded.

-Generally speaking, if the file contains a line of ``# --``, then all
-contents above that line are considered directives (meta data) and
-comments; below that line lies the snippet template.
-
-If no ``# --`` is found, the whole file content is considered as the
-template.
+Optionally, if the file contains a line of ``# --``, the lines above
+it count as comments, some of which can be *directives* (or meta
+data). Snippet directives look like ``# property: value`` and tweak
+certain snippets properties described below. If no ``# --`` is found,
+the whole file is considered the snippet template.

 Here's a typical example:

@ -86,14 +86,7 @@ Here's a typical example:
  # --
  __${init}__

-Meta data are specified in the syntax of
-
-.. sourcecode:: text
-
-  #data-name : data value
-
-Any other text above ``# --`` is considered as comment and
-ignored. Here's a list of currently supported directives:
+Here's a list of currently supported directives:

 ``# key:`` snippet abbrev
 --------------------------
@ -122,7 +115,6 @@ snippet -- especially distinguishable among similar snippets.
 If you omit this name it will default to the file name the snippet was
 loaded from.

-
 ``# condition:`` snippet condition
 ----------------------------------
 This is a piece of Emacs-lisp code. If a snippet has a condition, then it
@ -132,8 +124,8 @@ value.
 See also ``yas/buffer-local-condition`` in `Expanding snippets`_


-
-``# group`` snippet menu grouping
+``# group:`` snippet menu grouping
+----------------------------------

 When expanding/visiting snippets from the menu-bar menu, snippets for a
 given mode can be grouped into sub-menus . This is useful if one has
@ -154,14 +146,14 @@ which is under the ``control structure`` group.
 ``# expand-env:`` expand environment
 ------------------------------------

-This is another piece of Emacs-lisp code in the form of a ``let`` *varlist*
-form, i.e. a list of lists assigning values to variables. It can be
-used to override variable values while the snippet is being expanded.
+This is another piece of Emacs-lisp code in the form of a ``let``
+*varlist form*, i.e. a list of lists assigning values to variables. It
+can be used to override variable values while the snippet is being
+expanded.

 Interesting variables to override are ``yas/wrap-around-region`` and
 ``yas/indent-line`` (see `Expanding Snippets`_).

-
 As an example, you might normally have ``yas/indent-line`` set to
 ``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this
 particularly brilliant piece of ASCII art these values would mess up
@ -219,13 +211,13 @@ you want to record the keybinding.
  # --
  <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>

-*Note* that this feature is still **experimental**, it might go away,
-be changed in future release, and should be used with caution: It is
-easy to override important keybindings for many basic modes and it is
-hard to undefine them. For the moment, the variable
-``yas/active-keybinding`` can tell you what snippet keybindings are
-active and the function ``yas/kill-snippet-keybindings`` will attempt to
-undefine all the keybindings.
+**Note**: this feature is still **experimental**, it might go away, be
+changed in future release, and should be used with caution: It is easy
+to override important keybindings for many basic modes and it is hard
+to undefine them. For the moment, the variable
+``yas/active-keybindings`` can tell you what snippet keybindings are
+active and the function ``yas/kill-snippet-keybindings`` will attempt
+to undefine all the keybindings.

 ``# contributor:`` snippet author
 ---------------------------------------------------
@ -251,12 +243,13 @@ needed to be escaped as ``\\`` sometimes.
 Embedded Emacs-lisp code
 ------------------------

-Emacs-Lisp code can be embedded inside the template. They are written
-inside back-quotes (`````):
+Emacs-Lisp code can be embedded inside the template, written inside
+back-quotes (`````). The lisp forms are evaluated when the snippet is
+being expanded. The evaluation is done in the same buffer as the
+snippet being expanded. 

-They are evaluated when the snippet is being expanded. The evaluation
-is done in the same buffer as the snippet being expanded. Here's an
-example for ``c-mode`` to calculate the header file guard dynamically:
+Here's an example for ``c-mode`` to calculate the header file guard
+dynamically:

 .. sourcecode:: text

@ -267,7 +260,7 @@ example for ``c-mode`` to calculate the header file guard dynamically:

  #endif /* $1 */

-From version 0.6.0, snippets expansions are run with some special
+From version 0.6, snippets expansions are run with some special
 Emacs-lisp variables bound. One of this is ``yas/selected-text``. You
 can therefore define a snippet like:

@ -432,8 +425,8 @@ the value of the field and sets it its internal modification state to
 ``true``. As a consequence, the auto-deletion behaviour of normal
 fields does not take place. This is by design.

-Choosing fields value from a list
---------------------------------
+Choosing fields value from a list and other tricks
+--------------------------------------------------

 As mentioned, the field transformation is invoked just after you enter
 the field, and with some useful variables bound, notably
@ -445,13 +438,28 @@ The ``yas/choose-value`` does this work for you. For example:

 .. sourcecode:: text

-   <div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
-     $0
-   </div>
+  <div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
+    $0
+  </div>

 See the definition of ``yas/choose-value`` to see how it was written
-using the two variables. Also check out ``yas/verify-value`` for
-another neat trick.
+using the two variables.
+
+Here's another use, for LaTeX-mode, which calls reftex-label just as
+you enter snippet field 2. This one makes use of ``yas/modified-p``
+directly.
+
+.. sourcecode:: text 
+
+  \section{${1:"Titel der Tour"}}%
+  \index{$1}%
+  \label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-
+  insert))}}%  
+
+The function ``yas/verify-value`` has another neat trick, and makes
+use of ``yas/moving-away-p``. Try it and see! Also, check out this
+`thread
+<http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662>`_

 Nested placeholder fields
 -------------------------
--- a/doc/snippet-expansion.html
+++ b/doc/snippet-expansion.html
@ -74,7 +74,7 @@
 <li><a class="reference internal" href="#the-condition-system" id="id12">The condition system</a></li>
 <li><a class="reference internal" href="#multiples-snippet-with-the-same-key" id="id13">Multiples snippet with the same key</a><ul>
 <li><a class="reference internal" href="#use-the-x-window-system" id="id14">Use the X window system</a></li>
-<li><a class="reference internal" href="#use-built-in-emacs-selection-methods" id="id15">Use built-in Emacs selection methods</a></li>
+<li><a class="reference internal" href="#minibuffer-prompting" id="id15">Minibuffer prompting</a></li>
 <li><a class="reference internal" href="#use-dropdown-menu-el" id="id16">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></li>
 <li><a class="reference internal" href="#roll-your-own" id="id17">Roll your own</a></li>
 </ul>
@ -95,9 +95,10 @@
 <h1><a class="toc-backref" href="#id2">Triggering expansion</a></h1>
 <p>You can use YASnippet to expand snippets in different ways:</p>
 <ul class="simple">
-<li>By typing a snippet abbrev and then pressing the key defined in
-<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to &quot;TAB&quot;). This works in a
-buffer where the minor mode <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li>
+<li>By typing an abbrev, the snippet <em>trigger key</em>, and then pressing
+the key defined in <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to
+&quot;TAB&quot;). This works in buffers where the minor mode
+<tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li>
 <li>By invoking the command <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> (either by typing
 <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/insert-snippet</span></tt> or its keybinding). This does <em>not</em>
 require <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active.</li>
@ -171,12 +172,12 @@ prefer.</p>
 </div>
 <div class="section" id="expanding-from-emacs-lisp-code">
 <h2><a class="toc-backref" href="#id9">Expanding from emacs-lisp code</a></h2>
-<p>Sometimes you might want to expand a snippet directly by calling a
-functin from elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt>
-instead of <tt class="docutils literal"><span class="pre">yas/expand</span></tt> in this case.</p>
-<p>As with expanding from the menubar, condition system and multiple
-candidates won't exists here. In fact, expanding from menubar has the
-same effect of evaluating the follow code:</p>
+<p>Sometimes you might want to expand a snippet directly from you own
+elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> instead of
+<tt class="docutils literal"><span class="pre">yas/expand</span></tt> in this case.</p>
+<p>As with expanding from the menubar, the condition system and multiple
+candidates doesn't affect expansion. In fact, expanding from the
+YASnippet menu has the same effect of evaluating the follow code:</p>
 <div class="highlight"><pre>(<span style="color: #19177C">yas/expand-snippet</span> <span style="color: #19177C">template</span>)
 </pre></div>
 <p>See the internal documentation on <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> for more
@ -188,7 +189,7 @@ information.</p>
 <div class="section" id="eligible-snippets">
 <h2><a class="toc-backref" href="#id11">Eligible snippets</a></h2>
 <p>YASnippet does quite a bit of filtering to find out which snippets are
-eligible for expanding at point.</p>
+eligible for expanding at the current cursor position.</p>
 <p>In particular, the following things matter:</p>
 <ul>
 <li><p class="first">Currently loaded snippets tables</p>
@ -197,21 +198,22 @@ eligible for expanding at point.</p>
 <tt class="docutils literal"><span class="pre">html-mode</span></tt>, <tt class="docutils literal"><span class="pre">ruby-mode</span></tt>, etc...</p>
 </li>
 <li><p class="first">Major mode of the current buffer</p>
-<p>If it matches one of the loaded snippet tables, then all that
-table's snippets are considered for expansion. Use <tt class="docutils literal"><span class="pre">M-x</span>
-<span class="pre">describe-variable</span> <span class="pre">RET</span> <span class="pre">major-mode</span> <span class="pre">RET</span></tt> to find out which mode you
-are in currently.</p>
+<p>If the currrent major mode matches one of the loaded snippet tables,
+then all that table's snippets are considered for expansion. Use
+<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-variable</span> <span class="pre">RET</span> <span class="pre">major-mode</span> <span class="pre">RET</span></tt> to find out which major
+mode you are in currently.</p>
 </li>
 <li><p class="first">Parent tables</p>
-<p>Snippet tables defined as parent of some other table considered in
-the previous step are also considered.</p>
+<p>Snippet tables defined as the parent of some other eligible table
+are also considered. This works recursively, i.e. parents of parents
+of eligible tables are also considered.</p>
 </li>
 <li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/mode-symbol</span></tt> variable</p>
 <p>This can be used to consider snippet tables whose name does not
 correspond to a major mode. If you set this variable to a name ,
 like <tt class="docutils literal"><span class="pre">rinari-minor-mode</span></tt>, you can have some snippets expand only
 in that minor mode. Naturally, you want to set this conditionally,
-i.e. only when entering that minor mode, using a hook is a good
+i.e. only when entering that minor mode, so using a hook is a good
 idea.</p>
 </li>
 </ul>
@ -223,10 +225,10 @@ idea.</p>
 </pre></div>
 <ul>
 <li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> variable</p>
-<p>This variable provides more fine grained control over what snippets
-can be expanded in the current buffer. The default value, won't let
-you expand snippets inside comments or string literals for
-example. See <a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p>
+<p>This variable provides finer grained control over what snippets can
+be expanded in the current buffer. The default value won't let you
+expand snippets inside comments or string literals for example. See
+<a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p>
 </li>
 </ul>
 </div>
@ -294,9 +296,9 @@ other snippets like <tt class="docutils literal"><span class="pre">if</span></tt
 <p>The rules outlined <a class="reference external" href="Eligiblesnippets">above</a> can return more than
 one snippet to be expanded at point.</p>
 <p>When there are multiple candidates, YASnippet will let you select
-one. The UI for selecting multiple candidate can be customized. A
-customization variable, called <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> defines your
-preferred method of being prompted for snippets.</p>
+one. The UI for selecting multiple candidate can be customized through
+<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> , which defines your preferred methods of
+being prompted for snippets.</p>
 <p>You can customize it with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">customize-variable</span> <span class="pre">RET</span>
 <span class="pre">yas/prompt-functions</span> <span class="pre">RET</span></tt>. Alternatively you can put in your
 emacs-file:</p>
@ -318,8 +320,8 @@ support, this menu will be rendered with your gtk theme.</li>
 </ul>
 <img align="right" alt="images/ido-menu.png" class="align-right" src="images/ido-menu.png" />
 </div>
-<div class="section" id="use-built-in-emacs-selection-methods">
-<h3><a class="toc-backref" href="#id15">Use built-in Emacs selection methods</a></h3>
+<div class="section" id="minibuffer-prompting">
+<h3><a class="toc-backref" href="#id15">Minibuffer prompting</a></h3>
 <p>You can use functions <tt class="docutils literal"><span class="pre">yas/completing-prompt</span></tt> for the classic emacs
 completion method or <tt class="docutils literal"><span class="pre">yas/ido-prompt</span></tt> for a much nicer looking
 method. The best way is to try it. This works in a terminal.</p>
@ -390,11 +392,11 @@ eligible tables.</p>
 <div class="section" id="yas-key-syntaxes">
 <h2><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt></a></h2>
 <p>The default searching strategy is quite powerful. For example, in
-<tt class="docutils literal"><span class="pre">c-mode</span></tt>, <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;#foo_bar&quot;</span></tt> can all be
-recognized as a snippet key. Furthermore, the searching is in that
-order. In other words, if <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt> is found to be a key to some
-<em>valid</em> snippet, then <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt> and <tt class="docutils literal"><span class="pre">&quot;#foobar&quot;</span></tt> won't be
-searched.</p>
+<tt class="docutils literal"><span class="pre">c-mode</span></tt>, <tt class="docutils literal"><span class="pre">bar</span></tt>, <tt class="docutils literal"><span class="pre">foo_bar</span></tt>, <tt class="docutils literal"><span class="pre">&quot;#foo_bar&quot;</span></tt> can all be recognized
+as a snippet key. Furthermore, the searching is in that order. In
+other words, if <tt class="docutils literal"><span class="pre">bar</span></tt> is found to be a key to some <em>valid</em> snippet,
+then that snippet is expanded and replaces the <tt class="docutils literal"><span class="pre">bar</span></tt>. Snippets
+pointed to by <tt class="docutils literal"><span class="pre">foo_bar</span></tt> and <tt class="docutils literal"><span class="pre">&quot;#foobar</span></tt> won't be considered.</p>
 <p>However, this strategy can also be customized easily from the
 <tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt> variable. It is a list of syntax rules, the
 default value is <tt class="docutils literal"><span class="pre">(&quot;w&quot;</span> <span class="pre">&quot;w_&quot;</span> <span class="pre">&quot;w_.&quot;</span> <span class="pre">&quot;^</span> <span class="pre">&quot;)</span></tt>. Which means search the
@ -405,8 +407,8 @@ following thing until found one:</p>
 <li>a sequence of characters of either word, symbol or punctuation.</li>
 <li>a sequence of characters of non-whitespace characters.</li>
 </ul>
-<p>But you'd better keep the default value unless you understand what
-Emacs's syntax rule mean.</p>
+<p>But you'd better keep the default value unless you want to understand
+how Emacs's syntax rules work...</p>
 </div>
 </div>
 	  </div>
--- a/doc/snippet-expansion.rst
+++ b/doc/snippet-expansion.rst
@ -15,9 +15,10 @@ Triggering expansion

 You can use YASnippet to expand snippets in different ways:

-* By typing a snippet abbrev and then pressing the key defined in
-  ``yas/trigger-key`` (which defaults to "TAB"). This works in a
-  buffer where the minor mode ``yas/minor-mode`` is active;
+* By typing an abbrev, the snippet *trigger key*, and then pressing
+  the key defined in ``yas/trigger-key`` (which defaults to
+  "TAB"). This works in buffers where the minor mode
+  ``yas/minor-mode`` is active;

 * By invoking the command ``yas/insert-snippet`` (either by typing
  ``M-x yas/insert-snippet`` or its keybinding). This does *not*
@ -115,13 +116,13 @@ prefer.
 Expanding from emacs-lisp code
 ------------------------------

-Sometimes you might want to expand a snippet directly by calling a
-functin from elisp code. You should call ``yas/expand-snippet``
-instead of ``yas/expand`` in this case.
+Sometimes you might want to expand a snippet directly from you own
+elisp code. You should call ``yas/expand-snippet`` instead of
+``yas/expand`` in this case.

-As with expanding from the menubar, condition system and multiple
-candidates won't exists here. In fact, expanding from menubar has the
-same effect of evaluating the follow code:
+As with expanding from the menubar, the condition system and multiple
+candidates doesn't affect expansion. In fact, expanding from the
+YASnippet menu has the same effect of evaluating the follow code:

 .. sourcecode:: common-lisp

@ -137,7 +138,7 @@ Eligible snippets
 -----------------

 YASnippet does quite a bit of filtering to find out which snippets are
-eligible for expanding at point.
+eligible for expanding at the current cursor position.

 In particular, the following things matter:

@ -149,15 +150,16 @@ In particular, the following things matter:

 * Major mode of the current buffer

-  If it matches one of the loaded snippet tables, then all that
-  table's snippets are considered for expansion. Use ``M-x
-  describe-variable RET major-mode RET`` to find out which mode you
-  are in currently.
+  If the currrent major mode matches one of the loaded snippet tables,
+  then all that table's snippets are considered for expansion. Use
+  ``M-x describe-variable RET major-mode RET`` to find out which major
+  mode you are in currently.

 * Parent tables

-  Snippet tables defined as parent of some other table considered in
-  the previous step are also considered.
+  Snippet tables defined as the parent of some other eligible table
+  are also considered. This works recursively, i.e. parents of parents
+  of eligible tables are also considered.

 * Buffer-local ``yas/mode-symbol`` variable

@ -165,7 +167,7 @@ In particular, the following things matter:
  correspond to a major mode. If you set this variable to a name ,
  like ``rinari-minor-mode``, you can have some snippets expand only
  in that minor mode. Naturally, you want to set this conditionally,
-  i.e. only when entering that minor mode, using a hook is a good
+  i.e. only when entering that minor mode, so using a hook is a good
  idea.

 .. sourcecode:: common-lisp
@ -178,10 +180,10 @@ In particular, the following things matter:

 * Buffer-local ``yas/buffer-local-condition`` variable

-  This variable provides more fine grained control over what snippets
-  can be expanded in the current buffer. The default value, won't let
-  you expand snippets inside comments or string literals for
-  example. See `The condition system`_ for more info.
+  This variable provides finer grained control over what snippets can
+  be expanded in the current buffer. The default value won't let you
+  expand snippets inside comments or string literals for example. See
+  `The condition system`_ for more info.

 The condition system
 --------------------
@ -260,9 +262,9 @@ The rules outlined `above <Eligible snippets>`_ can return more than
 one snippet to be expanded at point.

 When there are multiple candidates, YASnippet will let you select
-one. The UI for selecting multiple candidate can be customized. A
-customization variable, called ``yas/prompt-functions`` defines your
-preferred method of being prompted for snippets.
+one. The UI for selecting multiple candidate can be customized through
+``yas/prompt-functions`` , which defines your preferred methods of
+being prompted for snippets.

 You can customize it with ``M-x customize-variable RET
 yas/prompt-functions RET``. Alternatively you can put in your
@ -293,8 +295,8 @@ which means:
 .. image:: images/ido-menu.png
   :align: right

-Use built-in Emacs selection methods
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Minibuffer prompting
+~~~~~~~~~~~~~~~~~~~~

 You can use functions ``yas/completing-prompt`` for the classic emacs
 completion method or ``yas/ido-prompt`` for a much nicer looking
@ -324,7 +326,6 @@ Customizable Variables
 ``yas/prompt-functions``
 ------------------------

-
 You can write a function and add it to the ``yas/prompt-functions``
 list. These functions are called with the following arguments:

@ -383,11 +384,11 @@ This affects ``yas/insert-snippet``, ``yas/visit-snippet-file``
 --------------------

 The default searching strategy is quite powerful. For example, in
-``c-mode``, ``"bar"``, ``"foo_bar"``, ``"#foo_bar"`` can all be
-recognized as a snippet key. Furthermore, the searching is in that
-order. In other words, if ``"bar"`` is found to be a key to some
-*valid* snippet, then ``"foo_bar"`` and ``"#foobar"`` won't be
-searched.
+``c-mode``, ``bar``, ``foo_bar``, ``"#foo_bar"`` can all be recognized
+as a snippet key. Furthermore, the searching is in that order. In
+other words, if ``bar`` is found to be a key to some *valid* snippet,
+then that snippet is expanded and replaces the ``bar``. Snippets
+pointed to by ``foo_bar`` and ``"#foobar`` won't be considered.

 However, this strategy can also be customized easily from the
 ``yas/key-syntaxes`` variable. It is a list of syntax rules, the
@ -399,7 +400,7 @@ following thing until found one:
 * a sequence of characters of either word, symbol or punctuation.
 * a sequence of characters of non-whitespace characters.

-But you'd better keep the default value unless you understand what
-Emacs's syntax rule mean.
+But you'd better keep the default value unless you want to understand
+how Emacs's syntax rules work...


--- a/doc/snippet-menu.html
+++ b/doc/snippet-menu.html
@ -65,7 +65,7 @@
 </ul>
 </div>
 <p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active, YASnippet will setup a menu just
-after the Buffers Menu in the menubar.</p>
+after the &quot;Buffers&quot; menu in the menubar.</p>
 <p>In this menu, you can find</p>
 <ul class="simple">
 <li>The currently loaded snippet definitions, organized by major mode,
--- a/doc/snippet-menu.rst
+++ b/doc/snippet-menu.rst
@ -5,7 +5,7 @@ YASnippet menu
 .. contents::

 When ``yas/minor-mode`` is active, YASnippet will setup a menu just
-after the Buffers Menu in the menubar. 
+after the "Buffers" menu in the menubar. 

 In this menu, you can find

--- a/doc/snippet-organization.html
+++ b/doc/snippet-organization.html
@ -57,34 +57,35 @@
            <div class="contents topic" id="contents">
 <p class="topic-title first">Contents</p>
 <ul class="simple">
-<li><a class="reference internal" href="#loading-snippets" id="id4">Loading snippets</a></li>
-<li><a class="reference internal" href="#id2" id="id5">Organizing snippets</a><ul>
-<li><a class="reference internal" href="#nested-organization" id="id6">Nested organization</a></li>
-<li><a class="reference internal" href="#the-yas-parents-file" id="id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></li>
-<li><a class="reference internal" href="#the-yas-make-groups-file" id="id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></li>
-<li><a class="reference internal" href="#using-plain-file-names" id="id9">Using plain file names</a></li>
+<li><a class="reference internal" href="#loading-snippets" id="id3">Loading snippets</a></li>
+<li><a class="reference internal" href="#id2" id="id4">Organizing snippets</a><ul>
+<li><a class="reference internal" href="#nested-organization" id="id5">Nested organization</a></li>
+<li><a class="reference internal" href="#the-yas-parents-file" id="id6">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></li>
+<li><a class="reference internal" href="#the-yas-make-groups-file" id="id7">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></li>
+<li><a class="reference internal" href="#using-plain-file-names" id="id8">Using plain file names</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#id3" id="id10">YASnippet bundle</a></li>
-<li><a class="reference internal" href="#customizable-variables" id="id11">Customizable variables</a><ul>
-<li><a class="reference internal" href="#yas-root-directory" id="id12"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></li>
-<li><a class="reference internal" href="#yas-ignore-filenames-as-triggers" id="id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></li>
+<li><a class="reference internal" href="#yasnippet-bundle" id="id9">YASnippet bundle</a></li>
+<li><a class="reference internal" href="#customizable-variables" id="id10">Customizable variables</a><ul>
+<li><a class="reference internal" href="#yas-root-directory" id="id11"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></li>
+<li><a class="reference internal" href="#yas-ignore-filenames-as-triggers" id="id12"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></li>
 </ul>
 </li>
 </ul>
 </div>
 <div class="section" id="loading-snippets">
-<h1><a class="toc-backref" href="#id4">Loading snippets</a></h1>
-<p>Snippet definitions are stored in files in the filesystem and you have
-to arrange for YASnippet to load them (unless you use a <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet
-bundle</a>) into <em>snippet tables</em>.</p>
-<p>The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will look up
-these snippet tables and (hopefully) expand your intended snippet.</p>
+<h1><a class="toc-backref" href="#id3">Loading snippets</a></h1>
+<p>Snippet definitions are stored in files in the filesystem. Unless you
+use the simpler <a class="reference external" href="mailto:index.html&#64;installation">bundle version</a>), these
+are arranged so that YASnippet can load them into <em>snippet
+tables</em>. The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will
+look up these snippet tables and (hopefully) expand the snippet you
+intended.</p>
 <p>The non-bundle version of YASnippet, once unpacked, comes with a full
 directory of snippets, which you can copy somewhere and use. You can
-also create or download, one or more directories.</p>
+also create or download more directories.</p>
 <p>Once these directories are in place reference them in the variable
-<tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and then load them with <tt class="docutils literal"><span class="pre">yas/load-directory</span></tt>:</p>
+<tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and load them with <tt class="docutils literal"><span class="pre">yas/load-directory</span></tt>:</p>
 <div class="highlight"><pre><span style="color: #408080; font-style: italic">;; Develop and keep personal snippets under ~/emacs.d/mysnippets</span>
 (<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/root-directory</span> <span style="color: #BA2121">&quot;~/emacs.d/mysnippets&quot;</span>)

@ -105,12 +106,12 @@ Snippets</a>.</p>
 <span style="color: #408080; font-style: italic">;; Map `yas/load-directory&#39; to every element</span>
 (<span style="color: #008000">mapc</span> <span style="color: #19177C">&#39;yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>)
 </pre></div>
-<p>Here the directories after the first are loaded, their snippets
-considered for expansion, but development still happens in
-&quot;~/emacs.d/mysnippets&quot;</p>
+<p>In this last example, the all the directories are loaded and their
+snippets considered for expansion. However development still happens
+in the first element, &quot;~/emacs.d/mysnippets&quot;.</p>
 </div>
 <div class="section" id="id2">
-<h1><a class="toc-backref" href="#id5">Organizing snippets</a></h1>
+<h1><a class="toc-backref" href="#id4">Organizing snippets</a></h1>
 <p>Once you've setup <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> , you can store snippets
 inside sub-directories of these directories.</p>
 <p>Snippet definitions are put in plain text files. They are arranged by
@ -118,9 +119,9 @@ sub-directories, and the snippet tables are named after these directories.</p>
 <p>The name corresponds to the Emacs mode where you want expansion to
 take place. For example, snippets for <tt class="docutils literal"><span class="pre">c-mode</span></tt> are put in the
 <tt class="docutils literal"><span class="pre">c-mode</span></tt> sub-directory. You can also skip snippet storage altogether
-and use the bundle (see <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet bundle</a>).</p>
+and use the bundle (see <a class="reference internal" href="#yasnippet-bundle">YASnippet bundle</a>).</p>
 <div class="section" id="nested-organization">
-<h2><a class="toc-backref" href="#id6">Nested organization</a></h2>
+<h2><a class="toc-backref" href="#id5">Nested organization</a></h2>
 <p>Here is an excerpt of a directory hierarchy containing snippets
 for some modes:</p>
 <div class="highlight"><pre>$ tree
@ -140,20 +141,23 @@ for some modes:</p>
    `-- time
 </pre></div>
 <p>A parent directory acts as a <em>parent table</em> of any of its
-sub-directories. This is one of the ways YASnippet can share snippet
-definitions among different modes. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt>
-and <tt class="docutils literal"><span class="pre">java-mode</span></tt> share the same parents <tt class="docutils literal"><span class="pre">cc-mode</span></tt>, while all modes
-are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>.</p>
+sub-directories. This is one of the ways different Emacs major modes
+can share snippet definitions. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and
+<tt class="docutils literal"><span class="pre">java-mode</span></tt> share the same parent <tt class="docutils literal"><span class="pre">cc-mode</span></tt> and its <tt class="docutils literal"><span class="pre">while</span></tt>
+snipepts, while all modes are share the <tt class="docutils literal"><span class="pre">time</span></tt> snippet from
+<tt class="docutils literal"><span class="pre">text-mode</span></tt>.</p>
 <p>This can be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty
 directory whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p>
 <img align="right" alt="images/menu-parent.png" class="align-right" src="images/menu-parent.png" />
 </div>
 <div class="section" id="the-yas-parents-file">
-<h2><a class="toc-backref" href="#id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2>
-<p>If you place a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the
-sub-directories you can bypass nesting and still have parent modes. In
-this file you just write white-space-separated names of modes. This
-allows more flexibility and readability of your snippet hierarchy.</p>
+<h2><a class="toc-backref" href="#id6">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2>
+<p>An alternate (and preferred) way of setting up parent tables consists
+of placing a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the
+sub-directories. By doing this, you avoid complex directory
+nesting. In the <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file you just write
+whitespace-separated names of modes. This allows more flexibility and
+readability of your snippet hierarchy.</p>
 <div class="highlight"><pre>$ tree
 .
 |-- c-mode
@ -171,7 +175,7 @@ allows more flexibility and readability of your snippet hierarchy.</p>
 </pre></div>
 </div>
 <div class="section" id="the-yas-make-groups-file">
-<h2><a class="toc-backref" href="#id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2>
+<h2><a class="toc-backref" href="#id7">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2>
 <img align="right" alt="images/menu-groups.png" class="align-right" src="images/menu-groups.png" />
 <p>If you place an empty plain text file <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> inside one
 of the mode directories, the names of these sub-directories are
@ -195,7 +199,7 @@ ruby-mode/
 </pre></div>
 </div>
 <div class="section" id="using-plain-file-names">
-<h2><a class="toc-backref" href="#id9">Using plain file names</a></h2>
+<h2><a class="toc-backref" href="#id8">Using plain file names</a></h2>
 <p>Normally, file names act as the snippet expansion <em>abbreviation</em> (also
 known as the <em>snippet key</em> or <em>snippet trigger</em>, see <a class="reference external" href="snippet-expansion.html">Expanding
 Snippets</a>).</p>
@ -222,8 +226,8 @@ rails-mode/
 </pre></div>
 </div>
 </div>
-<div class="section" id="id3">
-<h1><a class="toc-backref" href="#id10">YASnippet bundle</a></h1>
+<div class="section" id="yasnippet-bundle">
+<h1><a class="toc-backref" href="#id9">YASnippet bundle</a></h1>
 <p>The most convenient way to define snippets for YASnippet is to put
 them in a directory arranged by the mode and use
 <tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> to load them.</p>
@ -247,18 +251,18 @@ generated this way.</p>
 </ul>
 </div>
 <div class="section" id="customizable-variables">
-<h1><a class="toc-backref" href="#id11">Customizable variables</a></h1>
+<h1><a class="toc-backref" href="#id10">Customizable variables</a></h1>
 <div class="section" id="yas-root-directory">
-<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></h2>
 <p>Root directory that stores the snippets for each major mode.</p>
-<p>Can also be a list of strings, for multiple root directories. If
-you make this a list, the first element is always the
-user-created snippets directory.</p>
-<p>Other directories are used for bulk reloading of all snippets using
+<p>If you set this from your .emacs, can also be a list of strings,
+for multiple root directories. If you make this a list, the first
+element is always the user-created snippets directory. Other
+directories are used for bulk reloading of all snippets using
 <tt class="docutils literal"><span class="pre">yas/reload-all</span></tt></p>
 </div>
 <div class="section" id="yas-ignore-filenames-as-triggers">
-<h2><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></h2>
+<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></h2>
 <p>If non-nil, don't derive tab triggers from filenames.</p>
 <p>This means a snippet without a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive wont have a tab
 trigger.</p>
--- a/doc/snippet-organization.rst
+++ b/doc/snippet-organization.rst
@ -12,19 +12,19 @@ Organizing snippets
 Loading snippets
 ================

-Snippet definitions are stored in files in the filesystem and you have
-to arrange for YASnippet to load them (unless you use a `YASnippet
-bundle <index.html@bundle-install>`_) into *snippet tables*.
-
-The triggering mechanisms (see `Expanding snippets`_) will look up
-these snippet tables and (hopefully) expand your intended snippet.
+Snippet definitions are stored in files in the filesystem. Unless you
+use the simpler `bundle version <index.html@installation>`_), these
+are arranged so that YASnippet can load them into *snippet
+tables*. The triggering mechanisms (see `Expanding snippets`_) will
+look up these snippet tables and (hopefully) expand the snippet you
+intended.

 The non-bundle version of YASnippet, once unpacked, comes with a full
 directory of snippets, which you can copy somewhere and use. You can
-also create or download, one or more directories.
+also create or download more directories.

 Once these directories are in place reference them in the variable
-``yas/root-directory`` and then load them with ``yas/load-directory``:
+``yas/root-directory`` and load them with ``yas/load-directory``:

 .. sourcecode:: common-lisp

@ -52,9 +52,9 @@ You can make this variable a list and store more items into it:
  ;; Map `yas/load-directory' to every element
  (mapc 'yas/load-directory yas/root-directory)

-Here the directories after the first are loaded, their snippets
-considered for expansion, but development still happens in
-"~/emacs.d/mysnippets"
+In this last example, the all the directories are loaded and their
+snippets considered for expansion. However development still happens
+in the first element, "~/emacs.d/mysnippets".

 Organizing snippets
 ===================
@ -95,10 +95,11 @@ for some modes:
      `-- time

 A parent directory acts as a *parent table* of any of its
-sub-directories. This is one of the ways YASnippet can share snippet
-definitions among different modes. As you can see above, ``c-mode``
-and ``java-mode`` share the same parents ``cc-mode``, while all modes
-are derived from ``text-mode``.
+sub-directories. This is one of the ways different Emacs major modes
+can share snippet definitions. As you can see above, ``c-mode`` and
+``java-mode`` share the same parent ``cc-mode`` and its ``while``
+snipepts, while all modes are share the ``time`` snippet from
+``text-mode``.

 This can be also used to as an *alias* -- ``cperl-mode`` is an empty
 directory whose parent is ``perl-mode``.
@ -109,10 +110,12 @@ directory whose parent is ``perl-mode``.
 The ``.yas-parents`` file
 ------------------------------

-If you place a plain text file ``.yas-parents`` inside one of the
-sub-directories you can bypass nesting and still have parent modes. In
-this file you just write white-space-separated names of modes. This
-allows more flexibility and readability of your snippet hierarchy.
+An alternate (and preferred) way of setting up parent tables consists
+of placing a plain text file ``.yas-parents`` inside one of the
+sub-directories. By doing this, you avoid complex directory
+nesting. In the ``.yas-parents`` file you just write
+whitespace-separated names of modes. This allows more flexibility and
+readability of your snippet hierarchy.

 .. sourcecode:: text

@ -231,11 +234,10 @@ Customizable variables

 Root directory that stores the snippets for each major mode.

-Can also be a list of strings, for multiple root directories. If
-you make this a list, the first element is always the
-user-created snippets directory. 
-
-Other directories are used for bulk reloading of all snippets using
+If you set this from your .emacs, can also be a list of strings,
+for multiple root directories. If you make this a list, the first
+element is always the user-created snippets directory. Other
+directories are used for bulk reloading of all snippets using
 ``yas/reload-all``

 ``yas/ignore-filenames-as-triggers``