+[](https://travis-ci.org/capitaomorte/yasnippet)
+
# Intro
**YASnippet** is a template system for Emacs. It allows you to
templates. Bundled language templates include: C, C++, C#, Perl,
Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax
is inspired from [TextMate's][textmate-snippets] syntax, you can
-even [import][import-docs] most TextMate templates to
-YASnippet. Watch [a demo on YouTube][youtube-demo] or download a
-[higher resolution version][high-res-demo].
+even [import](#import) most TextMate templates to
+YASnippet. Watch [a demo on YouTube][youtube-demo].
[textmate-snippets]: http://manual.macromates.com/en/snippets
-[import-docs]: http://yasnippet.googlecode.com/svn/trunk/doc/snippet-development.html#importing-textmate-snippets
[youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
-[high-res-demo]: http://yasnippet.googlecode.com/files/yas_demo.avi
# Installation
Clone this repository somewhere
$ cd ~/.emacs.d/plugins
- $ git clone https://github.com/capitaomorte/yasnippet
+ $ git clone --recursive https://github.com/capitaomorte/yasnippet
Add the following in your `.emacs` file:
## Install with `package-install`
In a recent emacs `M-x list-packages` is the recommended way to list and install packages.
-[MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing.
+[MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.org/#installing.
## Install with el-get
El-get is a nice way to get the most recent version, too. See
-https://github.com/dimitri/el-get for instructions. Be sure to install the
-"master" branch since the 3.x series still use the old googlecode code, base.
-Consider using this "local" recipe.
-
- (push '(:name yasnippet
- :website "https://github.com/capitaomorte/yasnippet.git"
- :description "YASnippet is a template system for Emacs."
- :type github
- :pkgname "capitaomorte/yasnippet"
- :features "yasnippet"
- :compile "yasnippet.el")
- el-get-sources)
+https://github.com/dimitri/el-get for instructions.
## Use `yas-minor-mode` on a per-buffer basis
-To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
-`(yas-reload-all)` to load the snippet tables. Then add a call to
-`(yas-minor-mode)` to the major-modes where you to enable YASnippet.
+To use YASnippet as a non-global minor mode, don't call
+`yas-global-mode`; instead call `yas-reload-all` to load the snippet
+tables and then call `yas-minor-mode` from the hooks of major-modes
+where you want YASnippet enabled.
+
+ (yas-reload-all)
+ (add-hook 'prog-mode-hook #'yas-minor-mode)
+
+# Where are the snippets?
+
+<a name="import"></a>
+
+Yasnippet no longer bundles snippets directly, but it's very easy to
+get some!
+
+If you git-cloned yasnippet with the `--recursive` option you'll also
+download "git submodules" and find two subdirs under the main tree.
+
+1. `snippets/`
+
+ Points to [yasnippet-snippets] the snippet collection of
+ [AndreaCrotti](https://github.com/AndreaCrotti).
+
+ The default configuraiton already points to this dir, so to use
+ them, just make sure the submodule really was downloaded
+ (i.e. there are some files under `snippets/`)
- (add-hook 'prog-mode-hook
- '(lambda ()
- (yas-minor-mode)))
+2. `yasmate/`
-# (NOT) Contributing snippets
+ Points to a github repo of the [yasmate] tool, which is dedicated
+ to converting textmate bundles into yasnippet snippets.
-Please **do not** open pull requests or ask me to add snippets to
-YASnippet.
+ To use these snippets you have to run the tool first, so
+ [see its doc][yasmate]), and then point the `yas-snippet-dirs`
+ variable to the `.../yasmate/snippets` subdir.
-The bundled collection under `/snippets` is considered frozen: **I
-will not add more snippets to it**.
+ If you have a working ruby environment, you can probably get lucky
+ directly with `rake convert-bundles`.
-You can point `yas-snippet-dirs` to good snippet collections out
+3. [textmate-to-yas.el]
+
+ This is another textmate bundle converting tool using Elisp
+ instead of Ruby.
+
+Naturally, you can point `yas-snippet-dirs` to good snippet collections out
there. If you have created snippets for a mode, or multiple modes,
consider creating a repository to host them, then tell users that it
should be added like this to `yas-snippet-dirs`:
(setq yas-snippet-dirs
- '("~/.emacs.d/snippets" ;; personal snippets
- "/path/to/some/collection/" ;; just some foo-mode snippets
- "/path/to/some/othercollection/" ;; some more foo-mode and a complete baz-mode
- "/path/to/yasnippet/snippets" ;; the default collection
+ '("~/.emacs.d/snippets" ;; personal snippets
+ "/path/to/some/collection/" ;; foo-mode and bar-mode snippet collection
+ "/path/to/yasnippet/yasmate/snippets" ;; the yasmate collection
+ "/path/to/yasnippet/snippets" ;; the default collection
))
(yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
-# Importing TextMate snippets
+# Manual, issues etc
-There is a tool `extras/textmate-import.rb` than can import many
-actual TextMate snippets. These can be quite complex so the
-`extras/imported/*-mode/.yas-setup.el` files help it with the more
-difficult importation.
+Please refer to the comprehensive [documentation][docs] for full
+customisation and support. If you find a bug in the code or in the
+documentation, please report it on [the GitHub issue tracker][issues].
-I'm focusing on developing `textmate-import.rb` tool and some
-`yas-setup.el` files. In the future `/snippets` snippets will be
-deprecated and might be replaced with `extras/imported`.
+## Important note regarding bug reporting
-## Example importation of rails snippets
+Your bug reports are very valuable.
-To start using [drnic's](https://github.com/drnic) snippets for rails
-development, follow this example. It will convert `ruby`, `rails` and
-`html` bundles from github repositories. The importation will be
-guided by the `.yas-setup.el` files.
+The most important thing when reporting bugs is making sure that we have
+a way to reproduce the problem exactly like it happened to you.
-After cloning this repository to `~/.emacs.d/plugins/yasnippet`
+To do this, we need to rule out interference from external factors
+like other Emacs extensions or your own customisations.
- cd ~/.emacs.d/plugins/yasnippet
- git submodule init
- git submodule update
- gem install plist trollop
- rake convert_bundles # will convert ruby, rails and html bundles
+Here's an example report that "sandboxes" an Emacs session just for
+reproducing a bug.
-Then, in your `.emacs` file
+```
+$ emacs --version
+Emacs 24.3
+$ cd /tmp/
+$ git clone https://github.com/capitaomorte/yasnippet.git yasnippet-bug
+$ cd yasnippet-bug
+$ git log -1 --oneline
+6053db0 Closes #527: Unbreak case where yas-fallback-behaviour is a list
+$ HOME=$PWD emacs -L . # This "sandboxes" your emacs, melpa configuration, etc
- (add-to-list 'load-path
- "~/.emacs.d/plugins/yasnippet")
- (require 'yasnippet)
- (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported"))
- (yas-global-mode 1)
+(require 'yasnippet)
+(yas-global-mode 1)
-Open some rails file (model, app, etc) and start using the textmate
-snippets. Note that in the example above we have abandoned the
-default snippet collection on `~/.emacs.d/plugins/yasnippet/snippets`
+When I open a foo-mode file I don't see foo-mode under the "YASnippet" menu!
+OR
+When loading yasnippet I see "Error: failed to frobnicate"!
+```
-# Documentation, issues, etc
+Using `emacs -Q` or temporarily moving your `.emacs` init file to the side
+is another way to achieve good reproducibility.
-Please refer to the comprehensive (albeit slightly outdated)
-[documentation][docs] for full customization
-and support. If you find a bug, please report it on
-[the GitHub issue tracker][issues]. (please **do not** submit new issues to the old
-[googlecode tracker][googlecode tracker])
-
-## Important note regarding bug reporting
-If you think have found a bug, please report it clearly. Yasnippet
-does have (lots of) bugs and your reports are very valuable. Here's
-a [great example](https://github.com/capitaomorte/yasnippet/issues/318)
-of a bug report. It has everything needed for a sucessfull analysis and
-speedy resolution:
-
-*Before* reporting try to reproduce the bug **without** your usual
-`.emacs` (or whatever startup file you use). Do so either by starting
-emacs from the command line with the `-Q` switch, or by temporarily
-moving away your `.emacs` and creating a new smaller one just for
-reproducing the bug. Paste that file in your bug report. Paste any sequence
-of relevant shell commands before you launch Emacs.
-
-*Then*, describe steps taken to reproduce from an
-end-user perspective. Try to be as unambiguous as possible.
+Here's a
+[another example](https://github.com/capitaomorte/yasnippet/issues/318)
+of a bug report. It has everything needed for a successful analysis
+and speedy resolution.
Also, don't forget to state the Emacs version (use `M-x emacs-version`) and
the yasnippet version you are using (if using the latest from github,
do `git log -1` in the dir).
Any more info is welcome, but don't just paste a backtrace or an error
-message string you got. I'm not saying your analysis might not be
-useful but following the instructions above immediately gives me a
-clear picture of what is happening.
+message string you got, unless we ask for it.
There is also a [YASnippet google group][forum]. I will keep the group
-open for reference and for discussion among users, unfortunately I
-can't guarantee a timely response, so maybe creating a github issue
-clearly marking your intent (user support/bug/feature request).
+open for reference and for discussion among users. Unfortunately I
+can't guarantee a timely response, so maybe it's better to create a
+github issue clearly marking your intent (user support/bug/feature
+request).
Finally, thank you very much for using YASnippet!
[googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
[forum]: http://groups.google.com/group/smart-snippet
[melpa]: http://melpa.milkbox.net/
+[yasmate]: http://github.com/capitaomorte/yasmate
+[textmate-to-yas.el]: https://github.com/mattfidler/textmate-to-yas.el
+[yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets