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.
  45
  46 ## Use `yas-minor-mode` on a per-buffer basis
  47
  48 To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
  49 `(yas-reload-all)` to load the snippet tables. Then add a call to
  50 `(yas-minor-mode)` to the major-modes where you to enable YASnippet.
  51
  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][yasnippet-snippets] the snippet
  67     collection of [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][yasmate] tool, which is
  76     dedicated 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 Naturally, you can point `yas-snippet-dirs` to good snippet collections out
  86 there. If you have created snippets for a mode, or multiple modes,
  87 consider creating a repository to host them, then tell users that it
  88 should be added like this to `yas-snippet-dirs`:
  89
  90     (setq yas-snippet-dirs
  91           '("~/.emacs.d/snippets"                 ;; personal snippets
  92             "/path/to/some/collection/"           ;; foo-mode and bar-mode snippet collection
  93             "/path/to/yasnippet/yasmate/snippets" ;; the yasmate collection
  94             "/path/to/yasnippet/snippets"         ;; the default collection
  95             ))
  96
  97     (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
  98
  99 # Manual, issues etc
 100
 101 Please refer to the comprehensive [documentation][docs] for full
 102 customisation and support.  If you find a bug in the code or in the
 103 documentation, please report it on [the GitHub issue tracker][issues].
 104
 105 ## Important note regarding bug reporting
 106
 107 Your bug reports are very valuable.
 108
 109 The most important thing when reporting bugs is making sure that we have
 110 a way to reproduce the problem exactly like it happened to you.
 111
 112 To do this, we need to rule out interference from external factors
 113 like other Emacs extensions or your own customisations.
 114
 115 Here's an example report that "sandboxes" an Emacs session just for
 116 reproducing a bug.
 117
 118 ```
 119 $ emacs --version
 120 Emacs 24.3
 121 $ cd /tmp/
 122 $ git clone https://github.com/capitaomorte/yasnippet.git yasnippet-bug
 123 $ cd yasnippet-bug
 124 $ git log -1 --oneline
 125 6053db0 Closes #527: Unbreak case where yas-fallback-behaviour is a list
 126 $ HOME=$PWD emacs -L  # This "sandboxes" your emacs, melpa configuration, etc
 127
 128 (require 'yasnippet)
 129 (yas-global-mode 1)
 130
 131 When I open a foo-mode file I can't expand foo-mode snippets!
 132 OR
 133 I can't get yasnippet to load because frankinbogen!
 134 ```
 135
 136 Using `emacs -Q` or temporarily moving your `.emacs` init file to the side
 137 is another way to achieve good reproducibility.
 138
 139 Here's a
 140 [another example](https://github.com/capitaomorte/yasnippet/issues/318)
 141 of a bug report. It has everything needed for a successful analysis
 142 and speedy resolution.
 143
 144 Also, don't forget to state the Emacs version (use `M-x emacs-version`) and
 145 the yasnippet version you are using (if using the latest from github,
 146 do `git log -1` in the dir).
 147
 148 Any more info is welcome, but don't just paste a backtrace or an error
 149 message string you got, unless we ask for it.
 150
 151 There is also a [YASnippet google group][forum]. I will keep the group
 152 open for reference and for discussion among users. Unfortunately I
 153 can't guarantee a timely response, so maybe it's better to create a
 154 github issue clearly marking your intent (user support/bug/feature
 155 request).
 156
 157 Finally, thank you very much for using YASnippet!
 158
 159 [docs]: http://capitaomorte.github.com/yasnippet/
 160 [issues]: https://github.com/capitaomorte/yasnippet/issues
 161 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 162 [forum]: http://groups.google.com/group/smart-snippet
 163 [melpa]: http://melpa.milkbox.net/
 164 [yasmate]: http://github.com/capitaomorte/yasmate
 165 [yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets