+#+TITLE: Yet another snippet extension
+#+OPTIONS: toc:1
+#+STARTUP: showall
+
+#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheets/styles.css" />
+
+# External links
+#
+#+LINK: smart-snippet http://code.google.com/p/smart-snippet
+#+LINK: pluskid http://pluskid.lifegoo.org
+
+#+LINK: screencast http://www.youtube.com/watch?v=ZCGmZK4V7Sg
+#+LINK: docs http://capitaomorte.github.com/yasnippet
+#+LINK: issues https://github.com/capitaomorte/yasnippet/issues
+#+LINK: googlecode-tracker http://code.google.com/p/yasnippet/issues/list
+#+LINK: forum http://groups.google.com/group/smart-snippet
+
+
+* Quick start
+
+ *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-textmate][import most TextMate snippets]]
+
+ YASnippet is an original creation of [[pluskid]] who also wrote its predecessor
+ [[smart-snippet]].
+
+** Watch a demo
+
+ [[youtube]]
+
+** Installation
+
+ Clone this repository somewhere
+
+ #+begin_example
+ $ cd ~/.emacs.d/plugins
+ $ git clone https://github.com/capitaomorte/yasnippet
+ #+end_example
+
+ Add the following in your =.emacs= file:
+
+ #+begin_src emacs-lisp :exports code
+ (add-to-list 'load-path
+ "~/.emacs.d/plugins/yasnippet")
+ (require 'yasnippet)
+ (yas/global-mode 1)
+ #+end_src
+
+ Add your own snippets to =~/.emacs.d/snippets= by placing files there or
+ invoking [[#yas-new-snippet][=yas-new-snippet=]].
+
+** Import textmate snippets (rails example)
+ :PROPERTIES:
+ :CUSTOM_ID: import-textmate
+ :END:
+
+ YASnippet lets you use TextMate bundles directly:
+
+ #+begin_example
+ $ cd ~/.emacs.d/plugins
+ $ git clone https://github.com/capitaomorte/yasnippet
+ $ cd yasnippet
+ $ git submodule init
+ $ git submodule update
+ $ gem install plist trollop
+ $ rake convert_bundles # will convert ruby, rails and html bundles from drnic
+ #+end_example
+
+ Then, in your =.emacs= file
+
+ #+begin_example
+ (add-to-list 'load-path
+ "~/.emacs.d/plugins/yasnippet")
+ (require 'yasnippet)
+ (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))
+ (yas/global-mode 1)
+ #+end_example
+
+ Open some rails file (model, app, etc) and start using the textmate
+ snippets. Consider that this is a work-in-progress and many snippets/commands
+ might not work. Patches welcome!
+
+** Contributing snippets
+
+ Please *do not ask me* to add snippets to the default collection under
+ =/snippets=. This collection is considered frozen. By customizing
+ [[#yas-snippet-dirs][=yas-snippet-dirs=]] you can point yasnippet to good
+ snippet collections out there.
+
+ The =extras/textmate-import.rb= tool can import many actual Textmate
+ snippets. I'm focusing on developing it and the accompanying =yas-setup.el=
+ files that guide it with more difficult importations. The idea is to deprecate
+ =/snippets= and replace it with =extras/imported=.
+
+** Documentation, issues, etc
+
+ Please refer to the comprehensive [[docs][documentation]] for full
+ customization and support. If you think you've found a bug, please report it
+ on [[issues][the GitHub issue tracker]]. (please **do not** submit new
+ issues to the old [[googlecode-tracker][googlecode tracker]])
+
+ If you run into problems using YASnippet, or have snippets to contribute,
+ post to the [[forum][yasnippet forum]]. Thank you very much for using
+ YASnippet!
+
+* Organizing snippets
+
+** Basic structure
+
+ Snippet collections can be stored in plain text files. They are arranged by
+ sub-directories naming *snippet tables*. These mostly name Emacs major names.
+
+ #+begin_example
+ .
+ |-- c-mode
+ | `-- printf
+ |-- java-mode
+ | `-- println
+ `-- text-mode
+ |-- email
+ `-- time
+ #+end_example
+
+ The collections are loaded into *snippet tables* which the triggering
+ mechanism (see [[#expand-snippets][Expanding snippets]]) looks up and
+ (hopefully) cause the right snippet to be expanded for you.
+
+** Setting up =yas-snippet-dirs=
+
+ The emacs variable [[#yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
+ which collections to consider. It's used when you activate
+ [[#yas-global-mode][=yas-global-mode=]] or call
+ [[#yas-reload-all][=yas-reload-all=]] interactively.
+
+ The default considers:
+
+ - a personal collection that lives in =~/.emacs.d/snippets=
+ - the bundled collection, taken as a relative path to =yasnippet.el= localtion
+
+ When you come across other snippet collections, do the following to try them
+ out:
+
+ #+begin_src emacs-lisp :exports code
+ ;; Develop in ~/emacs.d/mysnippets, but also
+ ;; try out snippets in ~/Downloads/interesting-snippets
+ (setq yas/snippet-dirs '("~/emacs.d/mysnippets"
+ "~/Downloads/interesting-snippets"))
+
+ ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
+ (setq yas/snippet-dirs (append yas/snippet-dirs
+ '("~/Downloads/interesting-snippets")))
+ #+end_src
+
+ Collections appearing earlier in the list shadow snippets with same names
+ appearing in collections later in the list. [[#yas-new-snippet][=yas-new-snippet=]] always stores
+ snippets in the first collection.
+
+** The =.yas.parents= file
+
+ It's very useful to have certain modes share snippets between themselves. To do
+ this, choose a mode subdirectory and place a =.yas-parents= containing a
+ whitespace-separated list of other mode names. When you reload those modes
+ become parents of the original mode.
+
+ #+begin_example
+ .
+ |-- 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
+ #+end_example
+
+** TODO The =.yas-make-groups= file
+
+ 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 [[snippet-menu][the menu]] is organized much more cleanly:
+
+ (TODO image)
+
+ Another alternative way to achieve this is to place a =# group:= directive
+ inside the snippet definition. See [[#writing-snippets][Writing Snippets]]
+
+ #+begin_example
+ $ tree ruby-mode/
+ ruby-mode/
+ |-- .yas-make-groups
+ |-- collections
+ | |-- each
+ | `-- ...
+ |-- control structure
+ | |-- forin
+ | `-- ...
+ |-- definitions
+ | `-- ...
+ `-- general
+ `-- ...
+ #+end_example
+
+ Yet another way to create a nice snippet menu is to write into
+ =.yas-make-groups= a menu definition. TODO
+
+** TODO The =.yas-setup.el= file
+
+*** TODO
+
+** TODO The =.yas-compiled-snippet.el= file
+
+*** TODO
+
+** The =.yas-skip= file
+
+* Expanding Snippets
+
+ :PROPERTIES:
+ :CUSTOM_ID: expand-snippets
+ :END:
+
+ This section 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
+
+** Triggering expansion
+
+ To make a snippet expand after the cursor:
+
+ * Type an the snippet's *trigger key* then press the key defined in
+ [[#yas-trigger-key][=yas-trigger-key=]] (usually to "TAB").
+
+ * Use the snippet's *keybinding*.
+
+ * Call [[#yas-insert-snippet][=yas-insert-snippet=]] (use =M-x
+ yas-insert-snippet== or its keybinding =C-c & C-s=).
+
+ * By expanding directly from the "YASnippet" menu in the menu-bar
+
+ * Using hippie-expand
+
+ * Use m2m's excellent auto-complete
+
+* Reference
+#+BEGIN_SRC emacs-lisp :exports results :results value raw
+(yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
+ `("Customization variables" . ,#'(lambda (sym)
+ (and (boundp sym)
+ (get sym 'standard-value))))
+ `("Useful functions" . ,#'fboundp)
+ `("Useful variables" . ,#'boundp))
+#+END_SRC
+# Local Variables:
+# mode: org
+# fill-column: 80
+# coding: utf-8
+# End: