incorporate old rst docs into org

This commit is contained in:
Noam Postavsky
2013-11-26 21:22:57 -05:00
parent 695211b761
commit b194ea56b3
9 changed files with 5700 additions and 3364 deletions

View File

@@ -1,171 +1,295 @@
<?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">
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>Organizing snippets</title>
<link rel="stylesheet" href="styles.css" type="text/css" />
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/>
<meta name="title" content="Organizing snippets"/>
<meta name="generator" content="Org-mode"/>
<meta name="generated" content="2013-11-26T21:02-0500"/>
<meta name="author" content=""/>
<meta name="description" content=""/>
<meta name="keywords" content=""/>
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
html { font-family: Times, serif; font-size: 12pt; }
.title { text-align: center; }
.todo { color: red; }
.done { color: green; }
.tag { background-color: #add8e6; font-weight:normal }
.target { }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.right {margin-left:auto; margin-right:0px; text-align:right;}
.left {margin-left:0px; margin-right:auto; text-align:left;}
.center {margin-left:auto; margin-right:auto; text-align:center;}
p.verse { margin-left: 3% }
pre {
border: 1pt solid #AEBDCC;
background-color: #F3F5F7;
padding: 5pt;
font-family: courier, monospace;
font-size: 90%;
overflow:auto;
}
table { border-collapse: collapse; }
td, th { vertical-align: top; }
th.right { text-align:center; }
th.left { text-align:center; }
th.center { text-align:center; }
td.right { text-align:right; }
td.left { text-align:left; }
td.center { text-align:center; }
dt { font-weight: bold; }
div.figure { padding: 0.5em; }
div.figure p { text-align: center; }
div.inlinetask {
padding:10px;
border:2px solid gray;
margin:10px;
background: #ffffcc;
}
textarea { overflow-x: auto; }
.linenr { font-size:smaller }
.code-highlighted {background-color:#ffff00;}
.org-info-js_info-navigation { border-style:none; }
#org-info-js_console-label { font-size:10px; font-weight:bold;
white-space:nowrap; }
.org-info-js_search-highlight {background-color:#ffff00; color:#000000;
font-weight:bold; }
/*]]>*/-->
</style>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2013 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
</head>
<body>
<div class="document" id="organizing-snippets">
<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">Organizing snippets</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>
<b>Important:</b> This documentation applies to
the <b>SVN trunk</b> of YASnippet, which you
get <a href="http://code.google.com/p/yasnippet/source/checkout">here</a>. Documentation
for other versions can be found <a title=""
href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
</p>
<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="id3">Loading snippets</a></li>
<li><a class="reference internal" href="#id2" id="id4">Organizing snippets</a><ul>
<li><a class="reference internal" href="#the-yas-parents-file" id="id5">The <tt class="docutils literal">.yas.parents</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>
<div id="org-div-home-and-up" style="text-align:right;font-size:70%;white-space:nowrap;">
<a accesskey="h" href="./index.html"> UP </a>
|
<a accesskey="H" href="./index.html"> HOME </a>
</div>
<div id="preamble">
</div>
<div id="content">
<h1 class="title">Organizing snippets</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">Basic structure</a></li>
<li><a href="#sec-2">Setting up <code>yas-snippet-dirs</code></a></li>
<li><a href="#sec-3">The <code>.yas-parents</code> file</a></li>
<li><a href="#sec-4">The <code>.yas-make-groups</code> file</a></li>
<li><a href="#sec-5">The <code>.yas-setup.el</code> file</a>
<ul>
<li><a href="#sec-5-1"></a></li>
</ul>
</li>
<li><a class="reference internal" href="#yasnippet-bundle" id="id7">YASnippet bundle</a></li>
<li><a class="reference internal" href="#customizable-variables" id="id8">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-snippet-dirs" id="id9"><tt class="docutils literal"><span class="pre">yas-snippet-dirs</span></tt></a></li>
<li><a class="reference internal" href="#yas-ignore-filenames-as-triggers" id="id10"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></li>
<li><a href="#sec-6">The <code>.yas-compiled-snippet.el</code> file</a>
<ul>
<li><a href="#sec-6-1"></a></li>
</ul>
</li>
<li><a href="#sec-7">The <code>.yas-skip</code> file</a>
<ul>
<li><a href="#sec-7-1"></a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="loading-snippets">
<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 more directories.</p>
<p>
Once these directories are in place reference them in the variable
<tt class="docutils literal">
<span class="pre">yas-snippet-dirs</span>
</tt>
and then load YASnippet as usual:
</p>
<div class="highlight" style="background: #f8f8f8">
<pre style="line-height: 125%"><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-snippet-dirs</span> <span style="color: #666666">&#39;</span>(<span style="color: #BA2121">&quot;~/emacs.d/mysnippets&quot;</span>))
<span style="color: #408080; font-style: italic">;; Load yasnippet</span>
(<span style="color: #19177C">yas-global-mode</span> <span style="color: #19177C">1</span>)
</pre></div>
<p>
The point in using
<tt class="docutils literal">
<span class="pre">yas-snippet-dirs</span>
</tt>
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 in section
<a class="reference external" href="snippet-development.html">Writing Snippets</a>.
</p>
</div>
<div id="outline-container-1" class="outline-2">
<h2 id="sec-1">Basic structure</h2>
<div class="outline-text-2" id="text-1">
<p>
<strong>Note:</strong> In the past,
<tt class="docutils literal">
<span class="pre">yas/root-directory</span>
</tt>
is the variable that stores the list of snippet directories. This method is
deprecated and only exists for backward-compatibility reason.
Snippet collections can be stored in plain text files. They are arranged by
sub-directories naming <b>snippet tables</b>. These mostly name Emacs major names.
</p>
<div class="section" id="id2">
<h1><a class="toc-backref" href="#id4">Organizing snippets</a></h1>
<p>Once you've setup <tt class="docutils literal"><span class="pre">yas-snippet-dirs</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 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.</p>
<div class="section" id="the-yas-parents-file">
<h2><a class="toc-backref" href="#id5">The <tt class="docutils literal">.yas.parents</tt> file</a></h2>
<p>It's very useful to have certain modes share snippets between
themselves. To do this, choose a mode subdirectory and place a
<tt class="docutils literal"><span class="pre">.yas-parents</span></tt> containing a whitespace-separated list of other
mode names. When you reload those modes become parents of the
original mode.</p>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%">$ tree
.
<pre class="example">.
|-- c-mode
| |-- .yas-parents # contains &quot;cc-mode text-mode&quot;
| `-- printf
|-- java-mode
| `-- println
`-- text-mode
|-- email
`-- time
</pre>
<p>
The collections are loaded into <b>snippet tables</b> which the
triggering mechanism (see <a href="snippet-expansion.html">Expanding Snippets</a>) looks up and
(hopefully) causes the right snippet to be expanded for you.
</p>
</div>
</div>
<div id="outline-container-2" class="outline-2">
<h2 id="sec-2">Setting up <code>yas-snippet-dirs</code></h2>
<div class="outline-text-2" id="text-2">
<p>
The emacs variable <a href="snippet-reference.html#yas-snippet-dirs"><code>yas-snippet-dirs</code></a> tells YASnippet
which collections to consider. It's used when you activate
<a href="snippet-reference.html#yas-global-mode"><code>yas-global-mode</code></a> or call
<a href="snippet-reference.html#yas-reload-all"><code>yas-reload-all</code></a> interactively.
</p>
<p>
The default considers:
</p>
<ul>
<li>a personal collection that lives in <code>~/.emacs.d/snippets</code>
</li>
<li>the bundled collection, taken as a relative path to <code>yasnippet.el</code> localtion
</li>
</ul>
<p>
When you come across other snippet collections, do the following to try them
out:
</p>
<pre class="example">;; Develop in ~/emacs.d/mysnippets, but also
;; try out snippets in ~/Downloads/interesting-snippets
(setq yas-snippet-dirs '("~/emacs.d/mysnippets"
"~/Downloads/interesting-snippets"))
;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
(setq yas-snippet-dirs (append yas-snippet-dirs
'("~/Downloads/interesting-snippets")))
</pre>
<p>
Collections appearing earlier in the list shadow snippets with same names
appearing in collections later in the list. <a href="snippet-reference.html#yas-new-snippet"><code>yas-new-snippet</code></a> always stores
snippets in the first collection.
</p>
</div>
</div>
<div id="outline-container-3" class="outline-2">
<h2 id="sec-3">The <code>.yas-parents</code> file</h2>
<div class="outline-text-2" id="text-3">
<p>
It's very useful to have certain modes share snippets between
themselves. To do this, choose a mode subdirectory and place a
<code>.yas-parents</code> containing a whitespace-separated list of other mode
names. When you reload those modes become parents of the original
mode.
</p>
<pre class="example">.
|-- c-mode
| |-- .yas-parents # contains "cc-mode text-mode"
| `-- printf
|-- cc-mode
| |-- for
| `-- while
|-- java-mode
| |-- .yas-parents # contains &quot;cc-mode text-mode&quot;
| |-- .yas-parents # contains "cc-mode text-mode"
| `-- println
`-- text-mode
|-- email
`-- time
</pre></div>
</pre>
</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 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
considered groups of snippets and <a class="reference external" href="snippet-menu.html">The YASnippet Menu</a> 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"># group:</tt>
directive inside the snippet definition. See <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p>
<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%">$ tree ruby-mode/
</div>
<div id="outline-container-4" class="outline-2">
<h2 id="sec-4"><span class="todo TODO">TODO</span> The <code>.yas-make-groups</code> file</h2>
<div class="outline-text-2" id="text-4">
<p>
If you place an empty plain text file <code>.yas-make-groups</code> inside one
of the mode directories, the names of these sub-directories are
considered groups of snippets and <a href="#snippet-menu.org">the menu</a> is organized much more
cleanly:
</p>
<p>
<img src="./images/menu-groups.png" alt="./images/menu-groups.png" />
</p>
<p>
Another way to achieve this is to place a <code># group:</code> directive
inside the snippet definition. See <a href="./snippet-development.html">Writing Snippets</a>.
</p>
<pre class="example">$ tree ruby-mode/
ruby-mode/
|-- .yas-make-groups
|-- collections
@@ -177,83 +301,76 @@ ruby-mode/
|-- definitions
| `-- ...
`-- general
`-- ...
</pre></div>
</div>
</div>
<div class="section" id="yasnippet-bundle">
<h1><a class="toc-backref" href="#id7">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>
<p>However, this might slow down the Emacs start-up 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 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 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>Further more, the generated bundle is a stand-alone file not depending
on <tt class="docutils literal">yasnippet.el</tt>. The released bundles of YASnippet are all
generated this way.</p>
<p>See the internal documentation for these functions</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-function</span> RET <span class="pre">yas/define-snippets</span> RET</tt></li>
<li><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-function</span> RET <span class="pre">yas/compile-bundle</span> RET</tt>.</li>
</ul>
</div>
<div class="section" id="customizable-variables">
<h1><a class="toc-backref" href="#id8">Customizable variables</a></h1>
<div class="section" id="yas-snippet-dirs">
`-- ...
</pre>
<h2>
<a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">yas-snippet-dirs</span></tt></a>
</h2>
<p>
List of directories that store the snippets for each major mode.
</p>
<p>
The first element of the list 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>.
Yet another way to create a nice snippet menu is to write into
<code>.yas-make-groups</code> a menu definition. TODO
</p>
</div>
</div>
<div class="section" id="yas-ignore-filenames-as-triggers">
<h2><a class="toc-backref" href="#id10"><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"># key:</tt> directive wont have a tab
trigger.</p>
<!-- LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl -->
<!-- LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el -->
<!-- LocalWords: rjs RET -->
<div id="outline-container-5" class="outline-2">
<h2 id="sec-5"><span class="todo TODO">TODO</span> The <code>.yas-setup.el</code> file</h2>
<div class="outline-text-2" id="text-5">
</div>
<div id="outline-container-5-1" class="outline-3">
<h3 id="sec-5-1"><span class="todo TODO">TODO</span></h3>
<div class="outline-text-3" id="text-5-1">
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-10536822-1");
pageTracker._trackPageview();
} catch(err) {}
</script>
<div id="outline-container-6" class="outline-2">
<h2 id="sec-6"><span class="todo TODO">TODO</span> The <code>.yas-compiled-snippet.el</code> file</h2>
<div class="outline-text-2" id="text-6">
</div>
<div id="outline-container-6-1" class="outline-3">
<h3 id="sec-6-1"><span class="todo TODO">TODO</span></h3>
<div class="outline-text-3" id="text-6-1">
</div>
</div>
</div>
<div id="outline-container-7" class="outline-2">
<h2 id="sec-7"><span class="todo TODO">TODO</span> The <code>.yas-skip</code> file</h2>
<div class="outline-text-2" id="text-7">
</div>
<div id="outline-container-7-1" class="outline-3">
<h3 id="sec-7-1"><span class="todo TODO">TODO</span></h3>
<div class="outline-text-3" id="text-7-1">
</div>
</div>
</div>
</div>
<div id="postamble">
<p class="date">Date: 2013-11-26T21:02-0500</p>
<p class="creator"><a href="http://orgmode.org">Org</a> version 7.9.3f with <a href="http://www.gnu.org/software/emacs/">Emacs</a> version 24</p>
<a href="http://validator.w3.org/check?uri=referer">Validate XHTML 1.0</a>
</div>
</body>
</html>