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. Be sure to install the
  45 "master" branch since the 3.x series still use the old googlecode code, base.
  46 Consider using this "local" recipe.
  47
  48     (push '(:name yasnippet
  49                   :website "https://github.com/capitaomorte/yasnippet.git"
  50                   :description "YASnippet is a template system for Emacs."
  51                   :type github
  52                   :pkgname "capitaomorte/yasnippet"
  53                   :features "yasnippet"
  54                   :compile "yasnippet.el")
  55           el-get-sources)
  56
  57 ## Use `yas-minor-mode` on a per-buffer basis
  58
  59 To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
  60 `(yas-reload-all)` to load the snippet tables. Then add a call to
  61 `(yas-minor-mode)` to the major-modes where you to enable YASnippet.
  62
  63     (add-hook 'prog-mode-hook
  64               '(lambda ()
  65                  (yas-minor-mode)))
  66
  67 # Where are the snippets?
  68
  69 <a name="import"></a>
  70
  71 Yasnippet no longer bundles snippets directly, but it's very easy to
  72 get some!
  73
  74 If you git-cloned yasnippet with the `--recursive` option you'll also
  75 download "git submodules" and find two subdirs under the main tree.
  76
  77 1. `snippets/`
  78
  79     Points to [yasnippet-snippets][yasnippet-snippets] the snippet
  80     collection of [AndreaCrotti](https://github.com/AndreaCrotti).
  81
  82     The default configuraiton already points to this dir, so to use
  83     them, just make sure the submodule really was downloaded
  84     (i.e. there are some files under `snippets/`)
  85
  86 2. `yasmate/`
  87
  88     Points to a github repo of the [yasmate][yasmate] tool, which is
  89     dedicated to converting textmate bundles into yasnippet snippets.
  90
  91     To use these snippets you have to run the tool first, so
  92     [see its doc][yasmate]), and then point the `yas-snippet-dirs`
  93     variable to the `.../yasmate/snippets` subdir.
  94
  95     If you have a working ruby environment, you can probably get lucky
  96     directly with `rake convert-bundles`.
  97
  98 Naturally, you can point `yas-snippet-dirs` to good snippet collections out
  99 there. If you have created snippets for a mode, or multiple modes,
 100 consider creating a repository to host them, then tell users that it
 101 should be added like this to `yas-snippet-dirs`:
 102
 103     (setq yas-snippet-dirs
 104           '("~/.emacs.d/snippets"                 ;; personal snippets
 105             "/path/to/some/collection/"           ;; foo-mode and bar-mode snippet collection
 106             "/path/to/yasnippet/yasmate/snippets" ;; the yasmate collection
 107             "/path/to/yasnippet/snippets"         ;; the default collection
 108             ))
 109
 110     (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
 111
 112 # Documentation, issues, etc
 113
 114 Please refer to the comprehensive (albeit slightly outdated)
 115 [documentation][docs] for full customization
 116 and support.  If you find a bug, please report it on
 117 [the GitHub issue tracker][issues].  (please **do not** submit new issues to the old
 118 [googlecode tracker][googlecode tracker])
 119
 120 ## Important note regarding bug reporting
 121 If you think have found a bug, please report it clearly.  Yasnippet
 122 does have (lots of) bugs and your reports are very valuable. Here's
 123 a  [great example](https://github.com/capitaomorte/yasnippet/issues/318)
 124 of a bug report. It has everything needed for a sucessfull analysis and
 125 speedy resolution:
 126
 127 *Before* reporting try to reproduce the bug **without** your usual
 128 `.emacs` (or whatever startup file you use). Do so either by starting
 129 emacs from the command line with the `-Q` switch, or by temporarily
 130 moving away your `.emacs` and creating a new smaller one just for
 131 reproducing the bug. Paste that file in your bug report. Paste any sequence
 132 of relevant shell commands before you launch Emacs.
 133
 134 *Then*, describe steps taken to reproduce from an
 135 end-user perspective. Try to be as unambiguous as possible.
 136
 137 Also, don't forget to state the Emacs version (use `M-x emacs-version`) and
 138 the yasnippet version you are using (if using the latest from github,
 139 do `git log -1` in the dir).
 140
 141 Any more info is welcome, but don't just paste a backtrace or an error
 142 message string you got. I'm not saying your analysis might not be
 143 useful but following the instructions above immediately gives me a
 144 clear picture of what is happening.
 145
 146 There is also a [YASnippet google group][forum]. I will keep the group
 147 open for reference and for discussion among users, unfortunately I
 148 can't guarantee a timely response, so maybe creating a github issue
 149 clearly marking your intent (user support/bug/feature request).
 150
 151 Finally, thank you very much for using YASnippet!
 152
 153 [docs]: http://capitaomorte.github.com/yasnippet/
 154 [issues]: https://github.com/capitaomorte/yasnippet/issues
 155 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 156 [forum]: http://groups.google.com/group/smart-snippet
 157 [melpa]: http://melpa.milkbox.net/
 158 [yasmate]: http://github.com/capitaomorte/yasmate
 159 [yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets