code.delx.au - gnu-emacs-elpa/blob - doc/index.org

   1 #+SETUPFILE: org-setup.inc
   2 #+TITLE: Yet another snippet extension
   3
   4 * Quick start
   5
   6   *YASnippet* is a template system for Emacs. It allows you to type an
   7   abbreviation and automatically expand it into function templates. Bundled
   8   language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML,
   9   CSS and more. The snippet syntax is inspired from TextMate's syntax, you can
  10   even [[#import-textmate][import most TextMate snippets]]
  11
  12   YASnippet is an original creation of [[http://pluskid.lifegoo.org][pluskid]] who also wrote its predecessor
  13   [[http://code.google.com/p/smart-snippet][smart-snippet]].
  14
  15 ** Watch a demo
  16
  17    On [[http://www.youtube.com/watch?v=ZCGmZK4V7Sg][youtube]].
  18
  19 ** Installation
  20
  21    Clone this repository somewhere
  22
  23    #+begin_example
  24    $ cd ~/.emacs.d/plugins
  25    $ git clone https://github.com/capitaomorte/yasnippet
  26    #+end_example
  27
  28    Add the following in your =.emacs= file:
  29
  30    #+begin_src emacs-lisp :exports code
  31    (add-to-list 'load-path
  32                  "~/.emacs.d/plugins/yasnippet")
  33    (require 'yasnippet)
  34    (yas-global-mode 1)
  35    #+end_src
  36
  37    Add your own snippets to =~/.emacs.d/snippets= by placing files there or
  38    invoking [[sym:yas-new-snippet][=yas-new-snippet=]].
  39
  40 ** Import textmate snippets (rails example)
  41    :PROPERTIES:
  42    :CUSTOM_ID: import-textmate
  43    :END:
  44
  45    YASnippet lets you use TextMate bundles directly:
  46
  47    #+begin_example
  48    $ cd ~/.emacs.d/plugins
  49    $ git clone https://github.com/capitaomorte/yasnippet
  50    $ cd yasnippet
  51    $ git submodule init
  52    $ git submodule update
  53    $ gem install plist trollop
  54    $ rake convert_bundles             # will convert ruby, rails and html bundles from drnic
  55    #+end_example
  56
  57    Then, in your =.emacs= file
  58
  59    #+begin_example
  60    (add-to-list 'load-path
  61                  "~/.emacs.d/plugins/yasnippet")
  62    (require 'yasnippet)
  63    (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))
  64    (yas-global-mode 1)
  65    #+end_example
  66
  67    Open some rails file (model, app, etc) and start using the textmate
  68    snippets. Consider that this is a work-in-progress and many snippets/commands
  69    might not work. Patches welcome!
  70
  71 ** Contributing snippets
  72
  73    Please *do not ask me* to add snippets to the default collection under
  74    =/snippets=. This collection is considered frozen. By customizing
  75    [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] you can point yasnippet to good
  76    snippet collections out there.
  77
  78    The =extras/textmate-import.rb= tool can import many actual Textmate
  79    snippets.  I'm focusing on developing it and the accompanying =yas-setup.el=
  80    files that guide it with more difficult importations. The idea is to deprecate
  81    =/snippets=  and replace it with =extras/imported=.
  82
  83 ** Documentation
  84
  85    The documentation has been split into separate parts:
  86
  87    1. [[file:snippet-organization.org][Organizing Snippets]]
  88       Describes ways to organize your snippets in the hard disk.
  89
  90    2. [[file:snippet-expansion.org][Expanding Snippets]]
  91       Describes how YASnippet chooses snippets for expansion at point.
  92
  93       Maybe, you'll want some snippets to be expanded in a particular mode,
  94       or only under certain conditions, or be prompted using =ido=, etc...
  95
  96    3. [[file:snippet-development.org][Writing Snippets]]
  97       Describes the YASnippet definition syntax, which is very close (but
  98       not equivalent) to Textmate's. Includes a section about converting
  99       TextMate snippets.
 100
 101    4. [[file:snippet-menu.org][The YASnippet menu]]
 102       Explains how to use the YASnippet menu to explore, learn and modify
 103       snippets.
 104
 105    5. [[file:snippet-reference.org][YASnippet Symbol Reference]]
 106       An automatically generated listing of all YASnippet commands,
 107       (customization) variables, and functions.
 108
 109 ** Bugs, discussion, contributions, etc
 110
 111    If you think you've found a bug, please report it on [[https://github.com/capitaomorte/yasnippet/issues][the GitHub issue tracker]]
 112    (please **do not** submit new issues to the old [[http://code.google.com/p/yasnippet/issues/list][googlecode tracker]]).
 113
 114    If you run into problems using YASnippet, or have snippets to contribute,
 115    post to the [[http://groups.google.com/group/smart-snippet][yasnippet forum]]. Thank you very much for using YASnippet!
 116
 117 # Local Variables:
 118 # mode: org
 119 # fill-column: 80
 120 # coding: utf-8
 121 # End: