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

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