From ef9a0d5e69d91712119ac437e430d1864199d0dc Mon Sep 17 00:00:00 2001
From: capitaomorte <joaotavora@gmail.com>
Date: Thu, 20 Aug 2009 17:03:51 +0000
Subject: [PATCH] wrote more documentation, still a bit to go...

---
 doc/changelog.html            |  11 +-
 doc/faq.html                  |  11 +-
 doc/index.html                |  11 +-
 doc/snippet-development.html  |  11 +-
 doc/snippet-expansion.html    |  11 +-
 doc/snippet-menu.html         |  89 +++++++
 doc/snippet-organization.html | 420 ++++++++++++-------------------
 doc/snippet-organization.rst  | 461 ++++++++++++++--------------------
 doc/styles.css                |   1 +
 doc/template.txt              |  11 +-
 10 files changed, 481 insertions(+), 556 deletions(-)
 create mode 100644 doc/snippet-menu.html

diff --git a/doc/changelog.html b/doc/changelog.html
index c015c97..73dc5a3 100644
--- a/doc/changelog.html
+++ b/doc/changelog.html
@@ -20,16 +20,19 @@
     </div>
     <ul class="primary-links">
       <li>
-        <a title="" href="index.html">Home</a>
+        <a title="" href="index.html">Intro and tutorial</a>
       </li>
       <li>
-        <a title="" href="snippet-organization.html">Organize</a>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
       </li>
       <li>
-        <a title="" href="snippet-expansion.html">Expand</a>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
       </li>
       <li>
-        <a title="" href="snippet-development.html">Write</a>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
       </li>
       <li>
         <a title="" href="faq.html">FAQ</a>
diff --git a/doc/faq.html b/doc/faq.html
index c69bc8d..1ca145f 100644
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -20,16 +20,19 @@
     </div>
     <ul class="primary-links">
       <li>
-        <a title="" href="index.html">Home</a>
+        <a title="" href="index.html">Intro and tutorial</a>
       </li>
       <li>
-        <a title="" href="snippet-organization.html">Organize</a>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
       </li>
       <li>
-        <a title="" href="snippet-expansion.html">Expand</a>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
       </li>
       <li>
-        <a title="" href="snippet-development.html">Write</a>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
       </li>
       <li>
         <a title="" href="faq.html">FAQ</a>
diff --git a/doc/index.html b/doc/index.html
index 864538c..8b7f40f 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -20,16 +20,19 @@
     </div>
     <ul class="primary-links">
       <li>
-        <a title="" href="index.html">Home</a>
+        <a title="" href="index.html">Intro and tutorial</a>
       </li>
       <li>
-        <a title="" href="snippet-organization.html">Organize</a>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
       </li>
       <li>
-        <a title="" href="snippet-expansion.html">Expand</a>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
       </li>
       <li>
-        <a title="" href="snippet-development.html">Write</a>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
       </li>
       <li>
         <a title="" href="faq.html">FAQ</a>
diff --git a/doc/snippet-development.html b/doc/snippet-development.html
index 3504695..aea88ca 100644
--- a/doc/snippet-development.html
+++ b/doc/snippet-development.html
@@ -20,16 +20,19 @@
     </div>
     <ul class="primary-links">
       <li>
-        <a title="" href="index.html">Home</a>
+        <a title="" href="index.html">Intro and tutorial</a>
       </li>
       <li>
-        <a title="" href="snippet-organization.html">Organize</a>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
       </li>
       <li>
-        <a title="" href="snippet-expansion.html">Expand</a>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
       </li>
       <li>
-        <a title="" href="snippet-development.html">Write</a>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
       </li>
       <li>
         <a title="" href="faq.html">FAQ</a>
diff --git a/doc/snippet-expansion.html b/doc/snippet-expansion.html
index 94e7a2c..6d346f6 100644
--- a/doc/snippet-expansion.html
+++ b/doc/snippet-expansion.html
@@ -20,16 +20,19 @@
     </div>
     <ul class="primary-links">
       <li>
-        <a title="" href="index.html">Home</a>
+        <a title="" href="index.html">Intro and tutorial</a>
       </li>
       <li>
-        <a title="" href="snippet-organization.html">Organize</a>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
       </li>
       <li>
-        <a title="" href="snippet-expansion.html">Expand</a>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
       </li>
       <li>
-        <a title="" href="snippet-development.html">Write</a>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
       </li>
       <li>
         <a title="" href="faq.html">FAQ</a>
diff --git a/doc/snippet-menu.html b/doc/snippet-menu.html
new file mode 100644
index 0000000..32b0bdb
--- /dev/null
+++ b/doc/snippet-menu.html
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
+<title>The menu</title>
+<meta name="author" content="pluskid, joaotavora" />
+<meta name="date" content="2009-08-18" />
+<link rel="stylesheet" href="styles.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="the-menu">
+<div id="header-region" class="clear-block"></div>
+<div id="wrapper">
+  <div id="container" class="clear-block">
+    <div id="header">
+    <div id="logo-floater">
+    <h1 class="title">The menu</h1>
+    </div>
+    <ul class="primary-links">
+      <li>
+        <a title="" href="index.html">Intro and tutorial</a>
+      </li>
+      <li>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
+      </li>
+      <li>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
+      </li>
+      <li>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
+      </li>
+      <li>
+        <a title="" href="faq.html">FAQ</a>
+      </li>
+      <li>
+        <a title="" href="changelog.html">ChangeLog</a>
+      </li>
+      <li>
+        <a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
+      </li>
+    </ul>
+    </div>
+    <div id="center">
+      <div id="squeeze">
+        <div class="right-corner">
+          <div class="left-corner">
+	  <p>YASnippet will setup a menu just after the <em>Buffers</em> Menu in the
+menubar. The snippets for all <em>real</em> modes are listed there under the
+menu. You can select a snippet from the menu to expand it. Since you
+select manually from the menu, you can expand any snippet. For
+example, you can expand a snippet defined for <tt class="docutils literal"><span class="pre">python-mode</span></tt> in a
+<tt class="docutils literal"><span class="pre">c-mode</span></tt> buffer by selecting it from the menu:</p>
+<img align="right" alt="images/menubar.png" class="align-right" src="images/menubar.png" />
+<ul class="simple">
+<li>Condition system is ignored since you select to expand it
+explicitly.</li>
+<li>There will be no muliple candidates since they are listed in the
+menu as different items.</li>
+</ul>
+<p>This can be convenient sometimes. However, if you don't like the
+menubar of Emacs and never use it. You can tell YASnippet don't boring
+to build a menu by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to nil.</p>
+<p>Another thing to note is that only <em>real</em> modes are listed under the
+menu. As you know, common snippets can be shared by making up a
+<em>virtual</em> parent mode. It's too bad if the menu is floored by those
+<em>virtual</em> modes. So YASnippet only show menus for those <em>real</em>
+modes. But the snippets fo the <em>virtual</em> modes can still be accessed
+through the <tt class="docutils literal"><span class="pre">parent</span></tt> submenu of some <em>real</em> mode.</p>
+<p>YASnippet use a simple way to check whether a mode is <em>real</em> or
+<em>virtual</em>: <tt class="docutils literal"><span class="pre">(fboundp</span> <span class="pre">mode)</span></tt>. For example, the symbol <tt class="docutils literal"><span class="pre">c-mode</span></tt> is
+bound to a function while <tt class="docutils literal"><span class="pre">cc-mode</span></tt> is not. But this is not enough,
+some modes aren't part of Emacs, and maybe when initializing
+YASnippet, those modes haven't been initialized. So YASnippet also
+maintain a list of known modes (<tt class="docutils literal"><span class="pre">yas/known-modes</span></tt>). You can add item
+to that list if you need.</p>
+	  </div>
+	</div>
+      </div>
+    </div>
+  </div>
+</div>
+</div>
+</body>
+</html>
diff --git a/doc/snippet-organization.html b/doc/snippet-organization.html
index 758f550..924a18f 100644
--- a/doc/snippet-organization.html
+++ b/doc/snippet-organization.html
@@ -20,16 +20,19 @@
     </div>
     <ul class="primary-links">
       <li>
-        <a title="" href="index.html">Home</a>
+        <a title="" href="index.html">Intro and tutorial</a>
       </li>
       <li>
-        <a title="" href="snippet-organization.html">Organize</a>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
       </li>
       <li>
-        <a title="" href="snippet-expansion.html">Expand</a>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
       </li>
       <li>
-        <a title="" href="snippet-development.html">Write</a>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
       </li>
       <li>
         <a title="" href="faq.html">FAQ</a>
@@ -49,270 +52,179 @@
 	  <div class="contents topic" id="contents">
 <p class="topic-title first">Contents</p>
 <ul class="simple">
-<li><a class="reference internal" href="#new-style-storage-recommended" id="id1">New-style storage (recommended)</a></li>
-<li><a class="reference internal" href="#old-style-storage-pre-0-6" id="id2">Old-style storage (pre 0.6)</a></li>
-<li><a class="reference internal" href="#no-storage-bundle" id="id3">No storage (bundle)</a></li>
-<li><a class="reference internal" href="#define-snippets-in-files" id="id4">Define snippets in files</a><ul>
-<li><a class="reference internal" href="#directory-hierarchy" id="id5">Directory hierarchy</a></li>
-<li><a class="reference internal" href="#define-snippets-using-elisp-code" id="id6">Define snippets using elisp code</a><ul>
-<li><a class="reference internal" href="#yas-define-snippets" id="id7">yas/define-snippets</a></li>
-<li><a class="reference internal" href="#yas-define" id="id8">yas/define</a></li>
-<li><a class="reference internal" href="#yas-compile-bundle" id="id9">yas/compile-bundle</a></li>
-<li><a class="reference internal" href="#the-menu" id="id10">The Menu</a></li>
-</ul>
-</li>
+<li><a class="reference internal" href="#loading-snippets" id="id2">Loading snippets</a></li>
+<li><a class="reference internal" href="#id1" id="id3">Organizing snippets</a><ul>
+<li><a class="reference internal" href="#nested-organization" id="id4">Nested organization</a></li>
+<li><a class="reference internal" href="#the-yas-parents-file" id="id5">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="id6">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="id7">Using plain file names</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#no-storage-bundle" id="id8">No storage (bundle)</a></li>
 </ul>
 </div>
-<p>There are three ways to keep your snippets:</p>
-<div class="section" id="new-style-storage-recommended">
-<h1><a class="toc-backref" href="#id1">New-style storage (recommended)</a></h1>
-<p>Hehe</p>
+<div class="section" id="loading-snippets">
+<h1><a class="toc-backref" href="#id2">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> (see <a class="reference internal" href="#no-storage-bundle">No storage (bundle)</a>),</p>
+<p>The non-bundle version of YASsnippet, 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>
+<p>Once these 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>
+<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>)
+
+<span style="color: #408080; font-style: italic">;; Load the snippets</span>
+(<span style="color: #19177C">yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>)
+</pre></div>
+<p>The point in using <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> (as opposed to calling
+<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> directly) is considering &quot;~/emacs.d/mysnippets&quot;
+for snippet development, so you can use commands like
+<tt class="docutils literal"><span class="pre">yas/new-snippet</span></tt> and others described <a class="reference external" href="snippet-development.html">here</a>)</p>
+<p>If you make this variable a list and store more items into it...</p>
+<div class="highlight"><pre>;; Develop in ~/emacs.d/mysnippets, but also
+;; try out snippets in ~/Downloads/interesting-snippets
+(setq yas/root-directory &#39;(&quot;~/emacs.d/mysnippets&quot;
+                           &quot;~/Downloads/interesting-snippets&quot;))
+
+;; Map `yas/load-directory&#39; to every element
+(mapc &#39;yas/load-directory yas/root-directory)
+</pre></div>
+<p>, the directories after the first are loaded, their snippets
+considered for expansion, but development still happens in
+&quot;~/emacs.d/mysnippets&quot;</p>
+</div>
+<div class="section" id="id1">
+<h1><a class="toc-backref" href="#id3">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 subdirectories of these directories.</p>
+<p>Common to <em>both</em> cases, snippet definitions are put in plain text
+files. They are arranged by subdirectories, and the name of these
+directories correspond 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> subdirectory. You can also skip snippet storage altogether
+and use the bundle (see <a class="reference internal" href="#no-storage-bundle">No storage (bundle)</a>).</p>
+<div class="section" id="nested-organization">
+<h2><a class="toc-backref" href="#id4">Nested organization</a></h2>
+<p>Here is an excerpt of a directory hierarchy containing snippets
+for some modes:</p>
+<div class="highlight"><pre>$ tree
+.
+`-- text-mode
+    |-- cc-mode
+    |   |-- c-mode
+    |   |   `-- printf
+    |   |-- for
+    |   |-- java-mode
+    |   |   `-- println
+    |   `-- while
+    |-- email
+    |-- perl-mode
+    |   |-- cperl-mode
+    |   `-- for
+    `-- time
+</pre></div>
+<p>The parent directory acts as the <em>parent mode</em>. This is the way of
+YASnippet to 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>. 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>
+</div>
+<div class="section" id="the-yas-parents-file">
+<h2><a class="toc-backref" href="#id5">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
+subdirectories you can bypass nesting and still have parent modes. In
+this 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
+|   |-- .yas-parents    # contains &quot;cc-mode text-mode&quot;
+|   `-- printf
+|-- cc-mode
+|   |-- for
+|   `-- while
+|-- java-mode
+|   |-- .yas-parents    # contains &quot;cc-mode text-mode&quot;
+|   `-- println
+`-- text-mode
+    |-- email
+    `-- time
+</pre></div>
+</div>
+<div class="section" id="the-yas-make-groups-file">
+<h2><a class="toc-backref" href="#id6">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2>
+<img align="right" alt="images/group.png" class="align-right" src="images/group.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 subdirectories are
+considered groups of snippets and the <cite>YASsnippet menu</cite> is organized
+much more cleanly, as you can see in the image.</p>
+<p>Another alternative way to achieve this is to place a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt>
+directive inside the snippet definition. See <a class="reference external" href="snippet-development.html">Writing snippets</a></p>
+<div class="highlight"><pre>$ tree ruby-mode/
+ruby-mode/
+|-- .yas-make-groups
+|-- collections
+|   |-- each
+|   `-- ...
+|-- control structure
+|   |-- forin
+|   `-- ...
+|-- definitions
+|   `-- ...
+`-- general
+    `-- ...
+</pre></div>
+</div>
+<div class="section" id="using-plain-file-names">
+<h2><a class="toc-backref" href="#id7">Using plain file names</a></h2>
+<p>Normally, file names act as the snippet trigger <em>key</em>, see <a class="reference external" href="snippet-expansion.html">Expanding
+snippets</a>. However, if you customize the
+variable <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> to be true <em>or</em> place an
+empty file <tt class="docutils literal"><span class="pre">.yas-ignore-filename-triggers</span></tt> you can use much more
+descriptive file names. This is useful (but not mandatory) if many
+snippets within a mode share the same trigger key.</p>
+<div class="highlight"><pre>$ tree rails-mode/
+rails-mode/
+|-- .yas-make-groups
+|-- .yas-ignore-filename-triggers
+|-- Insert ERb&#39;s &lt;% __ %&gt; or &lt;%= __ %&gt;.yasnippet
+|-- asserts
+|   |-- assert(var = assigns(%3Avar)).yasnippet
+|   |-- assert_difference.yasnippet
+|   |-- assert_no_difference.yasnippet
+|   |-- assert_redirected_to (nested path plural).yasnippet
+|   |-- assert_redirected_to (nested path).yasnippet
+|   |-- assert_redirected_to (path plural).yasnippet
+|   |-- assert_redirected_to (path).yasnippet
+|   |-- assert_rjs.yasnippet
+|   `-- assert_select.yasnippet
+</pre></div>
 </div>
-<div class="section" id="old-style-storage-pre-0-6">
-<h1><a class="toc-backref" href="#id2">Old-style storage (pre 0.6)</a></h1>
-<p>Blabla</p>
 </div>
 <div class="section" id="no-storage-bundle">
-<h1><a class="toc-backref" href="#id3">No storage (bundle)</a></h1>
+<h1><a class="toc-backref" href="#id8">No storage (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>
 <p>However, this might slow down the Emacs startup speed if you have many
 snippets. You can use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to define a bunch of
-snippets for a perticular mode. But this is hard to maintain! So,
-there's a better way: define your snippets in directory and use
-<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> to compile it into a bundle file when you
-modified your snippets.</p>
+snippets for a particular mode in an emacs-lisp file.</p>
+<p>Since this is hard to maintain, there's a better way: define your
+snippets in directory and then call <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/compile-bundle</span></tt> to
+compile it into a bundle file when you modified your snippets.</p>
 <p>The release bundle of YASnippet is produced by
-<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>. The bundle use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to
-define snippets. This avoid the IO and parsing overhead when loading
+<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>. The bundle uses <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to
+define snippets. This avoids the IO and parsing overhead when loading
 snippets.</p>
-<p>Finally, you can use <tt class="docutils literal"><span class="pre">yas/define</span></tt> to define a single snippet at your
-convenience. I ofthen use this to do some testing.</p>
-</div>
-<div class="section" id="define-snippets-in-files">
-<h1><a class="toc-backref" href="#id4">Define snippets in files</a></h1>
-<div class="section" id="directory-hierarchy">
-<h2><a class="toc-backref" href="#id5">Directory hierarchy</a></h2>
-<p>Here's the directory hierarchy of the <tt class="docutils literal"><span class="pre">snippets</span></tt> directory comes
-with YASnippet:</p>
-<div class="highlight"><pre>snippets
-`-- text-mode/
-    |-- cc-mode/
-    |   |-- c++-mode/
-    |   |   |-- beginend
-    |   |   |-- class
-    |   |   `-- using
-    |   |-- c-mode/
-    |   |   `-- fopen
-    |   |-- do
-    |   |-- for
-    |   |-- if
-    |   |-- inc
-    |   |-- inc.1
-    |   |-- main
-    |   |-- once
-    |   `-- struct
-    |-- css-mode/
-    |   |-- background
-    |   |-- background.1
-    |   `-- border
-    |-- email
-    |-- html-mode/
-    |   |-- div
-    |   |-- doctype
-    |   |-- doctype.xhml1
-    |   |-- doctype.xhtml1_1
-    |   |-- doctype.xhtml1_strict
-    |   `-- doctype.xhtml1_transitional
-    |-- objc-mode/
-    |   `-- prop
-    |-- perl-mode/
-    |   |-- cperl-mode/
-    |   |-- eval
-    |   |-- for
-    |   |-- fore
-    |   |-- if
-    |   |-- ife
-    |   |-- ifee
-    |   |-- sub
-    |   |-- unless
-    |   |-- while
-    |   |-- xfore
-    |   |-- xif
-    |   |-- xunless
-    |   `-- xwhile
-    |-- python-mode/
-    |   |-- __
-    |   |-- class
-    |   |-- def
-    |   |-- for
-    |   |-- ifmain
-    |   `-- while
-    |-- rst-mode/
-    |   |-- chapter
-    |   |-- section
-    |   `-- title
-    |-- ruby-mode/
-    |   |-- #
-    |   |-- =b
-    |   |-- Comp
-    |   |-- all
-    |   |-- am
-    |   |-- any
-    |   |-- app
-    |   |-- bm
-    |   |-- case
-    |   |-- cla
-    |   |-- classify
-    |   |-- cls
-    |   |-- collect
-    |   |-- dee
-    |   |-- deli
-    |   |-- det
-    |   |-- ea
-    |   |-- eac
-    |   |-- eai
-    |   |-- eav
-    |   |-- eawi
-    |   |-- forin
-    |   |-- if
-    |   |-- ife
-    |   |-- inject
-    |   |-- mm
-    |   |-- r
-    |   |-- rb
-    |   |-- reject
-    |   |-- req
-    |   |-- rreq
-    |   |-- rw
-    |   |-- select
-    |   |-- w
-    |   |-- y
-    |   `-- zip
-    `-- time
-</pre></div>
-<p>Snippet definitions are put in plain text files. They are arranged by
-subdirectories. 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> directory.</p>
-<p>The parent directory acts as the <em>parent mode</em>. This is the way of
-YASnippet to 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">c++-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>. 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>
-<p>File names act as the snippet trigger key. Note files starting with a
-dot (<tt class="docutils literal"><span class="pre">.</span></tt>) are ignored.</p>
-</div>
-<div class="section" id="define-snippets-using-elisp-code">
-<h2><a class="toc-backref" href="#id6">Define snippets using elisp code</a></h2>
-<p>As I mentioned above, you can define snippets directly by writing
-elisp code.</p>
-<div class="section" id="yas-define-snippets">
-<h3><a class="toc-backref" href="#id7">yas/define-snippets</a></h3>
-<p>The basic syntax of <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> is</p>
-<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">MODE</span> <span style="color: #19177C">SNIPPETS</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">PARENT</span>)
-</pre></div>
-<p>The parameters are self-descriptive. If you specify a <tt class="docutils literal"><span class="pre">PARENT</span></tt>, then
-the snippets of the parents may be shared by <tt class="docutils literal"><span class="pre">MODE</span></tt>. Note if you use
-this function several times, the later specified <tt class="docutils literal"><span class="pre">PARENT</span></tt> will
-overwrite the original one. However, not specifying a <tt class="docutils literal"><span class="pre">PARENT</span></tt> won't
-erase the original parent.</p>
-<p>The <tt class="docutils literal"><span class="pre">SNIPPETS</span></tt> parameter is a list of snippet definitions. Each
-element should have the following form:</p>
-<div class="highlight"><pre>(<span style="color: #19177C">KEY</span> <span style="color: #19177C">TEMPLATE</span> <span style="color: #19177C">NAME</span> <span style="color: #19177C">CONDITION</span> <span style="color: #19177C">GROUP</span>)
-</pre></div>
-<p>The <tt class="docutils literal"><span class="pre">NAME</span></tt>, <tt class="docutils literal"><span class="pre">CONDITION</span></tt> and <tt class="docutils literal"><span class="pre">GROUP</span></tt> can be omitted if you don't
-want to provide one. Here's an example:</p>
-<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">&#39;c++-mode</span>
-<span style="color: #666666">&#39;</span>(
-  (<span style="color: #BA2121">&quot;using&quot;</span> <span style="color: #BA2121">&quot;using namespace ${std};</span>
-<span style="color: #BA2121">$0&quot;</span> <span style="color: #BA2121">&quot;using namespace ... &quot;</span> <span style="color: #880000">nil</span>)
-  (<span style="color: #BA2121">&quot;class&quot;</span> <span style="color: #BA2121">&quot;class ${1:Name}</span>
-<span style="color: #BA2121">{</span>
-<span style="color: #BA2121">public:</span>
-<span style="color: #BA2121">    $1($2);</span>
-<span style="color: #BA2121">    virtual ~$1();</span>
-<span style="color: #BA2121">};&quot;</span> <span style="color: #BA2121">&quot;class ... { ... }&quot;</span> <span style="color: #880000">nil</span>)
-  (<span style="color: #BA2121">&quot;beginend&quot;</span> <span style="color: #BA2121">&quot;${1:v}.begin(), $1.end&quot;</span> <span style="color: #BA2121">&quot;v.begin(), v.end()&quot;</span> <span style="color: #880000">nil</span>)
-  )
-<span style="color: #19177C">&#39;cc-mode</span>)
-</pre></div>
-<p>The example above is auto-generated code by <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>.</p>
-</div>
-<div class="section" id="yas-define">
-<h3><a class="toc-backref" href="#id8">yas/define</a></h3>
-<p>The basic syntax for <tt class="docutils literal"><span class="pre">yas/define</span></tt> is</p>
-<div class="highlight"><pre>(<span style="color: #19177C">yas/define</span> <span style="color: #19177C">mode</span> <span style="color: #19177C">key</span> <span style="color: #19177C">template</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">name</span> <span style="color: #B00040">condition</span> <span style="color: #19177C">group</span>)
-</pre></div>
-<p>This is only a syntax sugar for</p>
-<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">mode</span>
-                     (<span style="color: #008000">list</span> (<span style="color: #008000">list</span> <span style="color: #19177C">key</span> <span style="color: #19177C">template</span> <span style="color: #19177C">name</span> <span style="color: #B00040">condition</span> <span style="color: #19177C">group</span>)))
-</pre></div>
-</div>
-<div class="section" id="yas-compile-bundle">
-<h3><a class="toc-backref" href="#id9">yas/compile-bundle</a></h3>
-<p><tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> can be used to parse the snippets from a
-directory hierarchy and translate them into the elisp form. The
-translated code is faster to load. Further more, the generated bundle
-is a stand-alone file not depending on <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt>. The released
-bundles of YASnippet are all generated this way.</p>
-</div>
-<div class="section" id="the-menu">
-<h3><a class="toc-backref" href="#id10">The Menu</a></h3>
-<p>YASnippet will setup a menu just after the <em>Buffers</em> Menu in the
-menubar. The snippets for all <em>real</em> modes are listed there under the
-menu. You can select a snippet from the menu to expand it. Since you
-select manually from the menu, you can expand any snippet. For
-example, you can expand a snippet defined for <tt class="docutils literal"><span class="pre">python-mode</span></tt> in a
-<tt class="docutils literal"><span class="pre">c-mode</span></tt> buffer by selecting it from the menu:</p>
-<img align="right" alt="images/menubar.png" class="align-right" src="images/menubar.png" />
-<ul class="simple">
-<li>Condition system is ignored since you select to expand it
-explicitly.</li>
-<li>There will be no muliple candidates since they are listed in the
-menu as different items.</li>
-</ul>
-<p>This can be convenient sometimes. However, if you don't like the
-menubar of Emacs and never use it. You can tell YASnippet don't boring
-to build a menu by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to nil.</p>
-<p>Another thing to note is that only <em>real</em> modes are listed under the
-menu. As you know, common snippets can be shared by making up a
-<em>virtual</em> parent mode. It's too bad if the menu is floored by those
-<em>virtual</em> modes. So YASnippet only show menus for those <em>real</em>
-modes. But the snippets fo the <em>virtual</em> modes can still be accessed
-through the <tt class="docutils literal"><span class="pre">parent</span></tt> submenu of some <em>real</em> mode.</p>
-<p>YASnippet use a simple way to check whether a mode is <em>real</em> or
-<em>virtual</em>: <tt class="docutils literal"><span class="pre">(fboundp</span> <span class="pre">mode)</span></tt>. For example, the symbol <tt class="docutils literal"><span class="pre">c-mode</span></tt> is
-bound to a function while <tt class="docutils literal"><span class="pre">cc-mode</span></tt> is not. But this is not enough,
-some modes aren't part of Emacs, and maybe when initializing
-YASnippet, those modes haven't been initialized. So YASnippet also
-maintain a list of known modes (<tt class="docutils literal"><span class="pre">yas/known-modes</span></tt>). You can add item
-to that list if you need.</p>
-<p>The basic syntax of <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> is</p>
-<div class="highlight"><pre>(<span style="color: #19177C">yas/compile-bundle</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">yasnippet</span> <span style="color: #19177C">yasnippet-bundle</span> <span style="color: #19177C">snippet-roots</span> <span style="color: #19177C">code</span> <span style="color: #19177C">dropdown</span>)
-</pre></div>
-<p>As you can see, all the parameters are optional. The default values
-for those parameters are convenient for me to produce the default
-release bundle:</p>
-<div class="highlight"><pre>(<span style="color: #19177C">yas/compile-bundle</span> <span style="color: #BA2121">&quot;yasnippet.el&quot;</span>
-                    <span style="color: #BA2121">&quot;./yasnippet-bundle.el&quot;</span>
-                    <span style="color: #666666">&#39;</span>(<span style="color: #BA2121">&quot;snippets&quot;</span>)
-                    <span style="color: #BA2121">&quot;(yas/initialize)&quot;</span>
-                    <span style="color: #BA2121">&quot;dropdown-list.el&quot;</span>)
-</pre></div>
-<p>The <tt class="docutils literal"><span class="pre">snippet-roots</span></tt> can be a list of root directories. This is
-useful when you have multiple snippet directories (maybe from other
-users). The <tt class="docutils literal"><span class="pre">code</span></tt> parameter can be used to specify your own
-customization code instead of the default <tt class="docutils literal"><span class="pre">(yas/initialize)</span></tt>. For
-example, you can set <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to <tt class="docutils literal"><span class="pre">(kbd</span> <span class="pre">&quot;SPC&quot;)</span></tt> here if
-you like.</p>
-<p>From release 0.6 you have to specify the <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> file if
-you want it to be a part of the generated bundle.</p>
-</div>
-</div>
+<p>Further more, the generated bundle is a stand-alone file not depending
+on <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt>. The released bundles of YASnippet are all
+generated this way.</p>
+<p>See the internal documentation for the functions
+<tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> and <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>.</p>
 </div>
 	  </div>
 	</div>
diff --git a/doc/snippet-organization.rst b/doc/snippet-organization.rst
index a27e456..c4e5367 100644
--- a/doc/snippet-organization.rst
+++ b/doc/snippet-organization.rst
@@ -8,300 +8,205 @@ Organizing snippets
 
 .. contents::
 
-There are three ways to keep your 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>`_ (see `No storage (bundle)`_),
+
+The non-bundle version of YASsnippet, 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.
+
+Once these are in place reference them in the variable
+``yas/root-directory`` and then load them with ``yas/load-directory``:
+
+.. sourcecode:: common-lisp
+
+  ;; Develop and keep personal snippets under ~/emacs.d/mysnippets
+  (setq yas/root-directory "~/emacs.d/mysnippets")
+
+  ;; Load the snippets
+  (yas/load-directory yas/root-directory)
+
+The point in using ``yas/root-directory`` (as opposed to calling
+``yas/load-directory`` directly) is considering "~/emacs.d/mysnippets"
+for snippet development, so you can use commands like
+``yas/new-snippet`` and others described `here
+<snippet-development.html>`_)
+
+If you make this variable a list and store more items into it...
+
+.. sourcecode:: common-lisp
+   :align: right
+
+  ;; Develop in ~/emacs.d/mysnippets, but also
+  ;; try out snippets in ~/Downloads/interesting-snippets
+  (setq yas/root-directory '("~/emacs.d/mysnippets"
+                             "~/Downloads/interesting-snippets"))
+
+  ;; Map `yas/load-directory' to every element
+  (mapc 'yas/load-directory yas/root-directory)
+
+, the directories after the first are loaded, their snippets
+considered for expansion, but development still happens in
+"~/emacs.d/mysnippets"
+
+Organizing snippets
+===================
+
+Once you've setup ``yas/root-directory`` , you can store snippets
+inside subdirectories of these directories.
+
+Common to *both* cases, snippet definitions are put in plain text
+files. They are arranged by subdirectories, and the name of these
+directories correspond to the Emacs mode where you want expansion to
+take place. For example, snippets for ``c-mode`` are put in the
+``c-mode`` subdirectory. You can also skip snippet storage altogether
+and use the bundle (see `No storage (bundle)`_).
+
+Nested organization
+-------------------
+
+Here is an excerpt of a directory hierarchy containing snippets
+for some modes:
+
+.. sourcecode:: text
+
+  $ tree
+  .
+  `-- text-mode
+      |-- cc-mode
+      |   |-- c-mode
+      |   |   `-- printf
+      |   |-- for
+      |   |-- java-mode
+      |   |   `-- println
+      |   `-- while
+      |-- email
+      |-- perl-mode
+      |   |-- cperl-mode
+      |   `-- for
+      `-- time
+
+The parent directory acts as the *parent mode*. This is the way of
+YASnippet to 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``. This can
+be also used to as an *alias* -- ``cperl-mode`` is an empty directory
+whose parent is ``perl-mode``.
+
+The ``.yas-parents`` file
+------------------------------
+
+If you place a plain text file ``.yas-parents`` inside one of the
+subdirectories you can bypass nesting and still have parent modes. In
+this file you just write whitespace-separated names of modes. This
+allows more flexibility and readability of your snippet hierarchy.
+
+.. sourcecode:: text
+
+  $ tree
+  .
+  |-- c-mode
+  |   |-- .yas-parents    # contains "cc-mode text-mode" 
+  |   `-- printf
+  |-- cc-mode
+  |   |-- for
+  |   `-- while
+  |-- java-mode
+  |   |-- .yas-parents    # contains "cc-mode text-mode"
+  |   `-- println
+  `-- text-mode
+      |-- email
+      `-- time
+
+The ``.yas-make-groups`` file
+-----------------------------
+
+.. image:: images/group.png
+   :align: right
+
+If you place an empty plain text file ``.yas-make-groups`` inside one
+of the mode directories, the names of these subdirectories are
+considered groups of snippets and the `YASsnippet menu` is organized
+much more cleanly, as you can see in the image.
+
+Another alternative way to achieve this is to place a ``# group:``
+directive inside the snippet definition. See `Writing snippets
+<snippet-development.html>`_
+
+.. sourcecode:: text
+
+  $ tree ruby-mode/
+  ruby-mode/
+  |-- .yas-make-groups
+  |-- collections
+  |   |-- each
+  |   `-- ...
+  |-- control structure
+  |   |-- forin
+  |   `-- ...
+  |-- definitions
+  |   `-- ...
+  `-- general
+      `-- ...
 
 
-New-style storage (recommended)
-===============================
+Using plain file names
+----------------------
 
-Hehe
+Normally, file names act as the snippet trigger *key*, see `Expanding
+snippets <snippet-expansion.html>`_. However, if you customize the
+variable ``yas/ignore-filenames-as-triggers`` to be true *or* place an
+empty file ``.yas-ignore-filename-triggers`` you can use much more
+descriptive file names. This is useful (but not mandatory) if many
+snippets within a mode share the same trigger key.
+
+.. sourcecode:: text
+
+  $ tree rails-mode/
+  rails-mode/
+  |-- .yas-make-groups
+  |-- .yas-ignore-filename-triggers
+  |-- Insert ERb's <% __ %> or <%= __ %>.yasnippet
+  |-- asserts
+  |   |-- assert(var = assigns(%3Avar)).yasnippet
+  |   |-- assert_difference.yasnippet
+  |   |-- assert_no_difference.yasnippet
+  |   |-- assert_redirected_to (nested path plural).yasnippet
+  |   |-- assert_redirected_to (nested path).yasnippet
+  |   |-- assert_redirected_to (path plural).yasnippet
+  |   |-- assert_redirected_to (path).yasnippet
+  |   |-- assert_rjs.yasnippet
+  |   `-- assert_select.yasnippet
 
-Old-style storage (pre 0.6)
-===========================
 
-Blabla
 
 No storage (bundle)
 ===================
 
 The most convenient way to define snippets for YASnippet is to put
 them in a directory arranged by the mode and use
-``yas/load-directory`` to load them. 
+``yas/load-directory`` to load them.
 
 However, this might slow down the Emacs startup speed if you have many
 snippets. You can use ``yas/define-snippets`` to define a bunch of
-snippets for a perticular mode. But this is hard to maintain! So,
-there's a better way: define your snippets in directory and use
-``yas/compile-bundle`` to compile it into a bundle file when you
-modified your snippets.
+snippets for a particular mode in an emacs-lisp file.
+
+Since this is hard to maintain, there's a better way: define your
+snippets in directory and then call ``M-x yas/compile-bundle`` to
+compile it into a bundle file when you modified your snippets.
 
 The release bundle of YASnippet is produced by
-``yas/compile-bundle``. The bundle use ``yas/define-snippets`` to
-define snippets. This avoid the IO and parsing overhead when loading
+``yas/compile-bundle``. The bundle uses ``yas/define-snippets`` to
+define snippets. This avoids the IO and parsing overhead when loading
 snippets.
 
-Finally, you can use ``yas/define`` to define a single snippet at your
-convenience. I ofthen use this to do some testing.
+Further more, the generated bundle is a stand-alone file not depending
+on ``yasnippet.el``. The released bundles of YASnippet are all
+generated this way.
 
-Define snippets in files
-========================
-
-Directory hierarchy
--------------------
-
-Here's the directory hierarchy of the ``snippets`` directory comes
-with YASnippet:
-
-.. sourcecode:: text
-
-  snippets
-  `-- text-mode/
-      |-- cc-mode/
-      |   |-- c++-mode/
-      |   |   |-- beginend
-      |   |   |-- class
-      |   |   `-- using
-      |   |-- c-mode/
-      |   |   `-- fopen
-      |   |-- do
-      |   |-- for
-      |   |-- if
-      |   |-- inc
-      |   |-- inc.1
-      |   |-- main
-      |   |-- once
-      |   `-- struct
-      |-- css-mode/
-      |   |-- background
-      |   |-- background.1
-      |   `-- border
-      |-- email
-      |-- html-mode/
-      |   |-- div
-      |   |-- doctype
-      |   |-- doctype.xhml1
-      |   |-- doctype.xhtml1_1
-      |   |-- doctype.xhtml1_strict
-      |   `-- doctype.xhtml1_transitional
-      |-- objc-mode/
-      |   `-- prop
-      |-- perl-mode/
-      |   |-- cperl-mode/
-      |   |-- eval
-      |   |-- for
-      |   |-- fore
-      |   |-- if
-      |   |-- ife
-      |   |-- ifee
-      |   |-- sub
-      |   |-- unless
-      |   |-- while
-      |   |-- xfore
-      |   |-- xif
-      |   |-- xunless
-      |   `-- xwhile
-      |-- python-mode/
-      |   |-- __
-      |   |-- class
-      |   |-- def
-      |   |-- for
-      |   |-- ifmain
-      |   `-- while
-      |-- rst-mode/
-      |   |-- chapter
-      |   |-- section
-      |   `-- title
-      |-- ruby-mode/
-      |   |-- #
-      |   |-- =b
-      |   |-- Comp
-      |   |-- all
-      |   |-- am
-      |   |-- any
-      |   |-- app
-      |   |-- bm
-      |   |-- case
-      |   |-- cla
-      |   |-- classify
-      |   |-- cls
-      |   |-- collect
-      |   |-- dee
-      |   |-- deli
-      |   |-- det
-      |   |-- ea
-      |   |-- eac
-      |   |-- eai
-      |   |-- eav
-      |   |-- eawi
-      |   |-- forin
-      |   |-- if
-      |   |-- ife
-      |   |-- inject
-      |   |-- mm
-      |   |-- r
-      |   |-- rb
-      |   |-- reject
-      |   |-- req
-      |   |-- rreq
-      |   |-- rw
-      |   |-- select
-      |   |-- w
-      |   |-- y
-      |   `-- zip
-      `-- time
-
-Snippet definitions are put in plain text files. They are arranged by
-subdirectories. For example, snippets for ``c-mode`` are put in the
-``c-mode`` directory.
-
-The parent directory acts as the *parent mode*. This is the way of
-YASnippet to share snippet definitions among different modes. As you
-can see above, ``c-mode`` and ``c++-mode`` share the same parents
-``cc-mode``, while all modes are derived from ``text-mode``. This can
-be also used to as an *alias* -- ``cperl-mode`` is an empty directory
-whose parent is ``perl-mode``.
-
-File names act as the snippet trigger key. Note files starting with a
-dot (``.``) are ignored.
-
-Define snippets using elisp code
---------------------------------
-
-As I mentioned above, you can define snippets directly by writing
-elisp code.
-
-yas/define-snippets
-~~~~~~~~~~~~~~~~~~~
-
-The basic syntax of ``yas/define-snippets`` is
-
-.. sourcecode:: common-lisp
-
-  (yas/define-snippets MODE SNIPPETS &optional PARENT)
-
-The parameters are self-descriptive. If you specify a ``PARENT``, then
-the snippets of the parents may be shared by ``MODE``. Note if you use
-this function several times, the later specified ``PARENT`` will
-overwrite the original one. However, not specifying a ``PARENT`` won't
-erase the original parent.
-
-The ``SNIPPETS`` parameter is a list of snippet definitions. Each
-element should have the following form:
-
-.. sourcecode:: common-lisp
-
-  (KEY TEMPLATE NAME CONDITION GROUP)
-
-The ``NAME``, ``CONDITION`` and ``GROUP`` can be omitted if you don't
-want to provide one. Here's an example:
-
-.. sourcecode:: common-lisp
-
-  (yas/define-snippets 'c++-mode
-  '(
-    ("using" "using namespace ${std};
-  $0" "using namespace ... " nil)
-    ("class" "class ${1:Name}
-  {
-  public:
-      $1($2);
-      virtual ~$1();
-  };" "class ... { ... }" nil)
-    ("beginend" "${1:v}.begin(), $1.end" "v.begin(), v.end()" nil)
-    )
-  'cc-mode)
-
-The example above is auto-generated code by ``yas/compile-bundle``.
-
-
-yas/define
-~~~~~~~~~~
-
-The basic syntax for ``yas/define`` is
-
-.. sourcecode:: common-lisp
-
-  (yas/define mode key template &optional name condition group)
-
-This is only a syntax sugar for
-
-.. sourcecode:: common-lisp
-
-  (yas/define-snippets mode
-                       (list (list key template name condition group)))
-
-yas/compile-bundle
-~~~~~~~~~~~~~~~~~~
-
-``yas/compile-bundle`` can be used to parse the snippets from a
-directory hierarchy and translate them into the elisp form. The
-translated code is faster to load. Further more, the generated bundle
-is a stand-alone file not depending on ``yasnippet.el``. The released
-bundles of YASnippet are all generated this way.
-
-
-
-The Menu
-~~~~~~~~
-
-YASnippet will setup a menu just after the *Buffers* Menu in the
-menubar. The snippets for all *real* modes are listed there under the
-menu. You can select a snippet from the menu to expand it. Since you
-select manually from the menu, you can expand any snippet. For
-example, you can expand a snippet defined for ``python-mode`` in a
-``c-mode`` buffer by selecting it from the menu:
-
-.. image:: images/menubar.png
-   :align: right
-
-* Condition system is ignored since you select to expand it
-  explicitly.
-* There will be no muliple candidates since they are listed in the
-  menu as different items.
-
-This can be convenient sometimes. However, if you don't like the
-menubar of Emacs and never use it. You can tell YASnippet don't boring
-to build a menu by setting ``yas/use-menu`` to nil.
-
-Another thing to note is that only *real* modes are listed under the
-menu. As you know, common snippets can be shared by making up a
-*virtual* parent mode. It's too bad if the menu is floored by those
-*virtual* modes. So YASnippet only show menus for those *real*
-modes. But the snippets fo the *virtual* modes can still be accessed
-through the ``parent`` submenu of some *real* mode.
-
-YASnippet use a simple way to check whether a mode is *real* or
-*virtual*: ``(fboundp mode)``. For example, the symbol ``c-mode`` is
-bound to a function while ``cc-mode`` is not. But this is not enough,
-some modes aren't part of Emacs, and maybe when initializing
-YASnippet, those modes haven't been initialized. So YASnippet also
-maintain a list of known modes (``yas/known-modes``). You can add item
-to that list if you need.
-
-The basic syntax of ``yas/compile-bundle`` is
-
-.. sourcecode:: common-lisp
-
-  (yas/compile-bundle &optional yasnippet yasnippet-bundle snippet-roots code dropdown)
-
-As you can see, all the parameters are optional. The default values
-for those parameters are convenient for me to produce the default
-release bundle:
-
-.. sourcecode:: common-lisp
-
-  (yas/compile-bundle "yasnippet.el"
-                      "./yasnippet-bundle.el"
-                      '("snippets")
-                      "(yas/initialize)"
-		      "dropdown-list.el")
-
-The ``snippet-roots`` can be a list of root directories. This is
-useful when you have multiple snippet directories (maybe from other
-users). The ``code`` parameter can be used to specify your own
-customization code instead of the default ``(yas/initialize)``. For
-example, you can set ``yas/trigger-key`` to ``(kbd "SPC")`` here if
-you like.
-
-From release 0.6 you have to specify the ``dropdown-list.el`` file if
-you want it to be a part of the generated bundle.
+See the internal documentation for the functions
+``yas/define-snippets`` and ``yas/compile-bundle``.
diff --git a/doc/styles.css b/doc/styles.css
index fad0240..e0afa09 100644
--- a/doc/styles.css
+++ b/doc/styles.css
@@ -59,6 +59,7 @@ ul.primary-links li {
     list-style-type: none;
     float: left;
     margin: 0px;
+    font-size: 0.8em;
     padding: 0px;
 }
 ul.primary-links li a {
diff --git a/doc/template.txt b/doc/template.txt
index a99c1a4..59c3f56 100644
--- a/doc/template.txt
+++ b/doc/template.txt
@@ -11,16 +11,19 @@
     </div>
     <ul class="primary-links">
       <li>
-        <a title="" href="index.html">Home</a>
+        <a title="" href="index.html">Intro and tutorial</a>
       </li>
       <li>
-        <a title="" href="snippet-organization.html">Organize</a>
+        <a title="" href="snippet-organization.html">Howto: organize</a>
       </li>
       <li>
-        <a title="" href="snippet-expansion.html">Expand</a>
+        <a title="" href="snippet-expansion.html">Howto: expand</a>
       </li>
       <li>
-        <a title="" href="snippet-development.html">Write</a>
+        <a title="" href="snippet-development.html">Howto: write </a>
+      </li>
+      <li>
+        <a title="" href="snippet-menu.html">Howto: menu </a>
       </li>
       <li>
         <a title="" href="faq.html">FAQ</a>