code.delx.au - gnu-emacs-elpa/blob - README.mdown

   1 # Intro
   2
   3 **YASnippet** is a template system for Emacs. It allows you to
   4 type an abbreviation and automatically expand it into function
   5 templates. Bundled language templates include: C, C++, C#, Perl,
   6 Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax
   7 is inspired from [TextMate's][textmate-snippets] syntax, you can
   8 even [import][import-docs] most TextMate templates to
   9 YASnippet. Watch [a demo on YouTube][youtube-demo] or download a
  10 [higher resolution version][high-res-demo].
  11
  12 [textmate-snippets]: http://manual.macromates.com/en/snippets
  13 [import-docs]: http://yasnippet.googlecode.com/svn/trunk/doc/snippet-development.html#importing-textmate-snippets
  14 [youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
  15 [high-res-demo]: http://yasnippet.googlecode.com/files/yas_demo.avi
  16
  17 # Installation
  18
  19 ## Install the most recent version
  20
  21 Clone this repository somewhere
  22
  23     $ cd ~/.emacs.d/plugins
  24     $ git clone https://github.com/capitaomorte/yasnippet
  25
  26 Add the following in your `.emacs` file:
  27
  28     (add-to-list 'load-path
  29                   "~/.emacs.d/plugins/yasnippet")
  30     (require 'yasnippet)
  31     (yas-global-mode 1)
  32
  33 Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`.
  34
  35 ## Install with `package-install`
  36
  37 In a recent emacs `M-x list-packages` is the recommended way to list and install packages.
  38 [MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing.
  39
  40 ## Install with el-get
  41
  42 El-get is a nice way to get the most recent version, too. See
  43 https://github.com/dimitri/el-get for instructions. Be sure to install the
  44 "master" branch since the 3.x series still use the old googlecode code, base.
  45 Consider using this "local" recipe.
  46
  47     (push '(:name yasnippet
  48                   :website "https://github.com/capitaomorte/yasnippet.git"
  49                   :description "YASnippet is a template system for Emacs."
  50                   :type github
  51                   :pkgname "capitaomorte/yasnippet"
  52                   :features "yasnippet"
  53                   :compile "yasnippet.el")
  54           el-get-sources)
  55
  56 ## Use `yas-minor-mode` on a per-buffer basis
  57
  58 To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
  59 `(yas-reload-all)` to load the snippet tables. Then add a call to
  60 `(yas-minor-mode)` to the major-modes where you to enable YASnippet.
  61
  62     (add-hook 'prog-mode-hook
  63               '(lambda ()
  64                  (yas-minor-mode)))
  65
  66 # (NOT) Contributing snippets
  67
  68 Please **do not** open pull requests or ask me to add snippets to
  69 YASnippet.
  70
  71 The bundled collection under `/snippets` is considered frozen: **I
  72 will not add more snippets to it**.
  73
  74 You can point `yas-snippet-dirs` to good snippet collections out
  75 there. If you have created snippets for a mode, or multiple modes,
  76 consider creating a repository to host them, then tell users that it
  77 should be added like this to `yas-snippet-dirs`:
  78
  79     (setq yas-snippet-dirs
  80           '("~/.emacs.d/snippets"            ;; personal snippets
  81             "/path/to/some/collection/"      ;; just some foo-mode snippets
  82             "/path/to/some/othercollection/" ;; some more foo-mode and a complete baz-mode
  83             "/path/to/yasnippet/snippets"    ;; the default collection
  84             ))
  85
  86     (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
  87
  88 # Importing TextMate snippets
  89
  90 There is a tool `extras/textmate-import.rb` than can import many
  91 actual TextMate snippets. These can be quite complex so the
  92 `extras/imported/*-mode/.yas-setup.el` files help it with the more
  93 difficult importation.
  94
  95 I'm focusing on developing `textmate-import.rb` tool and some
  96 `yas-setup.el` files. In the future `/snippets` snippets will be
  97 deprecated and might be replaced with `extras/imported`.
  98
  99 ## Example importation of rails snippets
 100
 101 To start using [drnic's](https://github.com/drnic) snippets for rails
 102 development, follow this example. It will convert `ruby`, `rails` and
 103 `html` bundles from github repositories. The importation will be
 104 guided by the `.yas-setup.el` files.
 105
 106 After cloning this repository to `~/.emacs.d/plugins/yasnippet`
 107
 108     cd ~/.emacs.d/plugins/yasnippet
 109     git submodule init
 110     git submodule update
 111     gem install plist trollop
 112     rake convert_bundles             # will convert ruby, rails and html bundles
 113
 114 Then, in your `.emacs` file
 115
 116     (add-to-list 'load-path
 117                   "~/.emacs.d/plugins/yasnippet")
 118     (require 'yasnippet)
 119     (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported"))
 120     (yas-global-mode 1)
 121
 122 Open some rails file (model, app, etc) and start using the textmate
 123 snippets.  Note that in the example above we have abandoned the
 124 default snippet collection on `~/.emacs.d/plugins/yasnippet/snippets`
 125
 126 # Documentation, issues, etc
 127
 128 Please refer to the comprehensive (albeit slightly outdated)
 129 [documentation][docs] for full customization
 130 and support.  If you find a bug, please report it on
 131 [the GitHub issue tracker][issues].  (please **do not** submit new issues to the old
 132 [googlecode tracker][googlecode tracker])
 133
 134 If you run into problems using YASnippet, or have snippets to contribute, post
 135 to the [YASnippet google group][forum]. Thank you very much for using YASnippet!
 136
 137 [docs]: http://capitaomorte.github.com/yasnippet/
 138 [issues]: https://github.com/capitaomorte/yasnippet/issues
 139 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 140 [forum]: http://groups.google.com/group/smart-snippet
 141 [melpa]: http://melpa.milkbox.net/