ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2026-02-04 14:32:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

* proof-reading the documentation

Browse Source 
* added link to the new screencast
This commit is contained in:
capitaomorte
2009-09-24 15:59:45 +00:00
parent 5d0b9657e3
commit 037f8fd3ee
12 changed files with 361 additions and 333 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
doc/snippet-organization.html
View File

@@ -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>