diff options
Diffstat (limited to 'emacs.d/lisp/yasnippet/doc')
37 files changed, 4950 insertions, 0 deletions
diff --git a/emacs.d/lisp/yasnippet/doc/changelog.html b/emacs.d/lisp/yasnippet/doc/changelog.html new file mode 100644 index 0000000..7a0f2c3 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/changelog.html @@ -0,0 +1,381 @@ +<?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>ChangeLog</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="changelog"> +<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">ChangeLog</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="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> +<li>More compliant customization group <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=94">Issue94</a>, (thanks +wyuenho).</li> +<li>Added workaround for issue 97 in the FAQ</li> +<li>Small updates to documentation.</li> +</ul> +</div> +<div class="section" id="b-2009-08-29"> +<h1>0.6.1b / 2009-08-29</h1> +<ul class="simple"> +<li>Much more powerful menu. See <a class="reference external" href="snippet-menu.html">The YASnippet menu</a>.</li> +<li>New ways to organize snippets. See <a class="reference external" href="snippet-organization.html">Organizing snippets</a>.</li> +<li>Added <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt> customization variable.</li> +<li>Renamed directive <tt class="docutils literal"><span class="pre">#</span> <span class="pre">env:</span></tt> to <tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt></li> +<li>Rewrote much of the documentation.</li> +<li>Added TextMate import tool <tt class="docutils literal"><span class="pre">textmate-import.rb</span></tt> to to svn +repository (see "extras/")</li> +<li>Added <em>experimental</em> bundle of textmate snippets +<tt class="docutils literal"><span class="pre">yasnippet-textmate-bundle.el</span></tt></li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=74">Issue 74</a> (thanks +rmartin.k...@gmail.com)</li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=80">Issues 80 through 84</a> (thanks +Moritz Bunkus)</li> +<li>Fixed many more issues...</li> +</ul> +</div> +<div class="section" id="c-2009-07-27"> +<h1>0.6.0c / 2009-07-27</h1> +<ul class="simple"> +<li>Now byte compiles correctly with no warnings.</li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=68">Issue 68</a> with +mouse-clicking alternatives in <tt class="docutils literal"><span class="pre">ido-mode</span></tt>.</li> +<li>Added <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt> customization variable.</li> +</ul> +</div> +<div class="section" id="b-2009-07-25"> +<h1>0.6.0b / 2009-07-25</h1> +<ul class="simple"> +<li>Nested placeholders of the type <tt class="docutils literal"><span class="pre"><div${1:</span> <span class="pre">id="${2:someid}"}></span> <span class="pre">$0</span></tt>.</li> +<li>More robust undo/redo support.</li> +<li>Stacked snippet expansion (<em>snippet in snippet</em>).</li> +<li>Transformation on a primary field with syntax <tt class="docutils literal"><span class="pre">${1:default$(transform)}</span></tt></li> +<li>Validations on field exit through the <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> +primary field transformation.</li> +<li>Wrapping the region in the exit marker <tt class="docutils literal"><span class="pre">$0</span></tt> of the snippet. Use +<tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt>.</li> +<li>Auto-indentation. Use <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to <tt class="docutils literal"><span class="pre">'auto</span></tt></li> +<li>Easier definition of snippets. Use <tt class="docutils literal"><span class="pre">yas/find-snippets</span></tt> or +<tt class="docutils literal"><span class="pre">yas/visit-snippet-file</span></tt>. In the new <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> use +<tt class="docutils literal"><span class="pre">yas/load-snippet-buffer</span></tt> and <tt class="docutils literal"><span class="pre">yas/tryout-snippet</span></tt>.</li> +<li>Customization group <tt class="docutils literal"><span class="pre">yasnippet</span></tt>.</li> +<li>Overriding customization variables in snippets. Use the <tt class="docutils literal"><span class="pre">env:</span> +<span class="pre">let-form</span></tt> template keyword.</li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=60">Issue 60</a></li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=65">Issue 65</a></li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=56">Issue 56</a></li> +</ul> +</div> +<div class="section" id="id1"> +<h1>0.5.10 / 2009-02-11</h1> +<ul class="simple"> +<li>Added <em>grouping</em> support so that the snippets in the menu can be +groupped together.</li> +<li>Make the bundle <a class="reference external" href="http://tromey.com/elpa/index.html">ELPA</a> +compatible.</li> +</ul> +</div> +<div class="section" id="id2"> +<h1>0.5.9 / 2009-01-21</h1> +<ul class="simple"> +<li>Fixed the bug of disabling the auto-indenting of <tt class="docutils literal"><span class="pre">cc-mode</span></tt>.</li> +</ul> +</div> +<div class="section" id="id3"> +<h1>0.5.8 / 2009-01-15</h1> +<ul class="simple"> +<li>Added a <tt class="docutils literal"><span class="pre">key</span></tt> property in snippet definition for snippet names +that are not valid path name.</li> +<li>Fixed some bugs of indenting (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=44">Issue 44</a>, <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=46">Issue +46</a>).</li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=45">Issue 45</a> by +providing a proper default value for <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt>.</li> +<li>Added helper function <tt class="docutils literal"><span class="pre">yas/substr</span></tt> for convenient mirror +transformation.</li> +<li>Make variable <tt class="docutils literal"><span class="pre">yas/registered-snippet</span></tt> properly initialized.</li> +<li>Fixed the overlay error when overlay becomes empty (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=49">Issue 49</a> and +<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=48">Issue 48</a>). This +bug has occurred and been fixed earlier, and should not have +happened if we have proper regression test.</li> +<li>Added a workaround for <tt class="docutils literal"><span class="pre">c-electric-</span></tt> serial commands (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=27">Issue 27</a>).</li> +</ul> +</div> +<div class="section" id="id4"> +<h1>0.5.7 / 2008-12-03</h1> +<ul class="simple"> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=28">Issue 28</a> of +properly clean up snippet (by joaotavora).</li> +<li>Added a new section "Field-level undo functionality" to correct +<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=33">Issue 33</a> +(by joaotavora).</li> +<li>Added some snippets from users for sql, erlang, scala, html, xml, latex, etc.</li> +<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=16">Issue 16</a> by adding +<tt class="docutils literal"><span class="pre">$></span></tt> support. Here's the <a class="reference external" href="http://pluskid.lifegoo.com/upload/project/yasnippet/doc/define_snippet.html#indenting">doc for $> indenting</a>.</li> +</ul> +</div> +<div class="section" id="id5"> +<h1>0.5.6 / 2008-08-07</h1> +<ul class="simple"> +<li>Added a buffer local variable <tt class="docutils literal"><span class="pre">yas/dont-activate</span></tt> to turn off +<tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> in some major modes. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=29">Issue 29</a>.</li> +<li>Make the environment of elisp evaluation more friendly to +<tt class="docutils literal"><span class="pre">(current-column)</span></tt>.</li> +<li>Fixed the regular expression bug in python-mode snippets.</li> +<li>Use filename or full key extension for snippet name if no <tt class="docutils literal"><span class="pre">name</span></tt> +property is defined.</li> +</ul> +</div> +<div class="section" id="id6"> +<h1>0.5.5 / 2008-05-29</h1> +<ul class="simple"> +<li>Tweak <tt class="docutils literal"><span class="pre">yas/extra-mode-hooks</span></tt> so that it can be more easily +customized.</li> +<li>Add an entry in FAQ about why <tt class="docutils literal"><span class="pre">TAB</span></tt> key doesn't work in some +modes.</li> +</ul> +</div> +<div class="section" id="id7"> +<h1>0.5.4 / 2008-05-15</h1> +<ul class="simple"> +<li>Added <tt class="docutils literal"><span class="pre">ox-mode-hook</span></tt> and <tt class="docutils literal"><span class="pre">python-mode-hook</span></tt> to +<tt class="docutils literal"><span class="pre">yas/extra-mode-hooks</span></tt> to fix the problem YASnippet is not enabled +in those modes.</li> +</ul> +</div> +<div class="section" id="id8"> +<h1>0.5.3 / 2008-05-07</h1> +<ul class="simple"> +<li>Fix indent of python-mode snippets.</li> +<li>Fix a bug of dropdown-list: conflicts with color-theme (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=23">Issue 23</a>). Thanks +Mike.</li> +<li>Fix a bug of condition system.</li> +</ul> +</div> +<div class="section" id="id9"> +<h1>0.5.2 / 2008-04-20</h1> +<ul class="simple"> +<li>Fix a bug for comparing string to symbol using <tt class="docutils literal"><span class="pre">string=</span></tt> (which +will fire an error).</li> +</ul> +</div> +<div class="section" id="id10"> +<h1>0.5.1 / 2008-04-14</h1> +<ul class="simple"> +<li>Use a beautiful css style in the document.</li> +</ul> +</div> +<div class="section" id="id11"> +<h1>0.5.0 / 2008-04-10</h1> +<ul class="simple"> +<li>Integrate with hippie-expand. Just add <tt class="docutils literal"><span class="pre">yas/hippie-try-expand</span></tt> to +<tt class="docutils literal"><span class="pre">hippie-expand-try-functions-list</span></tt>.</li> +<li>If you set <tt class="docutils literal"><span class="pre">yas/fall-back-behavior</span></tt> to <tt class="docutils literal"><span class="pre">'return-nil</span></tt>, YASnippet +will return nil when it can't find a snippet to expand.</li> +<li>Defect fix: the condition of a snippet was evaluated twice in +earlier version.</li> +<li>Deleting snippet (using <tt class="docutils literal"><span class="pre">C-w</span></tt> or <tt class="docutils literal"><span class="pre">C-k</span></tt>) won't cause serious +problem now.</li> +<li>Several complex snippet for python-mode from Yasser included in the +distribution.</li> +</ul> +</div> +<div class="section" id="id12"> +<h1>0.4.5 / 2008-04-07</h1> +<ul class="simple"> +<li>Merge the latest dropdown-list.el.</li> +<li>Add snippets for f90-mode from Li Zhu.</li> +<li>Bug fix: l-safe-expr-p: Lisp nesting exceeds <tt class="docutils literal"><span class="pre">max-lisp-eval-depth</span></tt> +error when several (more than two) snippets overlaps. Thanks +<a class="reference external" href="mailto:sunwaybupt@newsmth">sunwaybupt@newsmth</a> for reporting this bug.</li> +</ul> +</div> +<div class="section" id="id13"> +<h1>0.4.4 / 2008-03-24</h1> +<ul class="simple"> +<li>Bug fix: dropdown-list.el doesn't recognize [return] properly.</li> +</ul> +</div> +<div class="section" id="id14"> +<h1>0.4.3 / 2008-03-23</h1> +<ul class="simple"> +<li>Bug fix: failed to recognize user customized yas/trigger-key.</li> +</ul> +</div> +<div class="section" id="id15"> +<h1>0.4.2 / 2008-03-22</h1> +<ul class="simple"> +<li>Make a separate document package for release. Also make document +available online.</li> +</ul> +</div> +<div class="section" id="id16"> +<h1>0.4.1 / 2008-03-21</h1> +<ul class="simple"> +<li>Make sure <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt>'s key bindings always take priority to +other minor modes.</li> +</ul> +</div> +<div class="section" id="id17"> +<h1>0.4.0 / 2008-03-20</h1> +<ul class="simple"> +<li>Document refinement and released with YASnippet. Most of the Online +wiki document will be deprecated soon.</li> +<li>Powerful condition system added to yasnippet!</li> +<li>Incorporate <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> and make it default way for +selecting multiple candidates. Thanks to <a class="reference external" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/c869158b76addeb3/e7c6372ba457189e">Jaeyoun Chung</a>.</li> +<li>yas/before-expand-snippet-hook</li> +</ul> +</div> +<div class="section" id="id18"> +<h1>0.3.2 / 2008-03-19</h1> +<ul class="simple"> +<li>Enhancement: A better way to define minor-mode. Thanks to Kentaro +Kuribayashi. See <a class="reference external" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/65cb3b5583eda887?hl=en">this thread</a> +for more details.</li> +</ul> +</div> +<div class="section" id="id19"> +<h1>0.3.1 / 2008-03-17</h1> +<ul class="simple"> +<li>Bug fix: Emacs get confused when a field is deleted. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=10">issue 10</a>.</li> +</ul> +</div> +<div class="section" id="id20"> +<h1>0.3.0 / 2008-03-16</h1> +<ul class="simple"> +<li>Add a <tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> so that you can do something like +<tt class="docutils literal"><span class="pre">indent-region</span></tt> or <tt class="docutils literal"><span class="pre">fill-region</span></tt> after finish the snippet.</li> +<li>Use minor-mode instead of <tt class="docutils literal"><span class="pre">global-set-key</span></tt> to bind the trigger +key. Now the trigger key and fall-back behavior can be more +flexible. Not constrained to <tt class="docutils literal"><span class="pre"><tab></span></tt>. Thanks to Trey Jackson. See +this <a class="reference external" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/937f32a2a6dea4f2?hl=en">thread</a> +for more details.</li> +<li>Now user can customize the popup function for selecting multiple +candidate for the same snippet key.</li> +<li>Support <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> to be a better way to select multiple +candidate when in text mode.</li> +</ul> +</div> +<div class="section" id="id21"> +<h1>0.2.3 / 2008-03-15</h1> +<ul class="simple"> +<li>Bug in non-window (-nw) mode when there's multiple candidate to +expand. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=7">issue 7</a>.</li> +<li>Allow expanding another snippet as long as not currently inside a +field.</li> +</ul> +</div> +<div class="section" id="id22"> +<h1>0.2.2 / 2008-03-13</h1> +<ul class="simple"> +<li>Added customized face for fields and mirrors. Better in dark +background. And users can customize it.</li> +</ul> +</div> +<div class="section" id="id23"> +<h1>0.2.1 / 2008-03-10</h1> +<ul class="simple"> +<li>Fix the insert-behind problem under both Emacs 22 and Emacs 23.</li> +</ul> +</div> +<div class="section" id="id24"> +<h1>0.2.0 / 2008-03-10</h1> +<ul class="simple"> +<li>Use big keymap overlay to detect <tt class="docutils literal"><span class="pre">insert-behind</span></tt> event manually to +avoid sometimes missed hook calls. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=3">issue 3</a> for more +details.</li> +<li>Support parent snippet table. Now you can set (for example) +<tt class="docutils literal"><span class="pre">cc-mode</span></tt> as common mode for <tt class="docutils literal"><span class="pre">c++-mode</span></tt>, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and +<tt class="docutils literal"><span class="pre">java-mode</span></tt>. They'll share snippets defined for <tt class="docutils literal"><span class="pre">cc-mode</span></tt>.</li> +</ul> +</div> +<div class="section" id="id25"> +<h1>0.1.1 / 2008-03-08</h1> +<ul class="simple"> +<li>Add a rake task to upload to google code.</li> +<li>Use elisp compile-bundle function instead of python scrip</li> +</ul> +</div> +<div class="section" id="id26"> +<h1>0.1.0 / 2008-03-07</h1> +<ul class="simple"> +<li>Embedded elisp support.</li> +<li>Fields navigation support.</li> +<li>Mirror of fields support.</li> +<li>Menu-bar support.</li> +<li>Multiple snippets with same name support.</li> +<li>Popup menu for multiple snippet with same name support.</li> +<li>Transformation of fields support.</li> +<li>Load directory support.</li> +<li>Compile bundle support.</li> +</ul> +</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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/changelog.rst b/emacs.d/lisp/yasnippet/doc/changelog.rst new file mode 100644 index 0000000..3896fce --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/changelog.rst @@ -0,0 +1,319 @@ +========= +ChangeLog +========= + +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html + +0.6.1c / 2009-08-13 +=================== + +* Fixed `issues <http://code.google.com/p/yasnippet/issues>`_ 99, 98, 93, + 90, 91, 88, 87. Thanks everybody. +* More compliant customization group `Issue94 + <http://code.google.com/p/yasnippet/issues/detail?id=94>`_, (thanks + wyuenho). +* Added workaround for issue 97 in the FAQ +* Small updates to documentation. + +0.6.1b / 2009-08-29 +=================== + +* Much more powerful menu. See `The YASnippet menu`_. +* New ways to organize snippets. See `Organizing snippets`_. +* Added ``yas/also-auto-indent-first-line`` customization variable. +* Renamed directive ``# env:`` to ``# expand-env:`` +* Rewrote much of the documentation. +* Added TextMate import tool ``textmate-import.rb`` to to svn + repository (see "extras/") +* Added *experimental* bundle of textmate snippets + ``yasnippet-textmate-bundle.el`` +* Fixed `Issue 74 + <http://code.google.com/p/yasnippet/issues/detail?id=74>`_ (thanks + rmartin.k...@gmail.com) +* Fixed `Issues 80 through 84 + <http://code.google.com/p/yasnippet/issues/detail?id=80>`_ (thanks + Moritz Bunkus) +* Fixed many more issues... + + +0.6.0c / 2009-07-27 +=================== + +* Now byte compiles correctly with no warnings. +* Fixed `Issue 68 + <http://code.google.com/p/yasnippet/issues/detail?id=68>`_ with + mouse-clicking alternatives in ``ido-mode``. +* Added ``yas/also-auto-indent-first-line`` customization variable. + + +0.6.0b / 2009-07-25 +=================== + +* Nested placeholders of the type ``<div${1: id="${2:someid}"}> $0``. + +* More robust undo/redo support. + +* Stacked snippet expansion (*snippet in snippet*). + +* Transformation on a primary field with syntax ``${1:default$(transform)}`` + +* Validations on field exit through the ``yas/verify-value`` + primary field transformation. + +* Wrapping the region in the exit marker ``$0`` of the snippet. Use + ``yas/wrap-around-region``. + +* Auto-indentation. Use ``yas/indent-line`` set to ``'auto`` + +* Easier definition of snippets. Use ``yas/find-snippets`` or + ``yas/visit-snippet-file``. In the new ``snippet-mode`` use + ``yas/load-snippet-buffer`` and ``yas/tryout-snippet``. + +* Customization group ``yasnippet``. + +* Overriding customization variables in snippets. Use the ``env: + let-form`` template keyword. + +* Fixed `Issue 60 + <http://code.google.com/p/yasnippet/issues/detail?id=60>`_ +* Fixed `Issue 65 + <http://code.google.com/p/yasnippet/issues/detail?id=65>`_ +* Fixed `Issue 56 + <http://code.google.com/p/yasnippet/issues/detail?id=56>`_ + +0.5.10 / 2009-02-11 +=================== + +* Added *grouping* support so that the snippets in the menu can be + groupped together. +* Make the bundle `ELPA <http://tromey.com/elpa/index.html>`_ + compatible. + +0.5.9 / 2009-01-21 +================== + +* Fixed the bug of disabling the auto-indenting of ``cc-mode``. + +0.5.8 / 2009-01-15 +================== + +* Added a ``key`` property in snippet definition for snippet names + that are not valid path name. +* Fixed some bugs of indenting (`Issue 44 + <http://code.google.com/p/yasnippet/issues/detail?id=44>`_, `Issue + 46 <http://code.google.com/p/yasnippet/issues/detail?id=46>`_). +* Fixed `Issue 45 + <http://code.google.com/p/yasnippet/issues/detail?id=45>`_ by + providing a proper default value for ``yas/buffer-local-condition``. +* Added helper function ``yas/substr`` for convenient mirror + transformation. +* Make variable ``yas/registered-snippet`` properly initialized. +* Fixed the overlay error when overlay becomes empty (`Issue 49 + <http://code.google.com/p/yasnippet/issues/detail?id=49>`_ and + `Issue 48 + <http://code.google.com/p/yasnippet/issues/detail?id=48>`_). This + bug has occurred and been fixed earlier, and should not have + happened if we have proper regression test. +* Added a workaround for ``c-electric-`` serial commands (`Issue 27 + <http://code.google.com/p/yasnippet/issues/detail?id=27>`_). + +0.5.7 / 2008-12-03 +================== + +* Fixed `Issue 28 + <http://code.google.com/p/yasnippet/issues/detail?id=28>`_ of + properly clean up snippet (by joaotavora). +* Added a new section "Field-level undo functionality" to correct + `Issue 33 <http://code.google.com/p/yasnippet/issues/detail?id=33>`_ + (by joaotavora). +* Added some snippets from users for sql, erlang, scala, html, xml, latex, etc. +* Fixed `Issue 16 + <http://code.google.com/p/yasnippet/issues/detail?id=16>`_ by adding + ``$>`` support. Here's the `doc for $> indenting + <http://pluskid.lifegoo.com/upload/project/yasnippet/doc/define_snippet.html#indenting>`_. + +0.5.6 / 2008-08-07 +================== + +* Added a buffer local variable ``yas/dont-activate`` to turn off + ``yas/minor-mode`` in some major modes. See `Issue 29 + <http://code.google.com/p/yasnippet/issues/detail?id=29>`_. +* Make the environment of elisp evaluation more friendly to + ``(current-column)``. +* Fixed the regular expression bug in python-mode snippets. +* Use filename or full key extension for snippet name if no ``name`` + property is defined. + +0.5.5 / 2008-05-29 +================== + +* Tweak ``yas/extra-mode-hooks`` so that it can be more easily + customized. +* Add an entry in FAQ about why ``TAB`` key doesn't work in some + modes. + +0.5.4 / 2008-05-15 +================== + +* Added ``ox-mode-hook`` and ``python-mode-hook`` to + ``yas/extra-mode-hooks`` to fix the problem YASnippet is not enabled + in those modes. + +0.5.3 / 2008-05-07 +================== + +* Fix indent of python-mode snippets. +* Fix a bug of dropdown-list: conflicts with color-theme (`Issue 23 + <http://code.google.com/p/yasnippet/issues/detail?id=23>`_). Thanks + Mike. +* Fix a bug of condition system. + +0.5.2 / 2008-04-20 +================== + +* Fix a bug for comparing string to symbol using ``string=`` (which + will fire an error). + +0.5.1 / 2008-04-14 +================== + +* Use a beautiful css style in the document. + +0.5.0 / 2008-04-10 +================== + +* Integrate with hippie-expand. Just add ``yas/hippie-try-expand`` to + ``hippie-expand-try-functions-list``. +* If you set ``yas/fall-back-behavior`` to ``'return-nil``, YASnippet + will return nil when it can't find a snippet to expand. +* Defect fix: the condition of a snippet was evaluated twice in + earlier version. +* Deleting snippet (using ``C-w`` or ``C-k``) won't cause serious + problem now. +* Several complex snippet for python-mode from Yasser included in the + distribution. + +0.4.5 / 2008-04-07 +================== + +* Merge the latest dropdown-list.el. +* Add snippets for f90-mode from Li Zhu. +* Bug fix: l-safe-expr-p: Lisp nesting exceeds ``max-lisp-eval-depth`` + error when several (more than two) snippets overlaps. Thanks + sunwaybupt@newsmth for reporting this bug. + +0.4.4 / 2008-03-24 +================== + +* Bug fix: dropdown-list.el doesn't recognize [return] properly. + +0.4.3 / 2008-03-23 +================== + +* Bug fix: failed to recognize user customized yas/trigger-key. + +0.4.2 / 2008-03-22 +================== + +* Make a separate document package for release. Also make document + available online. + +0.4.1 / 2008-03-21 +================== + +* Make sure ``yas/minor-mode``'s key bindings always take priority to + other minor modes. + +0.4.0 / 2008-03-20 +================== + +* Document refinement and released with YASnippet. Most of the Online + wiki document will be deprecated soon. +* Powerful condition system added to yasnippet! +* Incorporate ``dropdown-list.el`` and make it default way for + selecting multiple candidates. Thanks to `Jaeyoun Chung + <http://groups.google.com/group/smart-snippet/browse_thread/thread/c869158b76addeb3/e7c6372ba457189e>`_. +* yas/before-expand-snippet-hook + +0.3.2 / 2008-03-19 +================== + +* Enhancement: A better way to define minor-mode. Thanks to Kentaro + Kuribayashi. See `this thread + <https://groups.google.com/group/smart-snippet/browse_thread/thread/65cb3b5583eda887?hl=en>`_ + for more details. + +0.3.1 / 2008-03-17 +================== + +* Bug fix: Emacs get confused when a field is deleted. See `issue 10 + <http://code.google.com/p/yasnippet/issues/detail?id=10>`_. + +0.3.0 / 2008-03-16 +================== + +* Add a ``yas/after-exit-snippet-hook`` so that you can do something like + ``indent-region`` or ``fill-region`` after finish the snippet. +* Use minor-mode instead of ``global-set-key`` to bind the trigger + key. Now the trigger key and fall-back behavior can be more + flexible. Not constrained to ``<tab>``. Thanks to Trey Jackson. See + this `thread + <https://groups.google.com/group/smart-snippet/browse_thread/thread/937f32a2a6dea4f2?hl=en>`_ + for more details. +* Now user can customize the popup function for selecting multiple + candidate for the same snippet key. +* Support ``dropdown-list.el`` to be a better way to select multiple + candidate when in text mode. + +0.2.3 / 2008-03-15 +================== + +* Bug in non-window (-nw) mode when there's multiple candidate to + expand. See `issue 7 + <http://code.google.com/p/yasnippet/issues/detail?id=7>`_. +* Allow expanding another snippet as long as not currently inside a + field. + +0.2.2 / 2008-03-13 +================== + +* Added customized face for fields and mirrors. Better in dark + background. And users can customize it. + +0.2.1 / 2008-03-10 +================== + +* Fix the insert-behind problem under both Emacs 22 and Emacs 23. + +0.2.0 / 2008-03-10 +================== + +* Use big keymap overlay to detect ``insert-behind`` event manually to + avoid sometimes missed hook calls. See `issue 3 + <http://code.google.com/p/yasnippet/issues/detail?id=3>`_ for more + details. +* Support parent snippet table. Now you can set (for example) + ``cc-mode`` as common mode for ``c++-mode``, ``c-mode`` and + ``java-mode``. They'll share snippets defined for ``cc-mode``. + +0.1.1 / 2008-03-08 +================== + +* Add a rake task to upload to google code. +* Use elisp compile-bundle function instead of python scrip + +0.1.0 / 2008-03-07 +================== + +* Embedded elisp support. +* Fields navigation support. +* Mirror of fields support. +* Menu-bar support. +* Multiple snippets with same name support. +* Popup menu for multiple snippet with same name support. +* Transformation of fields support. +* Load directory support. +* Compile bundle support. diff --git a/emacs.d/lisp/yasnippet/doc/compile-doc.py b/emacs.d/lisp/yasnippet/doc/compile-doc.py new file mode 100755 index 0000000..2d325e7 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/compile-doc.py @@ -0,0 +1,110 @@ +#!/usr/bin/python +# Compile document to HTML use docutils. + +# ======================================== +# Pygments syntax highlighting +# ======================================== +from pygments.formatters import HtmlFormatter + +# Set to True if you want inline CSS styles instead of classes +INLINESTYLES = True + +from pygments.formatters import HtmlFormatter + +# The default formatter +DEFAULT = HtmlFormatter(noclasses=INLINESTYLES) + +# Add name -> formatter pairs for every variant you want to use +VARIANTS = { + # 'linenos': HtmlFormatter(noclasses=INLINESTYLES, linenos=True), +} + +from docutils import nodes +from docutils.parsers.rst import directives + +from pygments import highlight +from pygments.lexers import get_lexer_by_name, TextLexer + +def pygments_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + try: + lexer = get_lexer_by_name(arguments[0]) + except ValueError: + # no lexer found - use the text one instead of an exception + lexer = TextLexer() + # take an arbitrary option if more than one is given + formatter = options and VARIANTS[options.keys()[0]] or DEFAULT + parsed = highlight(u'\n'.join(content), lexer, formatter) + return [nodes.raw('', parsed, format='html')] + +pygments_directive.arguments = (1, 0, 1) +pygments_directive.content = 1 +pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS]) + +directives.register_directive('sourcecode', pygments_directive) + +# ================= +# Youtube embedding +# ================= + +from docutils import nodes +from docutils.parsers.rst import directives + +CODE = """\ +<object type="application/x-shockwave-flash" + width="%(width)s" + height="%(height)s" + align="%(align)s" + class="youtube-embed" + data="http://www.youtube.com/v/%(yid)s"> + <param name="movie" value="http://www.youtube.com/v/%(yid)s"></param> + <param name="wmode" value="transparent"></param>%(extra)s +</object> +""" + +PARAM = """\n <param name="%s" value="%s"></param>""" + +def youtube(name, args, options, content, lineno, + contentOffset, blockText, state, stateMachine): + """ Restructured text extension for inserting youtube embedded videos """ + if len(content) == 0: + return + string_vars = { + 'yid': content[0], + 'width': 425, + 'height': 344, + 'align': "right", + 'extra': '' + } + extra_args = content[1:] # Because content[0] is ID + extra_args = [ea.strip().split("=") for ea in extra_args] # key=value + extra_args = [ea for ea in extra_args if len(ea) == 2] # drop bad lines + extra_args = dict(extra_args) + if 'width' in extra_args: + string_vars['width'] = extra_args.pop('width') + if 'align' in extra_args: + string_vars['align'] = extra_args.pop('align') + if 'height' in extra_args: + string_vars['height'] = extra_args.pop('height') + if extra_args: + params = [PARAM % (key, extra_args[key]) for key in extra_args] + string_vars['extra'] = "".join(params) + return [nodes.raw('', CODE % (string_vars), format='html')] +youtube.content = True +directives.register_directive('youtube', youtube) + + +# ======================================== +# Command line processing +# ======================================== +from docutils.core import publish_cmdline, default_description + +description = ('Generates (X)HTML documents from standalone reStructuredText ' + 'sources. ' + default_description) +overrides = {'stylesheet_path' : 'styles.css', + 'embed_stylesheet' : False, + 'template' : 'doc/template.txt'} + +publish_cmdline(writer_name='html', + description=description, + settings_overrides=overrides) diff --git a/emacs.d/lisp/yasnippet/doc/define_snippet.html b/emacs.d/lisp/yasnippet/doc/define_snippet.html new file mode 100644 index 0000000..984d3db --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/define_snippet.html @@ -0,0 +1,78 @@ +<?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>Moved</title> +<meta content="3; URL=index.html" http-equiv="Refresh" /> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="moved"> +<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">Moved</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> + <p>This page has been moved. Click <a class="reference external" href="index.html">here</a> if your browser +does not automatically redirect you</p> + </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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/define_snippet.rst b/emacs.d/lisp/yasnippet/doc/define_snippet.rst new file mode 100644 index 0000000..9e312c3 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/define_snippet.rst @@ -0,0 +1,9 @@ +===== +Moved +===== + +.. meta:: + :http-equiv=Refresh: 3; URL=index.html + +This page has been moved. Click `here <index.html>`_ if your browser +does not automatically redirect you diff --git a/emacs.d/lisp/yasnippet/doc/faq.html b/emacs.d/lisp/yasnippet/doc/faq.html new file mode 100644 index 0000000..b3ef304 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/faq.html @@ -0,0 +1,189 @@ +<?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>Frequently Asked Questions</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="frequently-asked-questions"> +<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">Frequently Asked Questions</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="section" id="why-is-there-an-extra-newline"> +<h1>Why is there an extra newline?</h1> +<p>If you have a newline at the end of the snippet definition file, then +YASnippet will add a newline when you expanding a snippet. Please +don't add a newline at the end if you don't want it when you saving +the snippet file.</p> +<p>Note some editors will automatically add a newline for you. In Emacs, +if you set <tt class="docutils literal"><span class="pre">require-final-newline</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt>, it will add the final +newline for you automatically.</p> +</div> +<div class="section" id="why-doesn-t-tab-expand-a-snippet"> +<h1>Why doesn't TAB expand a snippet?</h1> +<p>First check the mode line to see if there's <tt class="docutils literal"><span class="pre">yas</span></tt>. If not, then try +<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/minor-mode</span></tt> to manually turn on the minor mode and try to +expand the snippet again. If it works, then, you can add the following +code to your <tt class="docutils literal"><span class="pre">.emacs</span></tt> <em>before</em> loading YASnippet:</p> +<div class="highlight"><pre>(add-hook 'the-major-mode-hook 'yas/minor-mode-on) +</pre></div> +<p>where <tt class="docutils literal"><span class="pre">the-major-mode</span></tt> is the major mode in which <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> +isn't enabled by default.</p> +<p>From YASnippet 0.6 you can also use the command <tt class="docutils literal"><span class="pre">M-x</span> +<span class="pre">yas/global-mode</span></tt> to turn on YASnippet automatically for <em>all</em> major +modes.</p> +<p>If <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is on but the snippet still not expanded. Then +try to see what command is bound to the <tt class="docutils literal"><span class="pre">TAB</span></tt> key: press <tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">k</span></tt> +and then press <tt class="docutils literal"><span class="pre">TAB</span></tt>. Emacs will show you the result.</p> +<p>You'll see a buffer prompted by Emacs saying that <tt class="docutils literal"><span class="pre">TAB</span> <span class="pre">runs</span> <span class="pre">the</span> +<span class="pre">command</span> <span class="pre">...</span></tt>. Alternatively, you might see <tt class="docutils literal"><span class="pre"><tab></span> <span class="pre">runs</span> <span class="pre">the</span> <span class="pre">command</span> +<span class="pre">...</span></tt>, note the difference between <tt class="docutils literal"><span class="pre">TAB</span></tt> and <tt class="docutils literal"><span class="pre"><tab></span></tt> where the +latter has priority. If you see <tt class="docutils literal"><span class="pre"><tab></span></tt> bound to a command other +than <tt class="docutils literal"><span class="pre">yas/expand</span></tt>, (e.g. in <tt class="docutils literal"><span class="pre">org-mode</span></tt>) you can try the following +code to work around:</p> +<div class="highlight"><pre>(add-hook 'org-mode-hook + (let ((original-command (lookup-key org-mode-map [tab]))) + `(lambda () + (setq yas/fallback-behavior + '(apply ,original-command)) + (local-set-key [tab] 'yas/expand)))) +</pre></div> +<p>replace <tt class="docutils literal"><span class="pre">org-mode-hook</span></tt> and <tt class="docutils literal"><span class="pre">org-mode-map</span></tt> with the major mode +hook you are dealing with (Use <tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">m</span></tt> to see what major mode you +are in).</p> +<p>As an alternative, you can also try</p> +<div class="highlight"><pre>(defun yas/advise-indent-function (function-symbol) + (eval `(defadvice ,function-symbol (around yas/try-expand-first activate) + ,(format + "Try to expand a snippet before point, then call `%s' as usual" + function-symbol) + (let ((yas/fallback-behavior nil)) + (unless (and (interactive-p) + (yas/expand)) + ad-do-it))))) + +(yas/advise-indent-function 'ruby-indent-line) +</pre></div> +<p>To <em>advise</em> the modes indentation function bound to TAB, (in this case +<tt class="docutils literal"><span class="pre">ruby-indent-line</span></tt>) to first try to run <tt class="docutils literal"><span class="pre">yas/expand</span></tt>.</p> +<p>If the output of <tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">k</span> <span class="pre">RET</span> <span class="pre"><tab></span></tt> tells you that <tt class="docutils literal"><span class="pre"><tab></span></tt> is +indeed bound to <tt class="docutils literal"><span class="pre">yas/expand</span></tt> but YASnippet still doesn't work, check +your configuration and you may also ask for help on the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion +group</a>. See this +particular <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=93&can=1">thread</a> for +quite some solutions and alternatives.</p> +<p>Don't forget to attach the information on what command is bound to TAB +as well as the mode information (Can be obtained by <tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">m</span></tt>).</p> +</div> +<div class="section" id="why-doesn-t-tab-navigation-work-with-flyspell"> +<h1>Why doesn't TAB navigation work with flyspell</h1> +<p>A workaround is to inhibit flyspell overlays while the snippet is active:</p> +<div class="highlight"><pre>(add-hook 'flyspell-incorrect-hook + #'(lambda (dummy1 dummy2 dymmy3) + (and yas/active-field-overlay + (overlay-buffer yas/active-field-overlay)))) +</pre></div> +<p>This is apparently related to overlay priorities. For some reason, the +<tt class="docutils literal"><span class="pre">keymap</span></tt> property of flyspell's overlays always takes priority over +the same property in yasnippet's overlays, even if one sets the +latter's <tt class="docutils literal"><span class="pre">priority</span></tt> property to something big. If you know +emacs-lisp and can solve this problem, drop a line in the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion +group</a>.</p> +</div> +<div class="section" id="how-do-i-turn-off-the-minor-mode-where-in-some-buffers"> +<h1>How do I turn off the minor mode where in some buffers</h1> +<p>The best way, since version 0.6.1c, is to set the default value of the +variable <tt class="docutils literal"><span class="pre">yas/dont-activate</span></tt> to a lambda function like so:</p> +<div class="highlight"><pre>(set-default 'yas/dont-activate + #'(lambda () + (and yas/root-directory + (null (yas/get-snippet-tables))))) +</pre></div> +<p>This is also the default value starting for that version. It skips the +minor mode in buffers where it is not applicable (no snippet tables), +but only once you have setup your yas/root-directory.</p> +</div> +<div class="section" id="how-do-i-define-an-abbrev-key-containing-characters-not-supported-by-the-filesystem"> +<h1>How do I define an abbrev key containing characters not supported by the filesystem?</h1> +<dl class="docutils"> +<dt><strong>Note</strong>: This question applies if you're still defining snippets</dt> +<dd>whose key <em>is</em> the filename. This is behavior stil provided by +version 0.6 for backward compatibilty, but is somewhat deprecated...</dd> +</dl> +<p>For example, you want to define a snippet by the key <tt class="docutils literal"><span class="pre"><</span></tt> which is +not a valid character for filename on Windows. This means you can't +use the filename as a trigger key in this case.</p> +<p>You should rather use the <tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive to specify the key of +the defined snippet explicitly and name your snippet with an arbitrary +valid filename, <tt class="docutils literal"><span class="pre">lt.yasnippet</span></tt> for example, using <tt class="docutils literal"><span class="pre"><</span></tt> for the +<tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive:</p> +<div class="highlight"><pre>#key: < +#name: <...></...> +# -- +<${1:div}>$0</$1> +</pre></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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/faq.rst b/emacs.d/lisp/yasnippet/doc/faq.rst new file mode 100644 index 0000000..ad1fa72 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/faq.rst @@ -0,0 +1,150 @@ +============================ + Frequently Asked Questions +============================ + +Why is there an extra newline? +============================== + +If you have a newline at the end of the snippet definition file, then +YASnippet will add a newline when you expanding a snippet. Please +don't add a newline at the end if you don't want it when you saving +the snippet file. + +Note some editors will automatically add a newline for you. In Emacs, +if you set ``require-final-newline`` to ``t``, it will add the final +newline for you automatically. + +Why doesn't TAB expand a snippet? +================================= + +First check the mode line to see if there's ``yas``. If not, then try +``M-x yas/minor-mode`` to manually turn on the minor mode and try to +expand the snippet again. If it works, then, you can add the following +code to your ``.emacs`` *before* loading YASnippet: + +.. sourcecode:: lisp + + (add-hook 'the-major-mode-hook 'yas/minor-mode-on) + +where ``the-major-mode`` is the major mode in which ``yas/minor-mode`` +isn't enabled by default. + +From YASnippet 0.6 you can also use the command ``M-x +yas/global-mode`` to turn on YASnippet automatically for *all* major +modes. + +If ``yas/minor-mode`` is on but the snippet still not expanded. Then +try to see what command is bound to the ``TAB`` key: press ``C-h k`` +and then press ``TAB``. Emacs will show you the result. + +You'll see a buffer prompted by Emacs saying that ``TAB runs the +command ...``. Alternatively, you might see ``<tab> runs the command +...``, note the difference between ``TAB`` and ``<tab>`` where the +latter has priority. If you see ``<tab>`` bound to a command other +than ``yas/expand``, (e.g. in ``org-mode``) you can try the following +code to work around: + +.. sourcecode:: lisp + + (add-hook 'org-mode-hook + (let ((original-command (lookup-key org-mode-map [tab]))) + `(lambda () + (setq yas/fallback-behavior + '(apply ,original-command)) + (local-set-key [tab] 'yas/expand)))) + +replace ``org-mode-hook`` and ``org-mode-map`` with the major mode +hook you are dealing with (Use ``C-h m`` to see what major mode you +are in). + +As an alternative, you can also try + +.. sourcecode:: lisp + + (defun yas/advise-indent-function (function-symbol) + (eval `(defadvice ,function-symbol (around yas/try-expand-first activate) + ,(format + "Try to expand a snippet before point, then call `%s' as usual" + function-symbol) + (let ((yas/fallback-behavior nil)) + (unless (and (interactive-p) + (yas/expand)) + ad-do-it))))) + + (yas/advise-indent-function 'ruby-indent-line) + +To *advise* the modes indentation function bound to TAB, (in this case +``ruby-indent-line``) to first try to run ``yas/expand``. + +If the output of ``C-h k RET <tab>`` tells you that ``<tab>`` is +indeed bound to ``yas/expand`` but YASnippet still doesn't work, check +your configuration and you may also ask for help on the `discussion +group <http://groups.google.com/group/smart-snippet>`_. See this +particular `thread +<http://code.google.com/p/yasnippet/issues/detail?id=93&can=1>`_ for +quite some solutions and alternatives. + +Don't forget to attach the information on what command is bound to TAB +as well as the mode information (Can be obtained by ``C-h m``). + +Why doesn't TAB navigation work with flyspell +============================================= + +A workaround is to inhibit flyspell overlays while the snippet is active: + +.. sourcecode:: lisp + + (add-hook 'flyspell-incorrect-hook + #'(lambda (dummy1 dummy2 dymmy3) + (and yas/active-field-overlay + (overlay-buffer yas/active-field-overlay)))) + +This is apparently related to overlay priorities. For some reason, the +``keymap`` property of flyspell's overlays always takes priority over +the same property in yasnippet's overlays, even if one sets the +latter's ``priority`` property to something big. If you know +emacs-lisp and can solve this problem, drop a line in the `discussion +group`_. + +How do I turn off the minor mode where in some buffers +====================================================== + +The best way, since version 0.6.1c, is to set the default value of the +variable ``yas/dont-activate`` to a lambda function like so: + +.. sourcecode:: lisp + + (set-default 'yas/dont-activate + #'(lambda () + (and yas/root-directory + (null (yas/get-snippet-tables))))) + +This is also the default value starting for that version. It skips the +minor mode in buffers where it is not applicable (no snippet tables), +but only once you have setup your yas/root-directory. + + +How do I define an abbrev key containing characters not supported by the filesystem? +==================================================================================== + +**Note**: This question applies if you're still defining snippets + whose key *is* the filename. This is behavior stil provided by + version 0.6 for backward compatibilty, but is somewhat deprecated... + +For example, you want to define a snippet by the key ``<`` which is +not a valid character for filename on Windows. This means you can't +use the filename as a trigger key in this case. + +You should rather use the ``# key:`` directive to specify the key of +the defined snippet explicitly and name your snippet with an arbitrary +valid filename, ``lt.yasnippet`` for example, using ``<`` for the +``# key:`` directive: + +.. sourcecode:: text + + #key: < + #name: <...></...> + # -- + <${1:div}>$0</$1> + +.. _discussion group: http://groups.google.com/group/smart-snippet diff --git a/emacs.d/lisp/yasnippet/doc/html4css1.css b/emacs.d/lisp/yasnippet/doc/html4css1.css new file mode 100644 index 0000000..bf10767 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/html4css1.css @@ -0,0 +1,279 @@ +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $ +:Revision: $Revision: 4224 $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left { + clear: left } + +img.align-right { + clear: right } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +tt.docutils { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } diff --git a/emacs.d/lisp/yasnippet/doc/images/bg-content-left.png b/emacs.d/lisp/yasnippet/doc/images/bg-content-left.png Binary files differnew file mode 100644 index 0000000..a64b346 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/bg-content-left.png diff --git a/emacs.d/lisp/yasnippet/doc/images/bg-content-right.png b/emacs.d/lisp/yasnippet/doc/images/bg-content-right.png Binary files differnew file mode 100644 index 0000000..f07ebb5 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/bg-content-right.png diff --git a/emacs.d/lisp/yasnippet/doc/images/bg-content.png b/emacs.d/lisp/yasnippet/doc/images/bg-content.png Binary files differnew file mode 100644 index 0000000..d55828e --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/bg-content.png diff --git a/emacs.d/lisp/yasnippet/doc/images/bg-navigation-item-hover.png b/emacs.d/lisp/yasnippet/doc/images/bg-navigation-item-hover.png Binary files differnew file mode 100644 index 0000000..c783d71 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/bg-navigation-item-hover.png diff --git a/emacs.d/lisp/yasnippet/doc/images/bg-navigation-item.png b/emacs.d/lisp/yasnippet/doc/images/bg-navigation-item.png Binary files differnew file mode 100644 index 0000000..d2452ac --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/bg-navigation-item.png diff --git a/emacs.d/lisp/yasnippet/doc/images/bg-navigation.png b/emacs.d/lisp/yasnippet/doc/images/bg-navigation.png Binary files differnew file mode 100644 index 0000000..18b9559 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/bg-navigation.png diff --git a/emacs.d/lisp/yasnippet/doc/images/body.png b/emacs.d/lisp/yasnippet/doc/images/body.png Binary files differnew file mode 100644 index 0000000..b361e7b --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/body.png diff --git a/emacs.d/lisp/yasnippet/doc/images/customization-group.png b/emacs.d/lisp/yasnippet/doc/images/customization-group.png Binary files differnew file mode 100644 index 0000000..b10827f --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/customization-group.png diff --git a/emacs.d/lisp/yasnippet/doc/images/dropdown-menu.png b/emacs.d/lisp/yasnippet/doc/images/dropdown-menu.png Binary files differnew file mode 100644 index 0000000..57d482e --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/dropdown-menu.png diff --git a/emacs.d/lisp/yasnippet/doc/images/external.png b/emacs.d/lisp/yasnippet/doc/images/external.png Binary files differnew file mode 100644 index 0000000..419c06f --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/external.png diff --git a/emacs.d/lisp/yasnippet/doc/images/ido-menu.png b/emacs.d/lisp/yasnippet/doc/images/ido-menu.png Binary files differnew file mode 100644 index 0000000..df392c5 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/ido-menu.png diff --git a/emacs.d/lisp/yasnippet/doc/images/menu-1.png b/emacs.d/lisp/yasnippet/doc/images/menu-1.png Binary files differnew file mode 100644 index 0000000..d2e6a51 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/menu-1.png diff --git a/emacs.d/lisp/yasnippet/doc/images/menu-2.png b/emacs.d/lisp/yasnippet/doc/images/menu-2.png Binary files differnew file mode 100644 index 0000000..abb8a72 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/menu-2.png diff --git a/emacs.d/lisp/yasnippet/doc/images/menu-groups.png b/emacs.d/lisp/yasnippet/doc/images/menu-groups.png Binary files differnew file mode 100644 index 0000000..fcedda8 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/menu-groups.png diff --git a/emacs.d/lisp/yasnippet/doc/images/menu-parent.png b/emacs.d/lisp/yasnippet/doc/images/menu-parent.png Binary files differnew file mode 100644 index 0000000..f0fa10c --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/menu-parent.png diff --git a/emacs.d/lisp/yasnippet/doc/images/minor-mode-indicator.png b/emacs.d/lisp/yasnippet/doc/images/minor-mode-indicator.png Binary files differnew file mode 100644 index 0000000..3743455 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/minor-mode-indicator.png diff --git a/emacs.d/lisp/yasnippet/doc/images/x-menu.png b/emacs.d/lisp/yasnippet/doc/images/x-menu.png Binary files differnew file mode 100644 index 0000000..3bc9a15 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/images/x-menu.png diff --git a/emacs.d/lisp/yasnippet/doc/index.html b/emacs.d/lisp/yasnippet/doc/index.html new file mode 100644 index 0000000..4f02a7e --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/index.html @@ -0,0 +1,201 @@ +<?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>Yet Another Snippet extension</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="yet-another-snippet-extension"> +<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">Yet Another Snippet extension</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="#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="#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> +<li><a class="reference internal" href="#how-to-use-yasnippet" id="id5">How to use YASnippet</a></li> +<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 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" + width="425" + height="344" + align="right" + class="youtube-embed" + 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=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 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.</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 +<tt class="docutils literal"><span class="pre">~/.emacs.d/plugins/</span></tt> (create the directory if not exists).</li> +<li>Open the file in Emacs, and type <tt class="docutils literal"><span class="pre">Alt+x</span> <span class="pre">eval-buffer</span></tt>.</li> +</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 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> +<div class="highlight"><pre>(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">'load-path</span> + <span style="color: #BA2121">"~/.emacs.d/plugins"</span>) +(<span style="color: #008000">require</span> <span style="color: #19177C">'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>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">'load-path</span> + <span style="color: #BA2121">"~/.emacs.d/plugins/yasnippet-x.y.z"</span>) +(<span style="color: #008000">require</span> <span style="color: #19177C">'yasnippet</span>) <span style="color: #408080; font-style: italic">;; not yasnippet-bundle</span> +(<span style="color: #19177C">yas/initialize</span>) +(<span style="color: #19177C">yas/load-directory</span> <span style="color: #BA2121">"~/.emacs.d/plugins/yasnippet-x.y.z/snippets"</span>) +</pre></div> +</blockquote> +<p>Please refer to the documentation for full customization, or use the +customization group.</p> +</div> +</div> +<div class="section" id="how-to-use-yasnippet"> +<h1><a class="toc-backref" href="#id5">How to use YASnippet</a></h1> +<p>Since version 0.6, YASnippet contains more functionality. You don't +need to know all of it to use it successfully, but you it can improve +your snippeting experience.</p> +<p>Hence this section has been split into separate documents:</p> +<ol class="arabic simple"> +<li><a class="reference external" href="snippet-organization.html">Organizing Snippets</a></li> +</ol> +<blockquote> +Describes ways to organize your snippets in the hard disk (or not +organize them at all and just use <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt>.</blockquote> +<ol class="arabic simple" start="2"> +<li><a class="reference external" href="snippet-expansion.html">Expanding Snippets</a></li> +</ol> +<blockquote> +<p>Describes how YASnippet chooses snippets for expansion at point.</p> +<p>Maybe, you'll want some snippets to be expanded in a particular +mode, or only under certain conditions, or be prompted using +<tt class="docutils literal"><span class="pre">ido</span></tt>, etc...</p> +</blockquote> +<ol class="arabic simple" start="3"> +<li><a class="reference external" href="snippet-development.html">Writing Snippets</a></li> +</ol> +<blockquote> +Describes the YASnippet definition syntax, which is very close (but +not equivalent) to Textmate's. Includes a section about converting +TextMate snippets.</blockquote> +<ol class="arabic simple" start="4"> +<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, learn and modify +snippets.</blockquote> +</div> +<div class="section" id="bugs-contribution-and-support"> +<h1><a class="toc-backref" href="#id6">Bugs, Contribution and Support</a></h1> +<ul class="simple"> +<li>If you find a bug, please report it at <a class="reference external" href="http://code.google.com/p/yasnippet/issues/list">Issue List</a>.</li> +<li>If you have problem using YASnippet, or have some new ideas, +including snippets, please post to the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a>.</li> +</ul> +<p>Thank you very much for using YASnippet!</p> +<!-- LocalWords: YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki --> +</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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/index.rst b/emacs.d/lisp/yasnippet/doc/index.rst new file mode 100644 index 0000000..7415186 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/index.rst @@ -0,0 +1,133 @@ +============================= +Yet Another Snippet extension +============================= + +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html + +.. contents:: + +**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. + +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:: 76Ygeg9miao + :align: right + +Watch the `demo at YouTube +<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 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. + +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 + ``~/.emacs.d/plugins/`` (create the directory if not exists). +3. Open the file in Emacs, and type ``Alt+x eval-buffer``. + +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 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: + + .. sourcecode:: common-lisp + + (add-to-list 'load-path + "~/.emacs.d/plugins") + (require 'yasnippet-bundle) + +The `youtube video <http://www.youtube.com/watch?v=76Ygeg9miao>`_ +demonstrates this quick installation. + +Normal Install +-------------- + +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 + + (add-to-list 'load-path + "~/.emacs.d/plugins/yasnippet-x.y.z") + (require 'yasnippet) ;; not yasnippet-bundle + (yas/initialize) + (yas/load-directory "~/.emacs.d/plugins/yasnippet-x.y.z/snippets") + +Please refer to the documentation for full customization, or use the +customization group. + +How to use YASnippet +==================== + +Since version 0.6, YASnippet contains more functionality. You don't +need to know all of it to use it successfully, but you it can improve +your snippeting experience. + +Hence this section has been split into separate documents: + +1. `Organizing Snippets`_ + + Describes ways to organize your snippets in the hard disk (or not + organize them at all and just use ``yasnippet-bundle.el``. + +2. `Expanding Snippets`_ + + Describes how YASnippet chooses snippets for expansion at point. + + Maybe, you'll want some snippets to be expanded in a particular + mode, or only under certain conditions, or be prompted using + ``ido``, etc... + +3. `Writing Snippets`_ + + Describes the YASnippet definition syntax, which is very close (but + not equivalent) to Textmate's. Includes a section about converting + TextMate snippets. + +4. `The YASnippet menu`_ + + Explains how to use the YASnippet menu to explore, learn and modify + snippets. + +Bugs, Contribution and Support +============================== + +* If you find a bug, please report it at `Issue List + <http://code.google.com/p/yasnippet/issues/list>`_. +* If you have problem using YASnippet, or have some new ideas, + including snippets, please post to the `discussion group`_. + +.. _discussion group: http://groups.google.com/group/smart-snippet +.. _wish list: http://code.google.com/p/yasnippet/wiki/WishList + +Thank you very much for using YASnippet! + +.. LocalWords: YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki diff --git a/emacs.d/lisp/yasnippet/doc/snippet-development.html b/emacs.d/lisp/yasnippet/doc/snippet-development.html new file mode 100644 index 0000000..6b55b4c --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-development.html @@ -0,0 +1,623 @@ +<?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>Writing snippets</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="writing-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">Writing 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="#snippet-development" id="id3">Snippet development</a><ul> +<li><a class="reference internal" href="#quickly-finding-snippets" id="id4">Quickly finding snippets</a></li> +<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></li> +</ul> +</li> +<li><a class="reference internal" href="#file-content" id="id6">File content</a><ul> +<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="#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="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="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="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:</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 +directory to store it, prompting you for creation if it does not +exist. Finally, places you in a new buffer set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> +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>. 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 +<tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, but instead of expanding it, takes you +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> +<p>There is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to edit snippets. You can set +the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">snippet-mode</span></tt>. It provides +reasonably useful syntax highlighting.</p> +<p>Two commands are defined in this mode:</p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p> +<blockquote> +<p>When editing a snippet, this loads the snippet into the correct +mode and menu. Bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-c</span></tt> by default while in +<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/tryout-snippet</span></tt></p> +<blockquote> +<p>When editing a snippet, this opens a new empty buffer, sets it to +the appropriate major mode and inserts the snippet there, so you +can see what it looks like. This is bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-t</span></tt> while in +<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p> +</blockquote> +</li> +</ul> +<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 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 <pluskid@gmail.com> +#name : __...__ +# -- +__${init}__ +</pre></div> +<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 +abbreviation you type to expand a snippet just before hitting +<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p> +<p>If you don't specify this it will default to the name of the file the +snippet is being loaded from, unless YASnippet is ignoring file names +as triggers (see <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> in <a class="reference external" href="snippet-organization.html">Organizing +snippets</a>), in which case this snippet +will not be expandable through the key mechanism.</p> +<p>Sometimes the key of a snippet is non-ASCII or not valid filename +(e.g. contains <tt class="docutils literal"><span class="pre">/</span></tt>). One can then define the <tt class="docutils literal"><span class="pre">key</span></tt> property which +will overwrite the filename as the key to expand the snippet.</p> +</div> +<div class="section" id="name-snippet-name"> +<h2><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></h2> +<p>This is a one-line description of the snippet. It will be displayed in +the menu. It's a good idea to select a descriptive name for a +snippet -- especially distinguishable among similar snippets.</p> +<p>If you omit this name it will default to the file name the snippet was +loaded from.</p> +</div> +<div class="section" id="condition-snippet-condition"> +<h2><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></h2> +<p>This is a piece of Emacs-lisp code. If a snippet has a condition, then it +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> +</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 +long.</p> +<p>The <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> property only affect menu construction (See <a class="reference external" href="snippet-menu.html">the +YASnippet menu</a>) and the same effect can be achieved by grouping +snippets into sub-directories and using the <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> +special file (for this see <a class="reference external" href="snippet-organization.html">Organizing Snippets</a></p> +<p>Refer to the bundled snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples on the +<tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> directive. Group can also be nested, e.g. <tt class="docutils literal"><span class="pre">control</span> +<span class="pre">structure.loops</span></tt> tells that the snippet is under the <tt class="docutils literal"><span class="pre">loops</span></tt> group +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="#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 +<tt class="docutils literal"><span class="pre">'auto</span></tt> and <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> set to <tt class="docutils literal"><span class="pre">t</span></tt>, but for this +particularly brilliant piece of ASCII art these values would mess up +your hard work. You can then use:</p> +<div class="highlight"><pre># name : ASCII home +# expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil)) +# -- + welcome to my + X humble + / \ home, + / \ $0 + / \ + /-------\ + | | + | +-+ | + | | | | + +--+-+--+ +</pre></div> +</div> +<div class="section" id="binding-direct-keybinding"> +<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 +for.</p> +<p>Additionally a variable <tt class="docutils literal"><span class="pre">yas/prefix</span></tt> is set to to the prefix +argument you normally use for a command. This allows for small +variations on the same snippet, for example in this "html-mode" +snippet.</p> +<div class="highlight"><pre>#name : <p>...</p> +#binding: "C-c C-c C-m" +# -- +<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p> +</pre></div> +<p>This binding will be recorded in the keymap <tt class="docutils literal"><span class="pre">html-mode-map</span></tt>. To +expand a paragraph tag newlines, just press "C-u C-c C-c +C-m". Omitting the "C-u" will expand the paragraph tag without +newlines.</p> +<p>To override the keymap choice based on the major mode name. Use a cons +cell where the first element specifies the name of the keymap where +you want to record the keybinding.</p> +<div class="highlight"><pre>#name : <p>...</p> +#binding: (rinari-minor-mode-map . "C-c C-c C-m") +# -- +<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p> +</pre></div> +<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="#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="#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="#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="#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 + +$0 + +#endif /* $1 */ +</pre></div> +<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) { + `yas/selected-text`$0 +} +</pre></div> +<p>to "wrap" the selected region inside your recently inserted +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="#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 +snippet. That is the last place to go when you've traveled all the +fields. Here's a typical example:</p> +<div class="highlight"><pre><div$1> + $0 +</div> +</pre></div> +</div> +<div class="section" id="placeholder-fields"> +<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} +</pre></div> +<p>They acts as the default value for a tab stop. But when you firstly +type at a tab stop, the default value will be replaced by your +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="#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> +<div class="highlight"><pre>\begin{${1:enumerate}} + $0 +\end{$1} +</pre></div> +<p>When you type <tt class="docutils literal"><span class="pre">"document"</span></tt> at <tt class="docutils literal"><span class="pre">${1:enumerate}</span></tt>, the word +<tt class="docutils literal"><span class="pre">"document"</span></tt> will also be inserted at <tt class="docutils literal"><span class="pre">\end{$1}</span></tt>. The best +explanation is to see the screencast(<a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">YouTube</a> or <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">avi video</a>).</p> +<p>The tab stops with the same number to the field act as its mirrors. If +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="#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 +this transformation, which is Emacs-lisp code that gets evaluated in +an environment where the variable <tt class="docutils literal"><span class="pre">text</span></tt> (or <tt class="docutils literal"><span class="pre">yas/text</span></tt>) is bound +to the text content (string) contained in the field <tt class="docutils literal"><span class="pre">n</span></tt>.Here's an +example for Objective-C:</p> +<div class="highlight"><pre>- (${1:id})${2:foo} +{ + return $2; +} + +- (void)set${2:$(capitalize text)}:($1)aValue +{ + [$2 autorelease]; + $2 = [aValue retain]; +} +$0 +</pre></div> +<p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a mirror with +transformation instead of a field. The actual field is at the first +line: <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the +transformation will be evaluated and the result will be placed there +as the transformed text. So in this example, if you type "baz" in the +field, the transformed text will be "Baz". This example is also +available in the screencast.</p> +<p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document +title can be some text surrounded by "===" below and above. The "===" +should be at least as long as the text. So</p> +<div class="highlight"><pre>===== +Title +===== +</pre></div> +<p>is a valid title but</p> +<div class="highlight"><pre>=== +Title +=== +</pre></div> +<p>is not. Here's an snippet for rst title:</p> +<div class="highlight"><pre>${1:$(make-string (string-width text) ?\=)} +${1:Title} +${1:$(make-string (string-width text) ?\=)} + +$0 +</pre></div> +</div> +<div class="section" id="fields-with-transformations"> +<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 +field and also just before you exit the field.</p> +<p>The syntax is also a tiny bit different, so that the parser can +distinguish between fields and mirrors. In the following example</p> +<div class="highlight"><pre>#define "${1:mydefine$(upcase yas/text)}" +</pre></div> +<p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter +the field. As you type text, it gets filtered through the +transformation every time.</p> +<p>Note that to tell this kind of expression from a mirror with a +transformation, YASnippet needs extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the +transformation's <tt class="docutils literal"><span class="pre">$</span></tt>. If you don't want this extra-text, you can use +two <tt class="docutils literal"><span class="pre">$</span></tt>'s instead.</p> +<div class="highlight"><pre>#define "${1:$$(upcase yas/text)}" +</pre></div> +<p>Please note that as soon as a transformation takes place, it changes +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-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 +feature you can place a transformation in the primary field that lets +you select default values for it.</p> +<p>The <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> does this work for you. For example:</p> +<div class="highlight"><pre><div align="${2:$$(yas/choose-value '("right" "center" "left"))}"> + $0 +</div> +</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.</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:"Titel der Tour"}}% +\index{$1}% +\label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil '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="#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><div${1: id="${2:some_id}"}>$0</div> +</pre></div> +<p>This allows you to choose if you want to give this <tt class="docutils literal"><span class="pre">div</span></tt> an <tt class="docutils literal"><span class="pre">id</span></tt> +attribute. If you tab forward after expanding it will let you change +"some_id" to whatever you like. Alternatively, you can just press +<tt class="docutils literal"><span class="pre">C-d</span></tt> (which executes <tt class="docutils literal"><span class="pre">yas/skip-and-clear-or-delete-char</span></tt>) and go +straight to the exit marker.</p> +<p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the +beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it +performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p> +</div> +</div> +<div class="section" id="customizable-variables"> +<h1><a class="toc-backref" href="#id24">Customizable variables</a></h1> +<div class="section" id="yas-trigger-key"> +<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 +representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p> +</div> +<div class="section" id="yas-next-field-key"> +<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> +<p>Can also be a list of keys.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p> +</div> +<div class="section" id="yas-prev-field-key"> +<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> +<p>Can also be a list of keys.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">("<backtab>"</span> <span class="pre">"<S-tab>)"</span></tt>.</p> +</div> +<div class="section" id="yas-skip-and-clear-key"> +<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> +<p>Can also be a list of keys.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">"C-d"</span></tt>.</p> +</div> +<div class="section" id="yas-good-grace"> +<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 "[yas] error" is returned instead.</p> +</div> +<div class="section" id="yas-indent-line"> +<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> +<p>Another variable <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>, when non-nil +does exactly that :-).</p> +<p>To use the hard-coded indentation in your snippet template, set this +variable to <tt class="docutils literal"><span class="pre">fixed</span></tt>.</p> +<p>To control indentation on a per-snippet basis, see also the directive +<tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> in <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p> +<p>For backward compatibility with earlier versions of YASnippet, you can +also place a <tt class="docutils literal"><span class="pre">$></span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt> +will be executed there to indent the line. This only takes effect when +<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> is set to something other than <tt class="docutils literal"><span class="pre">'auto</span></tt>.</p> +<div class="highlight"><pre>for (${int i = 0}; ${i < 10}; ${++i}) +{$> +$0$> +}$> +</pre></div> +</div> +<div class="section" id="yas-wrap-around-region"> +<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 +evaluation.</p> +<p>Because on most systems starting to type deletes the currently region, +this works mostly with the <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> command.</p> +<p>However, when the value is of this variable is <tt class="docutils literal"><span class="pre">cua</span></tt> YASnippet will +additionally look-up any recently selected that you deleted by starting +typing. This allows you select a region, type a snippet key (deleting +the region), then press <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to see the deleted region +spring back to life inside your new snippet.</p> +</div> +<div class="section" id="yas-triggers-in-field"> +<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="#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="#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, +so let us know.</p> +</div> +</div> +<div class="section" id="importing-textmate-snippets"> +<h1><a class="toc-backref" href="#id35">Importing TextMate snippets</a></h1> +<p>There are a couple of tools that take TextMate's ".tmSnippet" xml +files and create YASnippet definitions:</p> +<blockquote> +<ul class="simple"> +<li><a class="reference external" href="http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py">a python script by Jeff Wheeler</a></li> +<li>a <a class="reference external" href="http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb">ruby tool</a> +, <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> adapted from <a class="reference external" href="http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/">Rob Christie's</a>, +which I have uploaded to the repository.</li> +</ul> +</blockquote> +<p>In this section, i'll shortly cover the <strong>second</strong> option.</p> +<p>Download the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> tool and the TextMate +bundle you're interested in.</p> +<div class="highlight"><pre>$ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb +$ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/ +</pre></div> +<p>Then invoke <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> like this:</p> +<div class="highlight"><pre>$ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist +</pre></div> +<p>You should end up with a <tt class="docutils literal"><span class="pre">html-mode</span></tt> subdir containing snippets +exported from textmate.</p> +<div class="highlight"><pre>$ tree html-mode # to view dir contents, if you have 'tree' installed +</pre></div> +<p>The <tt class="docutils literal"><span class="pre">-g</span></tt> is optional but helps the tool figure out the grouping. +According to <a class="reference external" href="snippet-organization.html">Organizing Snippets</a>, don't forget to touch +<tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> and <tt class="docutils literal"><span class="pre">.yas-ignore-filename-triggers</span></tt> inside the +<tt class="docutils literal"><span class="pre">html-mode</span></tt> dir.</p> +<p>Also try <tt class="docutils literal"><span class="pre">textmate_import.rb</span> <span class="pre">--help</span></tt> for a list of options.</p> +<p>Please note that snippet importation is not yet perfect. You'll +probably have some adjustments to some/many snippets. Please +contribute these adjustments to the google group or, better yet, patch +the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> to automatically perform them and submit +that.</p> +<!-- LocalWords: html YASnippet yas sourcecode pluskid init filenames filename --> +<!-- LocalWords: env varlist keybinding keymap rinari ifndef upcase endif --> +<!-- LocalWords: nondirectory autorelease aValue inline --> +</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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/snippet-development.rst b/emacs.d/lisp/yasnippet/doc/snippet-development.rst new file mode 100644 index 0000000..cf14e11 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-development.rst @@ -0,0 +1,660 @@ +================ +Writing snippets +================ + +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html + +.. contents:: + +Snippet development +=================== + +Quickly finding snippets +------------------------ + +There are some ways you can quickly find a snippet file: + +* ``M-x yas/new-snippet`` + + Prompts you for a snippet name, then tries to guess a suitable + directory to store it, prompting you for creation if it does not + exist. Finally, places you in a new buffer set to ``snippet-mode`` + so you can write 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``. The + directory searching logic is similar to ``M-x yas/new-snippet``. + +* ``M-x yas/visit-snippet-file`` + + Prompts you for possible snippet expansions like + ``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 +------------------------------------- + +There is a major mode ``snippet-mode`` to edit snippets. You can set +the buffer to this mode with ``M-x snippet-mode``. It provides +reasonably useful syntax highlighting. + +Two commands are defined in this mode: + +* ``M-x yas/load-snippet-buffer`` + + When editing a snippet, this loads the snippet into the correct + mode and menu. Bound to ``C-c C-c`` by default while in + ``snippet-mode``. + +* ``M-x yas/tryout-snippet`` + + When editing a snippet, this opens a new empty buffer, sets it to + the appropriate major mode and inserts the snippet there, so you + can see what it looks like. This is bound to ``C-c C-t`` while in + ``snippet-mode``. + +There are also *snippets for writing snippets*: ``vars``, ``$f`` and +``$m`` :-). + +File content +============ + +A file defining a snippet generally contains the template to be +expanded. + +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: + +.. sourcecode:: text + + #contributor : pluskid <pluskid@gmail.com> + #name : __...__ + # -- + __${init}__ + +Here's a list of currently supported directives: + +``# key:`` snippet abbrev +-------------------------- + +This is the probably the most important directive, it's the +abbreviation you type to expand a snippet just before hitting +``yas/trigger-key``. + +If you don't specify this it will default to the name of the file the +snippet is being loaded from, unless YASnippet is ignoring file names +as triggers (see ``yas/ignore-filenames-as-triggers`` in `Organizing +snippets`_), in which case this snippet +will not be expandable through the key mechanism. + +Sometimes the key of a snippet is non-ASCII or not valid filename +(e.g. contains ``/``). One can then define the ``key`` property which +will overwrite the filename as the key to expand the snippet. + +``# name:`` snippet name +------------------------ + +This is a one-line description of the snippet. It will be displayed in +the menu. It's a good idea to select a descriptive name for a +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 +will only be expanded when the condition code evaluate to some non-nil +value. + +See also ``yas/buffer-local-condition`` in `Expanding snippets`_ + + +``# 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 +too many snippets for a mode which will make the menu too +long. + +The ``# group:`` property only affect menu construction (See `the +YASnippet menu`_) and the same effect can be achieved by grouping +snippets into sub-directories and using the ``.yas-make-groups`` +special file (for this see `Organizing Snippets`_ + + +Refer to the bundled snippets for ``ruby-mode`` for examples on the +``# group:`` directive. Group can also be nested, e.g. ``control +structure.loops`` tells that the snippet is under the ``loops`` group +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. + +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 +your hard work. You can then use: + +.. sourcecode:: text + + # name : ASCII home + # expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil)) + # -- + welcome to my + X humble + / \ home, + / \ $0 + / \ + /-------\ + | | + | +-+ | + | | | | + +--+-+--+ + +``# binding:`` direct keybinding +--------------------------------- + +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 +for. + +Additionally a variable ``yas/prefix`` is set to to the prefix +argument you normally use for a command. This allows for small +variations on the same snippet, for example in this "html-mode" +snippet. + +.. sourcecode:: text + + #name : <p>...</p> + #binding: "C-c C-c C-m" + # -- + <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p> + +This binding will be recorded in the keymap ``html-mode-map``. To +expand a paragraph tag newlines, just press "C-u C-c C-c +C-m". Omitting the "C-u" will expand the paragraph tag without +newlines. + +To override the keymap choice based on the major mode name. Use a cons +cell where the first element specifies the name of the keymap where +you want to record the keybinding. + +.. sourcecode:: text + + #name : <p>...</p> + #binding: (rinari-minor-mode-map . "C-c C-c C-m") + # -- + <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p> + +**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 +--------------------------------------------------- + +This is optional and has no effect whatsoever on snippet +functionality, but it looks nice. + + +Template syntax +=============== + +The syntax of the snippet template is simple but powerful, very +similar to TextMate's. + +Plain Text +---------- + +Arbitrary text can be included as the content of a template. They are +usually interpreted as plain text, except ``$`` and `````. You need to +use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also +needed to be escaped as ``\\`` sometimes. + +Embedded Emacs-lisp code +------------------------ + +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. + +Here's an example for ``c-mode`` to calculate the header file guard +dynamically: + +.. sourcecode:: text + + #ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_} + #define $1 + + $0 + + #endif /* $1 */ + +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: + +.. sourcecode:: text + + for ($1;$2;$3) { + `yas/selected-text`$0 + } + +to "wrap" the selected region inside your recently inserted +snippet. Alternatively, you can also customize the variable +``yas/wrap-around-region`` to ``t`` which will do this automatically. + +Tab stop fields +--------------- + +Tab stops are fields that you can navigate back and forth by ``TAB`` +and ``S-TAB``. They are written by ``$`` followed with a +number. ``$0`` has the special meaning of the *exit point* of a +snippet. That is the last place to go when you've traveled all the +fields. Here's a typical example: + +.. sourcecode:: text + + <div$1> + $0 + </div> + +Placeholder fields +------------------ + +Tab stops can have default values -- a.k.a placeholders. The syntax is +like this: + +.. sourcecode:: text + + ${N:default value} + +They acts as the default value for a tab stop. But when you firstly +type at a tab stop, the default value will be replaced by your +typing. The number can be omitted if you don't want to create +`mirrors`_ or `transformations`_ for this field. + +.. _mirrors: + +Mirrors +------- + +We refer the tab stops with placeholders as a *field*. A field can have +mirrors. Its mirrors will get updated when you change the text of a +field. Here's an example: + +.. sourcecode:: text + + \begin{${1:enumerate}} + $0 + \end{$1} + +When you type ``"document"`` at ``${1:enumerate}``, the word +``"document"`` will also be inserted at ``\end{$1}``. The best +explanation is to see the screencast(`YouTube +<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ or `avi video +<http://yasnippet.googlecode.com/files/yasnippet.avi>`_). + +The tab stops with the same number to the field act as its mirrors. If +none of the tab stops has an initial value, the first one is selected +as the field and others mirrors. + +.. _transformations: + +Mirrors with transformations +---------------------------- + +If the value of an ``${n:``-construct starts with and contains ``$(``, +then it is interpreted as a mirror for field ``n`` with a +transformation. The mirror's text content is calculated according to +this transformation, which is Emacs-lisp code that gets evaluated in +an environment where the variable ``text`` (or ``yas/text``) is bound +to the text content (string) contained in the field ``n``.Here's an +example for Objective-C: + +.. sourcecode:: text + + - (${1:id})${2:foo} + { + return $2; + } + + - (void)set${2:$(capitalize text)}:($1)aValue + { + [$2 autorelease]; + $2 = [aValue retain]; + } + $0 + +Look at ``${2:$(capitalize text)}``, it is a mirror with +transformation instead of a field. The actual field is at the first +line: ``${2:foo}``. When you type text in ``${2:foo}``, the +transformation will be evaluated and the result will be placed there +as the transformed text. So in this example, if you type "baz" in the +field, the transformed text will be "Baz". This example is also +available in the screencast. + +Another example is for ``rst-mode``. In reStructuredText, the document +title can be some text surrounded by "===" below and above. The "===" +should be at least as long as the text. So + +.. sourcecode:: text + + ===== + Title + ===== + +is a valid title but + +.. sourcecode:: text + + === + Title + === + +is not. Here's an snippet for rst title: + +.. sourcecode:: text + + ${1:$(make-string (string-width text) ?\=)} + ${1:Title} + ${1:$(make-string (string-width text) ?\=)} + + $0 + +Fields with transformations +--------------------------- + +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 +field and also just before you exit the field. + +The syntax is also a tiny bit different, so that the parser can +distinguish between fields and mirrors. In the following example + +.. sourcecode:: text + + #define "${1:mydefine$(upcase yas/text)}" + +``mydefine`` gets automatically upcased to ``MYDEFINE`` once you enter +the field. As you type text, it gets filtered through the +transformation every time. + +Note that to tell this kind of expression from a mirror with a +transformation, YASnippet needs extra text between the ``:`` and the +transformation's ``$``. If you don't want this extra-text, you can use +two ``$``'s instead. + +.. sourcecode:: text + + #define "${1:$$(upcase yas/text)}" + +Please note that as soon as a transformation takes place, it changes +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 and other tricks +-------------------------------------------------- + +As mentioned, the field transformation is invoked just after you enter +the field, and with some useful variables bound, notably +``yas/field-modified-p`` and ``yas/moving-away-p``. Because of this +feature you can place a transformation in the primary field that lets +you select default values for it. + +The ``yas/choose-value`` does this work for you. For example: + +.. sourcecode:: text + + <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. + +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 +------------------------- + +From version 0.6 on, you can also have nested placeholders of the type: + +.. sourcecode:: text + + <div${1: id="${2:some_id}"}>$0</div> + +This allows you to choose if you want to give this ``div`` an ``id`` +attribute. If you tab forward after expanding it will let you change +"some_id" to whatever you like. Alternatively, you can just press +``C-d`` (which executes ``yas/skip-and-clear-or-delete-char``) and go +straight to the exit marker. + +By the way, ``C-d`` will only clear the field if you cursor is at the +beginning of the field *and* it hasn't been changed yet. Otherwise, it +performs the normal Emacs ``delete-char`` command. + +Customizable variables +====================== + +``yas/trigger-key`` +------------------- + +The key bound to ``yas/expand`` when function ``yas/minor-mode`` is +active. + +Value is a string that is converted to the internal Emacs key +representation using ``read-kbd-macro``. + +Default value is ``"TAB"``. + +``yas/next-field-key`` +---------------------- + +The key to navigate to next field when a snippet is active. + +Value is a string that is converted to the internal Emacs key +representation using ``read-kbd-macro``. + +Can also be a list of keys. + +Default value is ``"TAB"``. + +``yas/prev-field-key`` +---------------------- + +The key to navigate to previous field when a snippet is active. + +Value is a string that is converted to the internal Emacs key +representation using ``read-kbd-macro``. + +Can also be a list of keys. + +Default value is ``("<backtab>" "<S-tab>)"``. + +``yas/skip-and-clear-key`` +-------------------------- + +The key to clear the currently active field. + +Value is a string that is converted to the internal Emacs key +representation using ``read-kbd-macro``. + +Can also be a list of keys. + +Default value is ``"C-d"``. + +``yas/good-grace`` +------------------ + +If non-nil, don't raise errors in inline Emacs-lisp evaluation inside +snippet definitions. An error string "[yas] error" is returned instead. + +``yas/indent-line`` +------------------- + +The variable ``yas/indent-line`` controls the indenting. It is bound +to ``'auto`` by default, which causes your snippet to be indented +according to the mode of the buffer it was inserted in. + +Another variable ``yas/also-auto-indent-first-line``, when non-nil +does exactly that :-). + +To use the hard-coded indentation in your snippet template, set this +variable to ``fixed``. + +To control indentation on a per-snippet basis, see also the directive +``# expand-env:`` in `Writing Snippets`_. + +For backward compatibility with earlier versions of YASnippet, you can +also place a ``$>`` in your snippet, an ``(indent-according-to-mode)`` +will be executed there to indent the line. This only takes effect when +``yas/indent-line`` is set to something other than ``'auto``. + +.. sourcecode:: text + + for (${int i = 0}; ${i < 10}; ${++i}) + {$> + $0$> + }$> + +``yas/wrap-around-region`` +-------------------------- + +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 ```yas/selected-text``` inline +evaluation. + +Because on most systems starting to type deletes the currently +selected region, this works mostly for snippets with direct +keybindings or with the ``yas/insert-snippet`` command. + +However, when the value is of this variable is ``cua`` YASnippet will +additionally look-up any recently selected that you deleted by starting +typing. This allows you select a region, type a snippet key (deleting +the region), then press ``yas/trigger-key`` to see the deleted region +spring back to life inside your new snippet. + +``yas/triggers-in-field`` +-------------------------- + +If non-nil, ``yas/next-field-key`` can trigger stacked expansions, +that is a snippet expansion inside another snippet +expansion. Otherwise, ``yas/next-field-key`` just tries to move on to +the next field. + +``yas/snippet-revival`` +----------------------- + +Non-nil means re-activate snippet fields after undo/redo. + +``yas/after-exit-snippet-hook`` and ``yas/before-expand-snippet-hook`` +---------------------------------------------------------------------- + +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, +so let us know. + +Importing TextMate snippets +=========================== + +There are a couple of tools that take TextMate's ".tmSnippet" xml +files and create YASnippet definitions: + + * `a python script by Jeff Wheeler + <http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py>`_ + + * a `ruby tool + <http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb>`_ + , ``textmate_import.rb`` adapted from `Rob Christie's + <http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/>`_, + which I have uploaded to the repository. + +In this section, i'll shortly cover the **second** option. + +Download the ``textmate_import.rb`` tool and the TextMate +bundle you're interested in. + +.. sourcecode:: text + + $ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb + $ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/ + + +Then invoke ``textmate_import.rb`` like this: + +.. sourcecode:: text + + $ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist + +You should end up with a ``html-mode`` subdir containing snippets +exported from textmate. + +.. sourcecode:: text + + $ tree html-mode # to view dir contents, if you have 'tree' installed + +The ``-g`` is optional but helps the tool figure out the grouping. +According to `Organizing Snippets`_, don't forget to touch +``.yas-make-groups`` and ``.yas-ignore-filename-triggers`` inside the +``html-mode`` dir. + +Also try ``textmate_import.rb --help`` for a list of options. + +Please note that snippet importation is not yet perfect. You'll +probably have some adjustments to some/many snippets. Please +contribute these adjustments to the google group or, better yet, patch +the ``textmate_import.rb`` to automatically perform them and submit +that. + +.. LocalWords: html YASnippet yas sourcecode pluskid init filenames filename +.. LocalWords: env varlist keybinding keymap rinari ifndef upcase endif +.. LocalWords: nondirectory autorelease aValue inline diff --git a/emacs.d/lisp/yasnippet/doc/snippet-expansion.html b/emacs.d/lisp/yasnippet/doc/snippet-expansion.html new file mode 100644 index 0000000..2f0256c --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-expansion.html @@ -0,0 +1,432 @@ +<?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>Expanding snippets</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="expanding-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">Expanding 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="#triggering-expansion" id="id2">Triggering expansion</a><ul> +<li><a class="reference internal" href="#trigger-key" id="id3">Trigger key</a><ul> +<li><a class="reference internal" href="#fallback-bahaviour" id="id4">Fallback bahaviour</a></li> +</ul> +</li> +<li><a class="reference internal" href="#insert-at-point" id="id5">Insert at point</a></li> +<li><a class="reference internal" href="#snippet-keybinding" id="id6">Snippet keybinding</a></li> +<li><a class="reference internal" href="#expanding-from-the-menu" id="id7">Expanding from the menu</a></li> +<li><a class="reference internal" href="#expanding-with-hippie-expand" id="id8">Expanding with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></li> +<li><a class="reference internal" href="#expanding-from-emacs-lisp-code" id="id9">Expanding from emacs-lisp code</a></li> +</ul> +</li> +<li><a class="reference internal" href="#controlling-expansion" id="id10">Controlling expansion</a><ul> +<li><a class="reference internal" href="#eligible-snippets" id="id11">Eligible snippets</a></li> +<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="#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> +</li> +</ul> +</li> +<li><a class="reference internal" href="#customizable-variables" id="id18">Customizable Variables</a><ul> +<li><a class="reference internal" href="#yas-prompt-functions" id="id19"><tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></a></li> +<li><a class="reference internal" href="#yas-fallback-behavior" id="id20"><tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt></a></li> +<li><a class="reference internal" href="#yas-choose-keys-first" id="id21"><tt class="docutils literal"><span class="pre">yas/choose-keys-first</span></tt></a></li> +<li><a class="reference internal" href="#yas-choose-tables-first" id="id22"><tt class="docutils literal"><span class="pre">yas/choose-tables-first</span></tt></a></li> +<li><a class="reference internal" href="#yas-key-syntaxes" id="id23"><tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt></a></li> +</ul> +</li> +</ul> +</div> +<div class="section" id="triggering-expansion"> +<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 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 +"TAB"). 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> +<li>By using the keybinding associated with an active snippet. This also +requires <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active;</li> +<li>By expanding directly from the "YASnippet" menu in the menu-bar</li> +<li>By using hippie-expand</li> +<li>Expanding from emacs-lisp code</li> +</ul> +<div class="section" id="trigger-key"> +<h2><a class="toc-backref" href="#id3">Trigger key</a></h2> +<p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is enabled, the keybinding taken from +<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> will take effect.</p> +<p><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> invokes <tt class="docutils literal"><span class="pre">yas/expand</span></tt>, which tries to expand a +<em>snippet abbrev</em> (also known as <em>snippet key</em>) before point.</p> +<p>The default key is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>, however, you can freely set it to some +other key.</p> +<img align="left" alt="images/minor-mode-indicator.png" class="align-left" src="images/minor-mode-indicator.png" /> +<p>To enable the YASnippet minor mode in all buffers globally use the +command <tt class="docutils literal"><span class="pre">yas/global-mode</span></tt>.</p> +<p>When you use <tt class="docutils literal"><span class="pre">yas/global-mode</span></tt> you can also selectively disable +YASnippet in some buffers by setting the buffer-local variable +<tt class="docutils literal"><span class="pre">yas/dont-active</span></tt> in the buffer's mode hook.</p> +<p>Trouble when using or understanding the <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> is easily +the most controversial issue in YASsnippet. See the <a class="reference external" href="faq.html">FAQ</a>.</p> +<div class="section" id="fallback-bahaviour"> +<h3><a class="toc-backref" href="#id4">Fallback bahaviour</a></h3> +<p><tt class="docutils literal"><span class="pre">yas/fallback-behaviour</span></tt> is a customization variable bound to +<tt class="docutils literal"><span class="pre">'call-other-command</span></tt> by default. If <tt class="docutils literal"><span class="pre">yas/expand</span></tt> failed to find +any suitable snippet to expand, it will disable the minor mode +temporarily and find if there's any other command bound the +<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p> +<p>If found, the command will be called. Usually this works very well -- +when there's a snippet, expand it, otherwise, call whatever command +originally bind to the trigger key.</p> +<p>However, you can change this behavior by customizing the +<tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt> variable. If you set this variable to +<tt class="docutils literal"><span class="pre">'return-nil</span></tt>, it will return <tt class="docutils literal"><span class="pre">nil</span></tt> instead of trying to call the +<em>original</em> command when no snippet is found.</p> +</div> +</div> +<div class="section" id="insert-at-point"> +<h2><a class="toc-backref" href="#id5">Insert at point</a></h2> +<p>The command <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/insert-snippet</span></tt> lets you insert snippets at +point <em>for you current major mode</em>. It prompts you for the snippet +key first, and then for a snippet template if more than one template +exists for the same key.</p> +<p>The list presented contains the snippets that can be inserted at +point, according to the condition system. If you want to see all +applicable snippets for the major mode, prefix this command with +<tt class="docutils literal"><span class="pre">C-u</span></tt>.</p> +<p>The prompting methods used are again controlled by +<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>.</p> +</div> +<div class="section" id="snippet-keybinding"> +<h2><a class="toc-backref" href="#id6">Snippet keybinding</a></h2> +<p>See the section of the <tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> directive in <a class="reference external" href="snippet-development.html">Writing +Snippets</a>.</p> +</div> +<div class="section" id="expanding-from-the-menu"> +<h2><a class="toc-backref" href="#id7">Expanding from the menu</a></h2> +<p>See <a class="reference external" href="snippet-menu.html">the YASnippet Menu</a>.</p> +</div> +<div class="section" id="expanding-with-hippie-expand"> +<h2><a class="toc-backref" href="#id8">Expanding with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></h2> +<p>To integrate with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt>, just put +<tt class="docutils literal"><span class="pre">yas/hippie-try-expand</span></tt> in +<tt class="docutils literal"><span class="pre">hippie-expand-try-functions-list</span></tt>. This probably makes more sense +when placed at the top of the list, but it can be put anywhere you +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 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 +information.</p> +</div> +</div> +<div class="section" id="controlling-expansion"> +<h1><a class="toc-backref" href="#id10">Controlling expansion</a></h1> +<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 the current cursor position.</p> +<p>In particular, the following things matter:</p> +<ul> +<li><p class="first">Currently loaded snippets tables</p> +<p>These are loaded from a directory hierarchy in your file system. See +<a class="reference external" href="snippet-organization.html">Organizing Snippets</a>. They are named after major modes like +<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 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 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, so using a hook is a good +idea.</p> +</li> +</ul> +<div class="highlight"><pre><span style="color: #408080; font-style: italic">;; When entering rinari-minor-mode, consider also the snippets in the</span> +<span style="color: #408080; font-style: italic">;; snippet table "rails-mode"</span> +(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">'rinari-minor-mode-hook</span> + <span style="color: #0000FF">#'</span>(<span style="color: #008000; font-weight: bold">lambda</span> () + (<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/mode-symbol</span> <span style="color: #19177C">'rails-mode</span>))) +</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 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> +<div class="section" id="the-condition-system"> +<h2><a class="toc-backref" href="#id12">The condition system</a></h2> +<p>Consider this scenario: you are an old Emacs hacker. You like the +abbrev-way and set <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to <tt class="docutils literal"><span class="pre">"SPC"</span></tt>. However, +you don't want <tt class="docutils literal"><span class="pre">if</span></tt> to be expanded as a snippet when you are typing +in a comment block or a string (e.g. in <tt class="docutils literal"><span class="pre">python-mode</span></tt>).</p> +<p>If you use the <tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition</span> <span class="pre">:</span></tt> directive (see <a class="reference external" href="snippet-development.html">Writing Snippets</a>) +you could just specify the condition for <tt class="docutils literal"><span class="pre">if</span></tt> to be <tt class="docutils literal"><span class="pre">(not</span> +<span class="pre">(python-in-string/comment))</span></tt>. But how about <tt class="docutils literal"><span class="pre">while</span></tt>, <tt class="docutils literal"><span class="pre">for</span></tt>, +etc. ? Writing the same condition for all the snippets is just +boring. So has a buffer local variable +<tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt>. You can set this variable to <tt class="docutils literal"><span class="pre">(not</span> +<span class="pre">(python-in-string/comment))</span></tt> in <tt class="docutils literal"><span class="pre">python-mode-hook</span></tt>.</p> +<p>Then, what if you really want some particular snippet to expand even +inside a comment? This is also possible! But let's stop telling the +story and look at the rules:</p> +<ul class="simple"> +<li>If <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> evaluate to nil, no snippets will +be considered for expansion.</li> +<li>If it evaluates to the a <em>cons cell</em> where the <tt class="docutils literal"><span class="pre">car</span></tt> is the symbol +<tt class="docutils literal"><span class="pre">require-snippet-condition</span></tt> and the <tt class="docutils literal"><span class="pre">cdr</span></tt> is a symbol (let's +call it <tt class="docutils literal"><span class="pre">requirement</span></tt>), then:<ul> +<li>Snippets having no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> directive won't be considered;</li> +<li>Snippets with conditions that evaluate to nil (or produce an +error) won't be considered;</li> +<li>If the snippet has a condition that evaluates to non-nil (let's +call it <tt class="docutils literal"><span class="pre">result</span></tt>):<ul> +<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">t</span></tt>, the snippet is ready to be +expanded;</li> +<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">eq</span></tt> to <tt class="docutils literal"><span class="pre">result</span></tt>, the snippet is ready +to be expanded;</li> +<li>Otherwise the snippet won't be considered.</li> +</ul> +</li> +</ul> +</li> +<li>If it evaluates to the symbol <tt class="docutils literal"><span class="pre">always</span></tt>, all snippets are +considered for expansion, regardless of any conditions.</li> +<li>If it evaluate to <tt class="docutils literal"><span class="pre">t</span></tt> or some other non-nil value:<ul> +<li>If the snippet has no condition, or has a condition that evaluate +to non-nil, it is ready to be expanded.</li> +<li>Otherwise, it won't be considered.</li> +</ul> +</li> +</ul> +<p>In the mentioned scenario, set <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> like +this</p> +<div class="highlight"><pre>(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">'python-mode-hook</span> + <span style="color: #666666">'</span>(<span style="color: #008000; font-weight: bold">lambda</span> () + (<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/buffer-local-condition</span> + <span style="color: #666666">'</span>(<span style="color: #008000; font-weight: bold">if</span> (<span style="color: #19177C">python-in-string/comment</span>) + <span style="color: #666666">'</span>(<span style="color: #19177C">require-snippet-condition</span> <span style="color: #666666">.</span> <span style="color: #19177C">force-in-comment</span>) + <span style="color: #880000">t</span>)))) +</pre></div> +<p>... and specify the condition for a snippet that you're going to +expand in comment to be evaluated to the symbol +<tt class="docutils literal"><span class="pre">force-in-comment</span></tt>. Then it can be expanded as you expected, while +other snippets like <tt class="docutils literal"><span class="pre">if</span></tt> still can't expanded in comment.</p> +</div> +<div class="section" id="multiples-snippet-with-the-same-key"> +<h2><a class="toc-backref" href="#id13">Multiples snippet with the same key</a></h2> +<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 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> +<div class="highlight"><pre>(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/prompt-functions</span> <span style="color: #666666">'</span>(<span style="color: #19177C">yas/x-prompt</span> <span style="color: #19177C">yas/dropdown-prompt</span>)) +</pre></div> +<p>Currently there are some alternatives solution with YASnippet.</p> +<img align="right" alt="images/x-menu.png" class="align-right" src="images/x-menu.png" /> +<div class="section" id="use-the-x-window-system"> +<h3><a class="toc-backref" href="#id14">Use the X window system</a></h3> +<p>The function <tt class="docutils literal"><span class="pre">yas/x-prompt</span></tt> can be used to show a popup menu for you +to select. This menu will be part of you native window system widget, +which means:</p> +<ul class="simple"> +<li>It usually looks beautiful. E.g. when you compile Emacs with gtk +support, this menu will be rendered with your gtk theme.</li> +<li>Emacs have little control over it. E.g. you can't use <tt class="docutils literal"><span class="pre">C-n</span></tt>, +<tt class="docutils literal"><span class="pre">C-p</span></tt> to navigate.</li> +<li>This function can't be used when in a terminal.</li> +</ul> +<img align="right" alt="images/ido-menu.png" class="align-right" src="images/ido-menu.png" /> +</div> +<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> +<img align="right" alt="images/dropdown-menu.png" class="align-right" src="images/dropdown-menu.png" /> +</div> +<div class="section" id="use-dropdown-menu-el"> +<h3><a class="toc-backref" href="#id16">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></h3> +<p>The function <tt class="docutils literal"><span class="pre">yas/dropdown-prompt</span></tt> can also be placed in the +<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> list.</p> +<p>This works in both window system and terminal and is customizable, you +can use <tt class="docutils literal"><span class="pre">C-n</span></tt>, <tt class="docutils literal"><span class="pre">C-p</span></tt> to navigate, <tt class="docutils literal"><span class="pre">q</span></tt> to quit and even press +<tt class="docutils literal"><span class="pre">6</span></tt> as a shortcut to select the 6th candidate.</p> +</div> +<div class="section" id="roll-your-own"> +<h3><a class="toc-backref" href="#id17">Roll your own</a></h3> +<p>See below for the documentation on variable <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></p> +</div> +</div> +</div> +<div class="section" id="customizable-variables"> +<h1><a class="toc-backref" href="#id18">Customizable Variables</a></h1> +<div class="section" id="yas-prompt-functions"> +<h2><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></a></h2> +<p>You can write a function and add it to the <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> +list. These functions are called with the following arguments:</p> +<ul class="simple"> +<li>PROMPT: A string to prompt the user;</li> +<li>CHOICES: A list of strings or objects;</li> +<li>optional DISPLAY-FN : A function. When applied to each of the +objects in CHOICES it will return a string;</li> +</ul> +<p>The return value of any function you put here should be one of +the objects in CHOICES, properly formatted with DISPLAY-FN (if +that is passed).</p> +<ul class="simple"> +<li>To signal that your particular style of prompting is unavailable at +the moment, you can also have the function return nil.</li> +<li>To signal that the user quit the prompting process, you can signal +<tt class="docutils literal"><span class="pre">quit</span></tt> with <tt class="docutils literal"><span class="pre">(signal</span> <span class="pre">'quit</span> <span class="pre">"user</span> <span class="pre">quit!")</span></tt></li> +</ul> +</div> +<div class="section" id="yas-fallback-behavior"> +<h2><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt></a></h2> +<p>How to act when <tt class="docutils literal"><span class="pre">yas/expand</span></tt> does <em>not</em> expand a snippet.</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">call-other-command</span></tt> means try to temporarily disable YASnippet and</dt> +<dd>call the next command bound to <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</dd> +</dl> +<p><tt class="docutils literal"><span class="pre">return-nil</span></tt> means return nil. (i.e. do nothing)</p> +<p>An entry (apply COMMAND . ARGS) means interactively call COMMAND, if +ARGS is non-nil, call COMMAND non-interactively with ARGS as +arguments.</p> +</div> +<div class="section" id="yas-choose-keys-first"> +<h2><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">yas/choose-keys-first</span></tt></a></h2> +<p>If non-nil, prompt for snippet key first, then for template.</p> +<p>Otherwise prompts for all possible snippet names.</p> +<p>This affects <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> and <tt class="docutils literal"><span class="pre">yas/visit-snippet-file</span></tt>.</p> +</div> +<div class="section" id="yas-choose-tables-first"> +<h2><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">yas/choose-tables-first</span></tt></a></h2> +<p>If non-nil, and multiple eligible snippet tables, prompts user for +tables first.</p> +<p>Otherwise, user chooses between the merging together of all +eligible tables.</p> +<p>This affects <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, <tt class="docutils literal"><span class="pre">yas/visit-snippet-file</span></tt></p> +</div> +<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">bar</span></tt>, <tt class="docutils literal"><span class="pre">foo_bar</span></tt>, <tt class="docutils literal"><span class="pre">"#foo_bar"</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">"#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">("w"</span> <span class="pre">"w_"</span> <span class="pre">"w_."</span> <span class="pre">"^</span> <span class="pre">")</span></tt>. Which means search the +following thing until found one:</p> +<ul class="simple"> +<li>a word.</li> +<li>a symbol. In lisp, <tt class="docutils literal"><span class="pre">-</span></tt> and <tt class="docutils literal"><span class="pre">?</span></tt> can all be part of a symbol.</li> +<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 want to understand +how Emacs's syntax rules work...</p> +</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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/snippet-expansion.rst b/emacs.d/lisp/yasnippet/doc/snippet-expansion.rst new file mode 100644 index 0000000..c251173 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-expansion.rst @@ -0,0 +1,406 @@ +================== +Expanding snippets +================== + +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html + +.. contents:: + + +Triggering expansion +==================== + +You can use YASnippet to expand snippets in different ways: + +* 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* + require ``yas/minor-mode`` to be active. + +* By using the keybinding associated with an active snippet. This also + requires ``yas/minor-mode`` to be active; + +* By expanding directly from the "YASnippet" menu in the menu-bar + +* By using hippie-expand + +* Expanding from emacs-lisp code + +Trigger key +----------- + +When ``yas/minor-mode`` is enabled, the keybinding taken from +``yas/trigger-key`` will take effect. + +``yas/trigger-key`` invokes ``yas/expand``, which tries to expand a +*snippet abbrev* (also known as *snippet key*) before point. + +The default key is ``"TAB"``, however, you can freely set it to some +other key. + +.. image:: images/minor-mode-indicator.png + :align: left + +To enable the YASnippet minor mode in all buffers globally use the +command ``yas/global-mode``. + +When you use ``yas/global-mode`` you can also selectively disable +YASnippet in some buffers by setting the buffer-local variable +``yas/dont-active`` in the buffer's mode hook. + +Trouble when using or understanding the ``yas/trigger-key`` is easily +the most controversial issue in YASsnippet. See the `FAQ <faq.html>`_. + +Fallback bahaviour +~~~~~~~~~~~~~~~~~~ + +``yas/fallback-behaviour`` is a customization variable bound to +``'call-other-command`` by default. If ``yas/expand`` failed to find +any suitable snippet to expand, it will disable the minor mode +temporarily and find if there's any other command bound the +``yas/trigger-key``. + +If found, the command will be called. Usually this works very well -- +when there's a snippet, expand it, otherwise, call whatever command +originally bind to the trigger key. + +However, you can change this behavior by customizing the +``yas/fallback-behavior`` variable. If you set this variable to +``'return-nil``, it will return ``nil`` instead of trying to call the +*original* command when no snippet is found. + +Insert at point +--------------- + +The command ``M-x yas/insert-snippet`` lets you insert snippets at +point *for you current major mode*. It prompts you for the snippet +key first, and then for a snippet template if more than one template +exists for the same key. + +The list presented contains the snippets that can be inserted at +point, according to the condition system. If you want to see all +applicable snippets for the major mode, prefix this command with +``C-u``. + +The prompting methods used are again controlled by +``yas/prompt-functions``. + +Snippet keybinding +------------------ + +See the section of the ``# binding:`` directive in `Writing +Snippets`_. + + +Expanding from the menu +----------------------- + +See `the YASnippet Menu`_. + +Expanding with ``hippie-expand`` +---------------------------------- + +To integrate with ``hippie-expand``, just put +``yas/hippie-try-expand`` in +``hippie-expand-try-functions-list``. This probably makes more sense +when placed at the top of the list, but it can be put anywhere you +prefer. + +Expanding from emacs-lisp code +------------------------------ + +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, 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 + + (yas/expand-snippet template) + +See the internal documentation on ``yas/expand-snippet`` for more +information. + +Controlling expansion +===================== + +Eligible snippets +----------------- + +YASnippet does quite a bit of filtering to find out which snippets are +eligible for expanding at the current cursor position. + +In particular, the following things matter: + +* Currently loaded snippets tables + + These are loaded from a directory hierarchy in your file system. See + `Organizing Snippets`_. They are named after major modes like + ``html-mode``, ``ruby-mode``, etc... + +* Major mode of the current buffer + + 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 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 + + 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 ``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, so using a hook is a good + idea. + +.. sourcecode:: common-lisp + + ;; When entering rinari-minor-mode, consider also the snippets in the + ;; snippet table "rails-mode" + (add-hook 'rinari-minor-mode-hook + #'(lambda () + (setq yas/mode-symbol 'rails-mode))) + +* Buffer-local ``yas/buffer-local-condition`` variable + + 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 +-------------------- + +Consider this scenario: you are an old Emacs hacker. You like the +abbrev-way and set ``yas/trigger-key`` to ``"SPC"``. However, +you don't want ``if`` to be expanded as a snippet when you are typing +in a comment block or a string (e.g. in ``python-mode``). + +If you use the ``# condition :`` directive (see `Writing Snippets`_) +you could just specify the condition for ``if`` to be ``(not +(python-in-string/comment))``. But how about ``while``, ``for``, +etc. ? Writing the same condition for all the snippets is just +boring. So has a buffer local variable +``yas/buffer-local-condition``. You can set this variable to ``(not +(python-in-string/comment))`` in ``python-mode-hook``. + +Then, what if you really want some particular snippet to expand even +inside a comment? This is also possible! But let's stop telling the +story and look at the rules: + +* If ``yas/buffer-local-condition`` evaluate to nil, no snippets will + be considered for expansion. + +* If it evaluates to the a *cons cell* where the ``car`` is the symbol + ``require-snippet-condition`` and the ``cdr`` is a symbol (let's + call it ``requirement``), then: + + * Snippets having no ``# condition:`` directive won't be considered; + + * Snippets with conditions that evaluate to nil (or produce an + error) won't be considered; + + * If the snippet has a condition that evaluates to non-nil (let's + call it ``result``): + + * If ``requirement`` is ``t``, the snippet is ready to be + expanded; + + * If ``requirement`` is ``eq`` to ``result``, the snippet is ready + to be expanded; + + * Otherwise the snippet won't be considered. + +* If it evaluates to the symbol ``always``, all snippets are + considered for expansion, regardless of any conditions. + +* If it evaluate to ``t`` or some other non-nil value: + + * If the snippet has no condition, or has a condition that evaluate + to non-nil, it is ready to be expanded. + + * Otherwise, it won't be considered. + +In the mentioned scenario, set ``yas/buffer-local-condition`` like +this + +.. sourcecode:: common-lisp + + (add-hook 'python-mode-hook + '(lambda () + (setq yas/buffer-local-condition + '(if (python-in-string/comment) + '(require-snippet-condition . force-in-comment) + t)))) + +... and specify the condition for a snippet that you're going to +expand in comment to be evaluated to the symbol +``force-in-comment``. Then it can be expanded as you expected, while +other snippets like ``if`` still can't expanded in comment. + +Multiples snippet with the same key +----------------------------------- + +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 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 +emacs-file: + +.. sourcecode:: common-lisp + + (setq yas/prompt-functions '(yas/x-prompt yas/dropdown-prompt)) + +Currently there are some alternatives solution with YASnippet. + +.. image:: images/x-menu.png + :align: right + +Use the X window system +~~~~~~~~~~~~~~~~~~~~~~~ + +The function ``yas/x-prompt`` can be used to show a popup menu for you +to select. This menu will be part of you native window system widget, +which means: + +* It usually looks beautiful. E.g. when you compile Emacs with gtk + support, this menu will be rendered with your gtk theme. +* Emacs have little control over it. E.g. you can't use ``C-n``, + ``C-p`` to navigate. +* This function can't be used when in a terminal. + +.. image:: images/ido-menu.png + :align: right + +Minibuffer prompting +~~~~~~~~~~~~~~~~~~~~ + +You can use functions ``yas/completing-prompt`` for the classic emacs +completion method or ``yas/ido-prompt`` for a much nicer looking +method. The best way is to try it. This works in a terminal. + +.. image:: images/dropdown-menu.png + :align: right + +Use ``dropdown-menu.el`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +The function ``yas/dropdown-prompt`` can also be placed in the +``yas/prompt-functions`` list. + +This works in both window system and terminal and is customizable, you +can use ``C-n``, ``C-p`` to navigate, ``q`` to quit and even press +``6`` as a shortcut to select the 6th candidate. + +Roll your own +~~~~~~~~~~~~~ + +See below for the documentation on variable ``yas/prompt-functions`` + +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: + +* PROMPT: A string to prompt the user; + +* CHOICES: A list of strings or objects; + +* optional DISPLAY-FN : A function. When applied to each of the + objects in CHOICES it will return a string; + +The return value of any function you put here should be one of +the objects in CHOICES, properly formatted with DISPLAY-FN (if +that is passed). + +* To signal that your particular style of prompting is unavailable at + the moment, you can also have the function return nil. + +* To signal that the user quit the prompting process, you can signal + ``quit`` with ``(signal 'quit "user quit!")`` + +``yas/fallback-behavior`` +------------------------- + +How to act when ``yas/expand`` does *not* expand a snippet. + +``call-other-command`` means try to temporarily disable YASnippet and + call the next command bound to ``yas/trigger-key``. + +``return-nil`` means return nil. (i.e. do nothing) + +An entry (apply COMMAND . ARGS) means interactively call COMMAND, if +ARGS is non-nil, call COMMAND non-interactively with ARGS as +arguments. + +``yas/choose-keys-first`` +------------------------- + +If non-nil, prompt for snippet key first, then for template. + +Otherwise prompts for all possible snippet names. + +This affects ``yas/insert-snippet`` and ``yas/visit-snippet-file``. + +``yas/choose-tables-first`` +--------------------------- + +If non-nil, and multiple eligible snippet tables, prompts user for +tables first. + +Otherwise, user chooses between the merging together of all +eligible tables. + +This affects ``yas/insert-snippet``, ``yas/visit-snippet-file`` + +``yas/key-syntaxes`` +-------------------- + +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 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 +default value is ``("w" "w_" "w_." "^ ")``. Which means search the +following thing until found one: + +* a word. +* a symbol. In lisp, ``-`` and ``?`` can all be part of a symbol. +* 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 want to understand +how Emacs's syntax rules work... + + diff --git a/emacs.d/lisp/yasnippet/doc/snippet-menu.html b/emacs.d/lisp/yasnippet/doc/snippet-menu.html new file mode 100644 index 0000000..ad9811b --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-menu.html @@ -0,0 +1,141 @@ +<?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>YASnippet menu</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="yasnippet-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">YASnippet 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> + <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-from-menu" id="id1">Loading snippets from menu</a></li> +<li><a class="reference internal" href="#snippet-menu-behavior" id="id2">Snippet menu behavior</a></li> +<li><a class="reference internal" href="#controlling-indenting" id="id3">Controlling indenting</a></li> +<li><a class="reference internal" href="#prompting-method" id="id4">Prompting method</a></li> +<li><a class="reference internal" href="#misc" id="id5">Misc</a></li> +</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> +<p>In this menu, you can find</p> +<ul class="simple"> +<li>The currently loaded snippet definitions, organized by major mode, +and optional grouping.</li> +<li>A rundown of the most common commands, (followed by their +keybindings) including commands to load directories and reload all +snippet definitions.</li> +<li>A series of submenus for customizing and exploring YASnippet +behavior.</li> +</ul> +<img align="right" alt="images/menu-1.png" class="align-right" src="images/menu-1.png" /> +<div class="section" id="loading-snippets-from-menu"> +<h1><a class="toc-backref" href="#id1">Loading snippets from menu</a></h1> +<p>Invoking "Load snippets..." from the menu invokes +<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> and prompts you for a snippet directory +hierarchy to load.</p> +<p>Also useful is the "Reload all" options which uncondionally reloads +all the snippets directories defined in <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and +rebuilds the menus.</p> +</div> +<div class="section" id="snippet-menu-behavior"> +<h1><a class="toc-backref" href="#id2">Snippet menu behavior</a></h1> +<p>YASnippet will list in this section all the loaded snippet definitions +organized by snippet table name.</p> +<p>You can use this section to explore currently loaded snippets. If you +click on one of them, the default behavior is to expand it, +unconditionally, inside the current buffer.</p> +<p>You can however, customize variable <tt class="docutils literal"><span class="pre">yas/visit-from-menu</span></tt> to be +<tt class="docutils literal"><span class="pre">t</span></tt> which will take you to the snippet definition file when you +select it from the menu.</p> +<p>If you want the menu show only snippet tables whose name corresponds +to a "real" major mode. You do this by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to +<tt class="docutils literal"><span class="pre">'real-modes</span></tt>.</p> +<p>Finally, to have the menu show only the tables for the currently +active mode, set <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to <tt class="docutils literal"><span class="pre">abbreviate</span></tt>.</p> +<p>These customizations can also be found in the menu itself, under the +"Snippet menu behavior" submenu.</p> +</div> +<div class="section" id="controlling-indenting"> +<h1><a class="toc-backref" href="#id3">Controlling indenting</a></h1> +<p>The "Indenting" submenu contains options to control the values of +<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> and <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>. See +<a class="reference external" href="snippet-development.html">Writing snippets</a> .</p> +</div> +<div class="section" id="prompting-method"> +<h1><a class="toc-backref" href="#id4">Prompting method</a></h1> +<p>The "Prompting method" submenu contains options to control the value +of <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>. See <a class="reference external" href="snippet-expansion.html">Expanding snippets</a> .</p> +</div> +<div class="section" id="misc"> +<h1><a class="toc-backref" href="#id5">Misc</a></h1> +<p>The "Misc" submenu contains options to control the values of more +variables.</p> +</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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/snippet-menu.rst b/emacs.d/lisp/yasnippet/doc/snippet-menu.rst new file mode 100644 index 0000000..a40c5a8 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-menu.rst @@ -0,0 +1,85 @@ +============== +YASnippet menu +============== + +.. contents:: + +When ``yas/minor-mode`` is active, YASnippet will setup a menu just +after the "Buffers" menu in the menubar. + +In this menu, you can find + +* The currently loaded snippet definitions, organized by major mode, + and optional grouping. + +* A rundown of the most common commands, (followed by their + keybindings) including commands to load directories and reload all + snippet definitions. + +* A series of submenus for customizing and exploring YASnippet + behavior. + +.. image:: images/menu-1.png + :align: right + +Loading snippets from menu +-------------------------- + +Invoking "Load snippets..." from the menu invokes +``yas/load-directory`` and prompts you for a snippet directory +hierarchy to load. + +Also useful is the "Reload all" options which uncondionally reloads +all the snippets directories defined in ``yas/root-directory`` and +rebuilds the menus. + +Snippet menu behavior +--------------------- + +YASnippet will list in this section all the loaded snippet definitions +organized by snippet table name. + +You can use this section to explore currently loaded snippets. If you +click on one of them, the default behavior is to expand it, +unconditionally, inside the current buffer. + +You can however, customize variable ``yas/visit-from-menu`` to be +``t`` which will take you to the snippet definition file when you +select it from the menu. + +If you want the menu show only snippet tables whose name corresponds +to a "real" major mode. You do this by setting ``yas/use-menu`` to +``'real-modes``. + +Finally, to have the menu show only the tables for the currently +active mode, set ``yas/use-menu`` to ``abbreviate``. + +These customizations can also be found in the menu itself, under the +"Snippet menu behavior" submenu. + + +Controlling indenting +--------------------- + +The "Indenting" submenu contains options to control the values of +``yas/indent-line`` and ``yas/also-auto-indent-first-line``. See +`Writing snippets <snippet-development.html>`_ . + +Prompting method +---------------- + +The "Prompting method" submenu contains options to control the value +of ``yas/prompt-functions``. See `Expanding snippets <snippet-expansion.html>`_ . + +Misc +---- + +The "Misc" submenu contains options to control the values of more +variables. + + + + + + + diff --git a/emacs.d/lisp/yasnippet/doc/snippet-organization.html b/emacs.d/lisp/yasnippet/doc/snippet-organization.html new file mode 100644 index 0000000..efb3a2e --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-organization.html @@ -0,0 +1,292 @@ +<?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>Organizing snippets</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</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="#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="#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="#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@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/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">"~/emacs.d/mysnippets"</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 "~/emacs.d/mysnippets" +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> +<p>You can make this variable a list and store more items into it:</p> +<div class="highlight"><pre><span style="color: #408080; font-style: italic">;; Develop in ~/emacs.d/mysnippets, but also</span> +<span style="color: #408080; font-style: italic">;; try out snippets in ~/Downloads/interesting-snippets</span> +(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/root-directory</span> <span style="color: #666666">'</span>(<span style="color: #BA2121">"~/emacs.d/mysnippets"</span> + <span style="color: #BA2121">"~/Downloads/interesting-snippets"</span>)) + +<span style="color: #408080; font-style: italic">;; Map `yas/load-directory' to every element</span> +(<span style="color: #008000">mapc</span> <span style="color: #19177C">'yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>) +</pre></div> +<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, "~/emacs.d/mysnippets".</p> +</div> +<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/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 +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 internal" href="#yasnippet-bundle">YASnippet bundle</a>).</p> +<div class="section" id="nested-organization"> +<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 +. +`-- text-mode + |-- cc-mode + | |-- c-mode + | | `-- printf + | |-- for + | |-- java-mode + | | `-- println + | `-- while + |-- email + |-- perl-mode + | |-- cperl-mode + | `-- for + `-- 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 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="#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 +| |-- .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 +</pre></div> +</div> +<div class="section" id="the-yas-make-groups-file"> +<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 +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"><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="#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> +<p>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 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'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 +</pre></div> +</div> +</div> +<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> +<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"><span class="pre">yasnippet.el</span></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> <span class="pre">RET</span> <span class="pre">yas/define-snippets</span> <span class="pre">RET</span></tt></li> +<li><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-function</span> <span class="pre">RET</span> <span class="pre">yas/compile-bundle</span> <span class="pre">RET</span></tt>.</li> +</ul> +</div> +<div class="section" id="customizable-variables"> +<h1><a class="toc-backref" href="#id10">Customizable variables</a></h1> +<div class="section" id="yas-root-directory"> +<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>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="#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> +<!-- 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> +</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> +</body> +</html> diff --git a/emacs.d/lisp/yasnippet/doc/snippet-organization.rst b/emacs.d/lisp/yasnippet/doc/snippet-organization.rst new file mode 100644 index 0000000..dc7018c --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-organization.rst @@ -0,0 +1,253 @@ +=================== +Organizing snippets +=================== + +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html + +.. contents:: + +Loading snippets +================ + +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 more directories. + +Once these directories are in place reference them in the variable +``yas/root-directory`` and 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 in section `Writing +Snippets`_. + +You can make this variable a list and store more items into it: + +.. sourcecode:: common-lisp + + ;; 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) + +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 +=================== + +Once you've setup ``yas/root-directory`` , you can store snippets +inside sub-directories of these directories. + +Snippet definitions are put in plain text files. They are arranged by +sub-directories, and the snippet tables are named after these directories. + +The name corresponds to the Emacs mode where you want expansion to +take place. For example, snippets for ``c-mode`` are put in the +``c-mode`` sub-directory. You can also skip snippet storage altogether +and use the bundle (see `YASnippet 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 + +A parent directory acts as a *parent table* of any of its +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``. + +.. image:: images/menu-parent.png + :align: right + +The ``.yas-parents`` file +------------------------------ + +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 + + $ 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/menu-groups.png + :align: right + +If you place an empty plain text file ``.yas-make-groups`` inside one +of the mode directories, the names of these sub-directories are +considered groups of snippets and `The YASnippet 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`_. + +.. sourcecode:: text + + $ tree ruby-mode/ + ruby-mode/ + |-- .yas-make-groups + |-- collections + | |-- each + | `-- ... + |-- control structure + | |-- forin + | `-- ... + |-- definitions + | `-- ... + `-- general + `-- ... + + +Using plain file names +---------------------- + +Normally, file names act as the snippet expansion *abbreviation* (also +known as the *snippet key* or *snippet trigger*, see `Expanding +Snippets`_). + +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 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 + + +YASnippet 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. + +However, this might slow down the Emacs start-up speed if you have many +snippets. You can use ``yas/define-snippets`` to define a bunch of +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 uses ``yas/define-snippets`` to +define snippets. This avoids the IO and parsing overhead when loading +snippets. + +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. + +See the internal documentation for these functions + +* ``M-x describe-function RET yas/define-snippets RET`` +* ``M-x describe-function RET yas/compile-bundle RET``. + +Customizable variables +====================== + +``yas/root-directory`` +---------------------- + +Root directory that stores the snippets for each major mode. + +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`` +------------------------------------ + +If non-nil, don't derive tab triggers from filenames. + +This means a snippet without a ``# key:`` directive wont have a tab +trigger. + +.. LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl +.. LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el +.. LocalWords: rjs RET diff --git a/emacs.d/lisp/yasnippet/doc/styles.css b/emacs.d/lisp/yasnippet/doc/styles.css new file mode 100644 index 0000000..e0afa09 --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/styles.css @@ -0,0 +1,142 @@ +/* Base stylesheet from Docutils distribution */ +@import url(html4css1.css); + +/* Theme stylesheet */ +body { + background: #EDF5FA; + margin: 0; + padding: 0; +} +.clear-block { + display: block; +} +#header-region { + background: #D2E6F3 url(images/bg-navigation.png) repeat-x scroll 50% 100%;; + min-height: 1em; +} +#wrapper { + background: #EDF5FA url(images/body.png) repeat-x scroll 50% 0pt; +} +#container { + margin: 0pt auto; + padding: 0pt 20px; +} +#header { + height: 80px; +} +#sidebar-left { + float: left; + margin: 60px 0pt 5em; + position: relative; + width: 210px; + z-index: 2; +} +#center #squeeze { + background: #FFFFFF url(images/bg-content.png) repeat-x scroll 50% 0pt; + position: relative; +} +#center .right-corner { + background: transparent url(images/bg-content-right.png) no-repeat scroll 100% 0pt; + left: 10px; + position: relative; +} +#center .left-corner { + background: transparent url(images/bg-content-left.png) no-repeat scroll 0pt 0pt; + left: -10px; + margin-left: -10px; + min-height: 400px; + padding: 60px 25px 5em 35px; + position: relative; +} +ul.primary-links { + float: right; + margin: 0px; + padding: 0px; + position: relative; + z-index: 4; +} +ul.primary-links li { + list-style-type: none; + float: left; + margin: 0px; + font-size: 0.8em; + padding: 0px; +} +ul.primary-links li a { + background: transparent url(images/bg-navigation-item.png) no-repeat scroll 50% 0pt; + color: #FFFFFF; + display: block; + margin: 0pt 1em; + padding: 0.75em 0pt 0pt; +} +ul.primary-links li a:hover { + background: transparent url(images/bg-navigation-item-hover.png) no-repeat scroll 50% 0pt; +} +#logo-floater { + position: absolute; + color: #FFFFFF; + height: 80px; + font-weight: normal; + text-shadow: #1659AC 0px 1px 3px; +} +#logo-floater h1 { + margin-top: 25px; + margin-left: 10px; + font-family: Georgia, Serif; +} + +/* Contents stylesheet */ +body { + font-family: Georgia, Serif; +} +#contents { + margin-right: 0; + width: 340px; + overflow: hidden; + float: right; +} +#contents p.topic-title { + margin: 0 0 0 18px; +} +#contents ul.simple { + margin: 5px 0 5px 5px; + padding: 2px 0 8px 30px; + border-left: 1px solid #E0E5FB; +} +a { + color: #027AC6; + text-decoration: none; +} +a:hover { + color: #0062A0; + text-decoration: underline; +} +a.toc-backref:hover { + color: #000000; +} +a.external { + padding-right: 13px; + background: transparent url(images/external.png) no-repeat scroll right center; +} + +tt.docutils { + background-color: #EAFFEA; + font-family: Monaco, Consolas, Courier New, Monospace; +} + +div.highlight { + margin: 5px 40px 5px 15px; + overflow: auto; + padding: 0; + background: #F7F7F7; + border: 1px solid #E0E5FB; +} +div.highlight pre { + margin: 8px 15px 8px 15px; + font-family: Monaco, Consolas, Courier New, Monospace; + font-size: 0.9em; + line-height: 1.2em; +} +img { + margin: 8px; +}
\ No newline at end of file diff --git a/emacs.d/lisp/yasnippet/doc/template.txt b/emacs.d/lisp/yasnippet/doc/template.txt new file mode 100644 index 0000000..e01d73d --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/template.txt @@ -0,0 +1,67 @@ +%(head_prefix)s +%(head)s +%(stylesheet)s +%(body_prefix)s +<div id="header-region" class="clear-block"></div> +<div id="wrapper"> + <div id="container" class="clear-block"> + <div id="header"> + <div id="logo-floater"> + %(html_title)s + </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> + %(body)s + </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> +%(body_suffix)s |
