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

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