yasnippet/doc/index.org

#+TITLE: Yet another snippet extension
#+OPTIONS: toc:1
#+STARTUP: showall

#+SETUPFILE: org-setup.inc

* 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 [[http://pluskid.lifegoo.org][pluskid]] who also wrote its predecessor
  [[http://code.google.com/p/smart-snippet][smart-snippet]].

** Watch a demo

   On [[http://www.youtube.com/watch?v=ZCGmZK4V7Sg][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 [[sym: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
   [[sym: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

   The documentation has been split into separate parts:

   1. [[file:snippet-organization.org][Organizing Snippets]]
      #+BEGIN_QUOTE
      Describes ways to organize your snippets in the hard disk.
      #+END_QUOTE

   2. [[file:snippet-expansion.org][Expanding Snippets]]
      #+BEGIN_QUOTE
      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...
      #+END_QUOTE

   3. [[file:snippet-development.org][Writing Snippets]]
      #+BEGIN_QUOTE
      Describes the YASnippet definition syntax, which is very close (but
      not equivalent) to Textmate's. Includes a section about converting
      TextMate snippets.
      #+END_QUOTE

   4. [[file:snippet-menu.org][The YASnippet menu]]
      #+BEGIN_QUOTE
      Explains how to use the YASnippet menu to explore, learn and modify
      snippets.
      #+END_QUOTE

   5. [[file:snippet-reference.org][YASnippet Symbol Reference]]
      #+BEGIN_QUOTE
      An automatically generated listing of all YASnippet commands,
      (customization) variables, and functions.
      #+END_QUOTE

** Bugs, discussion, contributions, etc

   If you think you've found a bug, please report it on [[https://github.com/capitaomorte/yasnippet/issues][the GitHub issue tracker]]
   (please **do not** submit new issues to the old [[http://code.google.com/p/yasnippet/issues/list][googlecode tracker]]).

   If you run into problems using YASnippet, or have snippets to contribute,
   post to the [[http://groups.google.com/group/smart-snippet][yasnippet forum]]. Thank you very much for using YASnippet!


* 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 the snippet's *trigger key* then calling [[sym:yas-expand][=yas-expand=]]. It's bound to
     =TAB= and =<tab>= by default, to change it use

   #+begin_src emacs-lisp :exports code
     (define-key yas-minor-mode-map (kbd "<tab>") nil)
     (define-key yas-minor-mode-map (kbd "TAB") nil)
     (define-key yas-minor-mode-map (kbd "<the new key>") 'yas-expand)
   #+end_src

   * Use the snippet's *keybinding*.

   * Call [[sym: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

# Local Variables:
# mode: org
# fill-column: 80
# coding: utf-8
# End: