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].
  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.milkbox.net/#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, replace `(yas-global-mode 1)` with
  47 `(yas-reload-all)` to load the snippet tables. Then add a call to
  48 `(yas-minor-mode)` to the major-modes where you to enable YASnippet.
  49
  50     (add-hook 'prog-mode-hook #'yas-minor-mode)
  51
  52 # Where are the snippets?
  53
  54 <a name="import"></a>
  55
  56 Yasnippet no longer bundles snippets directly, but it's very easy to
  57 get some!
  58
  59 If you git-cloned yasnippet with the `--recursive` option you'll also
  60 download "git submodules" and find two subdirs under the main tree.
  61
  62 1. `snippets/`
  63
  64     Points to [yasnippet-snippets][yasnippet-snippets] the snippet
  65     collection of [AndreaCrotti](https://github.com/AndreaCrotti).
  66
  67     The default configuraiton already points to this dir, so to use
  68     them, just make sure the submodule really was downloaded
  69     (i.e. there are some files under `snippets/`)
  70
  71 2. `yasmate/`
  72
  73     Points to a github repo of the [yasmate][yasmate] tool, which is
  74     dedicated to converting textmate bundles into yasnippet snippets.
  75
  76     To use these snippets you have to run the tool first, so
  77     [see its doc][yasmate]), and then point the `yas-snippet-dirs`
  78     variable to the `.../yasmate/snippets` subdir.
  79
  80     If you have a working ruby environment, you can probably get lucky
  81     directly with `rake convert-bundles`.
  82
  83 Naturally, you can point `yas-snippet-dirs` to good snippet collections out
  84 there. If you have created snippets for a mode, or multiple modes,
  85 consider creating a repository to host them, then tell users that it
  86 should be added like this to `yas-snippet-dirs`:
  87
  88     (setq yas-snippet-dirs
  89           '("~/.emacs.d/snippets"                 ;; personal snippets
  90             "/path/to/some/collection/"           ;; foo-mode and bar-mode snippet collection
  91             "/path/to/yasnippet/yasmate/snippets" ;; the yasmate collection
  92             "/path/to/yasnippet/snippets"         ;; the default collection
  93             ))
  94
  95     (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
  96
  97 # Manual, issues etc
  98
  99 Please refer to the comprehensive [documentation][docs] for full
 100 customisation and support.  If you find a bug in the code or in the
 101 documentation, please report it on [the GitHub issue tracker][issues].
 102
 103 ## Important note regarding bug reporting
 104
 105 Your bug reports are very valuable.
 106
 107 The most important thing when reporting bugs is making sure that we have
 108 a way to reproduce the problem exactly like it happened to you.
 109
 110 To do this, we need to rule out interference from external factors
 111 like other Emacs extensions or your own customisations.
 112
 113 Here's an example report that "sandboxes" an Emacs session just for
 114 reproducing a bug.
 115
 116 ```
 117 $ emacs --version
 118 Emacs 24.3
 119 $ cd /tmp/
 120 $ git clone https://github.com/capitaomorte/yasnippet.git yasnippet-bug
 121 $ cd yasnippet-bug
 122 $ git log -1 --oneline
 123 6053db0 Closes #527: Unbreak case where yas-fallback-behaviour is a list
 124 $ HOME=$PWD emacs -L  # This "sandboxes" your emacs, melpa configuration, etc
 125
 126 (require 'yasnippet)
 127 (yas-global-mode 1)
 128
 129 When I open a foo-mode file I can't expand foo-mode snippets!
 130 OR
 131 I can't get yasnippet to load because frankinbogen!
 132 ```
 133
 134 Using `emacs -Q` or temporarily moving your `.emacs` init file to the side
 135 is another way to achieve good reproducibility.
 136
 137 Here's a
 138 [another example](https://github.com/capitaomorte/yasnippet/issues/318)
 139 of a bug report. It has everything needed for a successful analysis
 140 and speedy resolution.
 141
 142 Also, don't forget to state the Emacs version (use `M-x emacs-version`) and
 143 the yasnippet version you are using (if using the latest from github,
 144 do `git log -1` in the dir).
 145
 146 Any more info is welcome, but don't just paste a backtrace or an error
 147 message string you got, unless we ask for it.
 148
 149 There is also a [YASnippet google group][forum]. I will keep the group
 150 open for reference and for discussion among users. Unfortunately I
 151 can't guarantee a timely response, so maybe it's better to create a
 152 github issue clearly marking your intent (user support/bug/feature
 153 request).
 154
 155 Finally, thank you very much for using YASnippet!
 156
 157 [docs]: http://capitaomorte.github.com/yasnippet/
 158 [issues]: https://github.com/capitaomorte/yasnippet/issues
 159 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 160 [forum]: http://groups.google.com/group/smart-snippet
 161 [melpa]: http://melpa.milkbox.net/
 162 [yasmate]: http://github.com/capitaomorte/yasmate
 163 [yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets