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

   1 [![Build Status](https://travis-ci.org/capitaomorte/yasnippet.png)](https://travis-ci.org/capitaomorte/yasnippet)
   2
   3 # Intro
   4
   5 **YASnippet** is a template system for Emacs. It allows you to
   6 type an abbreviation and automatically expand it into function
   7 templates. Bundled language templates include: C, C++, C#, Perl,
   8 Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax
   9 is inspired from [TextMate's][textmate-snippets] syntax, you can
  10 even [import](#import) most TextMate templates to
  11 YASnippet. Watch [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 [youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
  16 [high-res-demo]: http://yasnippet.googlecode.com/files/yas_demo.avi
  17
  18 # Installation
  19
  20 ## Install the most recent version
  21
  22 Clone this repository somewhere
  23
  24     $ cd ~/.emacs.d/plugins
  25     $ git clone --recursive https://github.com/capitaomorte/yasnippet
  26
  27 Add the following in your `.emacs` file:
  28
  29     (add-to-list 'load-path
  30                   "~/.emacs.d/plugins/yasnippet")
  31     (require 'yasnippet)
  32     (yas-global-mode 1)
  33
  34 Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`.
  35
  36 ## Install with `package-install`
  37
  38 In a recent emacs `M-x list-packages` is the recommended way to list and install packages.
  39 [MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing.
  40
  41 ## Install with el-get
  42
  43 El-get is a nice way to get the most recent version, too. See
  44 https://github.com/dimitri/el-get for instructions. Be sure to install the
  45 "master" branch since the 3.x series still use the old googlecode code, base.
  46 Consider using this "local" recipe.
  47
  48     (push '(:name yasnippet
  49                   :website "https://github.com/capitaomorte/yasnippet.git"
  50                   :description "YASnippet is a template system for Emacs."
  51                   :type github
  52                   :pkgname "capitaomorte/yasnippet"
  53                   :features "yasnippet"
  54                   :compile "yasnippet.el")
  55           el-get-sources)
  56
  57 ## Use `yas-minor-mode` on a per-buffer basis
  58
  59 To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
  60 `(yas-reload-all)` to load the snippet tables. Then add a call to
  61 `(yas-minor-mode)` to the major-modes where you to enable YASnippet.
  62
  63     (add-hook 'prog-mode-hook
  64               '(lambda ()
  65                  (yas-minor-mode)))
  66
  67 # Where are the snippets?
  68
  69 <a name="import"></a>
  70
  71 Yasnippet no longer bundles snippets directly, but it's very easy to
  72 get some!
  73
  74 If you git-cloned yasnippet with the `--recursive` option you'll also
  75 download "git submodules" and find two subdirs under the main tree.
  76
  77 1. `snippets/`
  78
  79     Points to [yasnippet-snippets][yasnippet-snippets] the snippet
  80     collection of [AndreaCrotti](https://github.com/AndreaCrotti).
  81
  82     The default configuraiton already points to this dir, so to use
  83     them, just make sure the submodule really was downloaded
  84     (i.e. there are some files under `snippets/`)
  85
  86 2. `yasmate/`
  87
  88     Points to a github repo of the [yasmate][yasmate] tool, which is
  89     dedicated to converting textmate bundles into yasnippet snippets.
  90
  91     To use these snippets you have to run the tool first, so
  92     [see its doc][yasmate]), and then point the `yas-snippet-dirs`
  93     variable to the `.../yasmate/snippets` subdir.
  94
  95     If you have a working ruby environment, you can probably get lucky
  96     directly with `rake convert-bundles`.
  97
  98 Naturally, you can point `yas-snippet-dirs` to good snippet collections out
  99 there. If you have created snippets for a mode, or multiple modes,
 100 consider creating a repository to host them, then tell users that it
 101 should be added like this to `yas-snippet-dirs`:
 102
 103     (setq yas-snippet-dirs
 104           '("~/.emacs.d/snippets"                 ;; personal snippets
 105             "/path/to/some/collection/"           ;; foo-mode and bar-mode snippet collection
 106             "/path/to/yasnippet/yasmate/snippets" ;; the yasmate collection
 107             "/path/to/yasnippet/snippets"         ;; the default collection
 108             ))
 109
 110     (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
 111
 112 # Manual, issues etc
 113
 114 Please refer to the comprehensive [documentation][docs] for full
 115 customization and support.  If you find a bug in the code or in the
 116 documentation, please report it on [the GitHub issue tracker][issues].
 117
 118 ## Important note regarding bug reporting
 119
 120 Your bug reports are very valuable.
 121
 122 The most important thing when reporting bugs is making sure that the
 123 developer has a way to reproduce the problem exactly like it happened
 124 to you.
 125
 126 To do this, he needs to rule out interference from external factors
 127 like other Emacs extensions or other Lisp-side code.
 128
 129 Here's an example that "sandboxes" an emacs just for reproducing the
 130 bug.
 131
 132 ```
 133 $ emacs --version
 134 Emacs 24.3
 135 $ cd /tmp/
 136 $ git clone https://github.com/capitaomorte/yasnippet.git yasnippet-bug
 137 $ cd yasnippet-bug
 138 $ git log -1 --oneline
 139 6053db0 Closes #527: Unbreak case where yas-fallback-behaviour is a list
 140 $ HOME=$PWD emacs -L  # This "sandboxes" your emacs, melpa configuration, etc
 141
 142 (require 'yasnippet)
 143 (yas-global-mode 1)
 144
 145 When I open a foo-mode file I can't expand foo-mode snippets!
 146 OR
 147 I can't get yasnippet to load because frankinbogen!
 148 ```
 149
 150 Here's a
 151 [another example](https://github.com/capitaomorte/yasnippet/issues/318)
 152 of a bug report. It has everything needed for a sucessfull analysis
 153 and speedy resolution.
 154
 155 Also, don't forget to state the Emacs version (use `M-x emacs-version`) and
 156 the yasnippet version you are using (if using the latest from github,
 157 do `git log -1` in the dir).
 158
 159 Any more info is welcome, but don't just paste a backtrace or an error
 160 message string you got, unless we ask for it.
 161
 162
 163 There is also a [YASnippet google group][forum]. I will keep the group
 164 open for reference and for discussion among users, unfortunately I
 165 can't guarantee a timely response, so maybe it's better to create a
 166 github issue clearly marking your intent (user support/bug/feature
 167 request).
 168
 169 Finally, thank you very much for using YASnippet!
 170
 171 [docs]: http://capitaomorte.github.com/yasnippet/
 172 [issues]: https://github.com/capitaomorte/yasnippet/issues
 173 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 174 [forum]: http://groups.google.com/group/smart-snippet
 175 [melpa]: http://melpa.milkbox.net/
 176 [yasmate]: http://github.com/capitaomorte/yasmate
 177 [yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets