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

   1 =============================
   2 Yet Another Snippet extension
   3 =============================
   4
   5 .. _Organizing Snippets: snippet-organization.html
   6 .. _Expanding Snippets: snippet-expansion.html
   7 .. _Writing Snippets: snippet-development.html
   8 .. _The YASnippet Menu: snippet-menu.html
   9
  10 .. contents::
  11
  12 **YASnippet** is a template system for Emacs. It allows you to type an
  13 abbreviation and automatically expand it into function
  14 templates. Bundled language templates includes: C, C++, C#, Perl,
  15 Python, Ruby, SQL, LaTeX, HTML, CSS and more.
  16
  17 The snippet syntax is inspired from TextMate's syntax, you can even
  18 `import <snippet-development.html#importing-textmate-snippets>`_
  19 import most TextMate templates. YASnippet is a re-write of the
  20 extension `smart-snippet`_. Both are original creations of `pluskid
  21 <http://pluskid.lifegoo.org>`_.
  22
  23 .. _smart-snippet: http://code.google.com/p/smart-snippet/
  24
  25 Video Demo
  26 ==========
  27
  28 .. youtube:: 76Ygeg9miao
  29    :align: right
  30
  31 Watch the `demo at YouTube
  32 <http://www.youtube.com/watch?v=76Ygeg9miao>`_ (download a higher
  33 resolution version: `yasnippet.avi
  34 <http://yasnippet.googlecode.com/files/yasnippet.avi>`_).
  35
  36 Installation
  37 ============
  38
  39 There are two archives you can download. To quickly tryout YASnippet,
  40 download the simpler "bundle" version. If you plan to modify the
  41 bundled templates and/or build your own, download the "normal"
  42 package.
  43
  44 Install with ``yasnippet-bundle.el``
  45 ------------------------------------
  46
  47 1. Download the latest ``yasnippet-bundle-x.y.z.el.tgz`` and unpack it.
  48 2. You'll get a file named ``yasnippet-bundle.el``, put it under
  49    ``~/.emacs.d/plugins/`` (create the directory if not exists).
  50 3. Open the file in Emacs, and type ``Alt+x eval-buffer``.
  51
  52 That's it. Now open any one of your language file, you'll see a menu
  53 YASnippet. you can pull the menu to insert a template. Or, you can
  54 type the a *trigger key* then press ``TAB`` to expand it.
  55
  56 To have Emacs load YASnippet automatically when it starts, put the
  57 following in your ``~/.emacs`` file:
  58
  59    .. sourcecode:: common-lisp
  60
  61      (add-to-list 'load-path
  62                    "~/.emacs.d/plugins")
  63      (require 'yasnippet-bundle)
  64
  65 The `youtube video <http://www.youtube.com/watch?v=76Ygeg9miao>`_
  66 demonstrates this quick installation.
  67
  68 Normal Install
  69 --------------
  70
  71 To install YASnippet as a normal emacs package, download and unpack
  72 the latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named
  73 ``yasnippet-x.y.z``, which you can put it in your
  74 ``~/.emacs.d/plugins`` and add the following in your ``.emacs`` file:
  75
  76    .. sourcecode:: common-lisp
  77
  78      (add-to-list 'load-path
  79                    "~/.emacs.d/plugins/yasnippet-x.y.z")
  80      (require 'yasnippet) ;; not yasnippet-bundle
  81      (yas/initialize)
  82      (yas/load-directory "~/.emacs.d/plugins/yasnippet-x.y.z/snippets")
  83
  84 Please refer to the documentation for full customization, or use the
  85 customization group.
  86
  87 How to use YASnippet
  88 ====================
  89
  90 Since version 0.6, YASnippet contains more functionality. You don't
  91 need to know all of it to use it successfully, but you it can improve
  92 your snippeting experience.
  93
  94 Hence this section has been split into separate documents:
  95
  96 1. `Organizing Snippets`_
  97
  98   Describes ways to organize your snippets in the hard disk (or not
  99   organize them at all and just use ``yasnippet-bundle.el``.
 100
 101 2. `Expanding Snippets`_
 102
 103   Describes how YASnippet chooses snippets for expansion at point.
 104
 105   Maybe, you'll want some snippets to be expanded in a particular
 106   mode, or only under certain conditions, or be prompted using
 107   ``ido``, etc...
 108
 109 3. `Writing Snippets`_
 110
 111   Describes the YASnippet definition syntax, which is very close (but
 112   not equivalent) to Textmate's. Includes a section about converting
 113   TextMate snippets.
 114
 115 4. `The YASnippet menu`_
 116
 117   Explains how to use the YASnippet menu to explore, learn and modify
 118   snippets.
 119
 120 Bugs, Contribution and Support
 121 ==============================
 122
 123 * If you find a bug, please report it at `Issue List
 124   <http://code.google.com/p/yasnippet/issues/list>`_.
 125 * If you have problem using YASnippet, or have some new ideas,
 126   including snippets, please post to the `discussion group`_.
 127
 128 .. _discussion group: http://groups.google.com/group/smart-snippet
 129 .. _wish list: http://code.google.com/p/yasnippet/wiki/WishList
 130
 131 Thank you very much for using YASnippet!
 132
 133 ..  LocalWords:  YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki