-# Intro
+[](https://travis-ci.org/capitaomorte/yasnippet)
-**yasnippet** is a template system for Emacs. It allows you to type an
-abbreviation and automatically expand it into function
-templates. Bundled language templates includes: C, C++, C#, Perl,
-Python, Ruby,
+# Intro
-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]
+**YASnippet** is a template system for Emacs. It allows you to
+type an abbreviation and automatically expand it into function
+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) most TextMate templates to
+YASnippet. Watch [a demo on YouTube][youtube-demo] or download a
+[higher resolution version][high-res-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
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:
(add-to-list 'load-path
"~/.emacs.d/plugins/yasnippet")
(require 'yasnippet)
- (yas/global-mode 1)
+ (yas-global-mode 1)
+
+Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`.
+
+## Install with `package-install`
-Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas/new-snippet`.
+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.
-## Install yasnippet with el-get
+## Install with el-get
-El-get is a nice way to get the most recent version, too
+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.
-See https://github.com/dimitri/el-get for instructions
+ (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)
-## Use `yas/minor-mode` on a per-buffer basis
+## 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, 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.
(add-hook 'prog-mode-hook
'(lambda ()
- (yas/minor-mode)))
+ (yas-minor-mode)))
-# Contributing snippets
+# Where are the snippets?
-Please do not ask me to add snippets to the default collection under
-`/snippets`. This is considered frozen and by customizing
-`yas/snippet-dirs` you can point yasnippet to good snippet collections
-out there.
+<a name="import"></a>
-There is a tool `extras/textmate-import.rb` than can import many
-actual Textmate snippets and there are
-`extras/imported/*-mode/.yas-setup.el` files that can help it with the
-more difficult importation.
+Yasnippet no longer bundles snippets directly, but it's very easy to
+get some!
-I'm focusing on developping `textmate-import.rb` tool and the
-`yas-setup.el` files. In the future `/snippets` snippets will be
-deprecated and replaced with `extras/imported`.
+If you git-cloned yasnippet with the `--recursive` option you'll also
+download "git submodules" and find two subdirs under the main tree.
-Follow through the following example to start using these snippets for
-rails development. It will convert `ruby`, `rails` and `html` bundles
-from drnic's github repositories based on corresponding
-`.yas-setup.el` files.
+1. `snippets/`
-## Using imported textmate snippets (rails example)
+ Points to [yasnippet-snippets][yasnippet-snippets] the snippet
+ collection of [AndreaCrotti](https://github.com/AndreaCrotti).
-After cloning this repository to `~/.emacs.d/plugins/yasnippet`
+ 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/`)
- 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 from drnic
+2. `yasmate/`
-Then, in your .emacs file
+ Points to a github repo of the [yasmate][yasmate] tool, which is
+ dedicated to converting textmate bundles into yasnippet snippets.
- (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)
+ 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.
+
+ If you have a working ruby environment, you can probably get lucky
+ directly with `rake convert-bundles`.
-Open some rails file (model, app, etc) and start using the textmate snippets.
-Note thqt in the example above we abandon the default snippet collection on
-`~/.emacs.d/plugins/yasnippet/snippets`
+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/" ;; 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.
# Documentation, issues, etc
-Please refer to the comprehensive [documentation] [docs] for full customization
+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])
-If you run into problems using yasnippet, or have snippets to contribute, post
-to the [yasnippet google group][forum]. Thank you very much for using yasnippet!
+## 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.
+
+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.
+
+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).
+
+Finally, thank you very much for using YASnippet!
[docs]: http://capitaomorte.github.com/yasnippet/
[issues]: https://github.com/capitaomorte/yasnippet/issues
[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
+[yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets