mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 13:13:03 +00:00
47dbe93d86
After the Github acocunt name change (capitaomorte -> joaotavora), most links to repositories are redirected excpect Travis CI and Github Pages (documentation). * README.mdown: Fix documentation and Travis badge links
172 lines
6.1 KiB
Markdown
172 lines
6.1 KiB
Markdown
[](https://travis-ci.org/joaotavora/yasnippet)
|
|
|
|
# Intro
|
|
|
|
**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].
|
|
|
|
[textmate-snippets]: http://manual.macromates.com/en/snippets
|
|
[youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
|
|
|
|
# Installation
|
|
|
|
## Install the most recent version
|
|
|
|
Clone this repository somewhere
|
|
|
|
$ cd ~/.emacs.d/plugins
|
|
$ 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)
|
|
|
|
Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`.
|
|
|
|
## 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.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.
|
|
|
|
## Use `yas-minor-mode` on a per-buffer basis
|
|
|
|
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/`)
|
|
|
|
2. `yasmate/`
|
|
|
|
Points to a github repo of the [yasmate] tool, which is dedicated
|
|
to converting textmate bundles into yasnippet snippets.
|
|
|
|
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`.
|
|
|
|
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/" ;; 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.
|
|
|
|
# Manual, issues etc
|
|
|
|
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].
|
|
|
|
## Important note regarding bug reporting
|
|
|
|
Your bug reports are very valuable.
|
|
|
|
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.
|
|
|
|
To do this, we need to rule out interference from external factors
|
|
like other Emacs extensions or your own customisations.
|
|
|
|
Here's an example report that "sandboxes" an Emacs session just for
|
|
reproducing a bug.
|
|
|
|
```
|
|
$ 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
|
|
|
|
(require 'yasnippet)
|
|
(yas-global-mode 1)
|
|
|
|
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"!
|
|
```
|
|
|
|
Using `emacs -Q` or temporarily moving your `.emacs` init file to the side
|
|
is another way to achieve good reproducibility.
|
|
|
|
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, 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 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!
|
|
|
|
[docs]: http://joaotavora.github.io/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
|
|
[textmate-to-yas.el]: https://github.com/mattfidler/textmate-to-yas.el
|
|
[yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets
|