code.delx.au - gnu-emacs-elpa/blob - README.mdown

   1 # Intro
   2
   3 **YASnippet** is a template system for Emacs. It allows you to
   4 type an abbreviation and automatically expand it into function
   5 templates. Bundled language templates include: C, C++, C#, Perl,
   6 Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax
   7 is inspired from [TextMate's][textmate-snippets] syntax, you can
   8 even [import][import-docs] most TextMate templates to
   9 YASnippet. Watch [a demo on YouTube][youtube-demo] or download a
  10 [higher resolution version][high-res-demo].
  11
  12 [textmate-snippets]: http://manual.macromates.com/en/snippets
  13 [import-docs]: http://yasnippet.googlecode.com/svn/trunk/doc/snippet-development.html#importing-textmate-snippets
  14 [youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
  15 [high-res-demo]: http://yasnippet.googlecode.com/files/yas_demo.avi
  16
  17 # Installation
  18
  19 ## Install the most recent version
  20
  21 Clone this repository somewhere
  22
  23     $ cd ~/.emacs.d/plugins
  24     $ git clone https://github.com/capitaomorte/yasnippet
  25
  26 Add the following in your `.emacs` file:
  27
  28     (add-to-list 'load-path
  29                   "~/.emacs.d/plugins/yasnippet")
  30     (require 'yasnippet)
  31     (yas-global-mode 1)
  32
  33 Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`.
  34
  35 ## Install with `package-install`
  36
  37 In a recent emacs `M-x list-packages` is the recommended way to list and install packages.
  38 [MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing.
  39
  40 ## Install with el-get
  41
  42 El-get is a nice way to get the most recent version, too. See
  43 https://github.com/dimitri/el-get for instructions. Be sure to install the
  44 "master" branch since the 3.x series still use the old googlecode code, base.
  45 Consider using this "local" recipe.
  46
  47     (push '(:name yasnippet
  48                   :website "https://github.com/capitaomorte/yasnippet.git"
  49                   :description "YASnippet is a template system for Emacs."
  50                   :type github
  51                   :pkgname "capitaomorte/yasnippet"
  52                   :features "yasnippet"
  53                   :compile "yasnippet.el")
  54           el-get-sources)
  55
  56 ## Use `yas-minor-mode` on a per-buffer basis
  57
  58 To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
  59 `(yas-reload-all)` to load the snippet tables. Then add a call to
  60 `(yas-minor-mode)` to the major-modes where you to enable YASnippet.
  61
  62     (add-hook 'prog-mode-hook
  63               '(lambda ()
  64                  (yas-minor-mode)))
  65
  66 # (NOT) Contributing snippets
  67
  68 Please **do not** open pull requests or ask me to add snippets to
  69 YASnippet.
  70
  71 The bundled collection under `/snippets` is considered frozen: **I
  72 will not add more snippets to it**.
  73
  74 You can point `yas-snippet-dirs` to good snippet collections out
  75 there. If you have created snippets for a mode, or multiple modes,
  76 consider creating a repository to host them, then tell users that it
  77 should be added like this to `yas-snippet-dirs`:
  78
  79     (setq yas-snippet-dirs
  80           '("~/.emacs.d/snippets"            ;; personal snippets
  81             "/path/to/some/collection/"      ;; just some foo-mode snippets
  82             "/path/to/some/othercollection/" ;; some more foo-mode and a complete baz-mode
  83             "/path/to/yasnippet/snippets"    ;; the default collection
  84             ))
  85
  86     (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
  87
  88 # Importing TextMate snippets
  89
  90 There is a tool `extras/textmate-import.rb` than can import many
  91 actual TextMate snippets. These can be quite complex so the
  92 `extras/imported/*-mode/.yas-setup.el` files help it with the more
  93 difficult importation.
  94
  95 I'm focusing on developing `textmate-import.rb` tool and some
  96 `yas-setup.el` files. In the future `/snippets` snippets will be
  97 deprecated and might be replaced with `extras/imported`.
  98
  99 ## Example importation of rails snippets
 100
 101 To start using [drnic's](https://github.com/drnic) snippets for rails
 102 development, follow this example. It will convert `ruby`, `rails` and
 103 `html` bundles from github repositories. The importation will be
 104 guided by the `.yas-setup.el` files.
 105
 106 After cloning this repository to `~/.emacs.d/plugins/yasnippet`
 107
 108     cd ~/.emacs.d/plugins/yasnippet
 109     git submodule init
 110     git submodule update
 111     gem install plist trollop
 112     rake convert_bundles             # will convert ruby, rails and html bundles
 113
 114 Then, in your `.emacs` file
 115
 116     (add-to-list 'load-path
 117                   "~/.emacs.d/plugins/yasnippet")
 118     (require 'yasnippet)
 119     (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported"))
 120     (yas-global-mode 1)
 121
 122 Open some rails file (model, app, etc) and start using the textmate
 123 snippets.  Note that in the example above we have abandoned the
 124 default snippet collection on `~/.emacs.d/plugins/yasnippet/snippets`
 125
 126 # Documentation, issues, etc
 127
 128 Please refer to the comprehensive (albeit slightly outdated)
 129 [documentation][docs] for full customization
 130 and support.  If you find a bug, please report it on
 131 [the GitHub issue tracker][issues].  (please **do not** submit new issues to the old
 132 [googlecode tracker][googlecode tracker])
 133
 134 ## Important note regarding bug reporting
 135 If you think have found a bug, please report it clearly.  Yasnippet
 136 does have (lots of) bugs and your reports are very valuable. Here's
 137 a  [great example](https://github.com/capitaomorte/yasnippet/issues/318)
 138 of a bug report. It has everything needed for a sucessfull analysis and
 139 speedy resolution:
 140
 141 *Before* reporting try to reproduce the bug **without** your usual
 142 `.emacs` (or whatever startup file you use). Do so either by starting
 143 emacs from the command line with the `-Q` switch, or by temporarily
 144 moving away your `.emacs` and creating a new smaller one just for
 145 reproducing the bug. Paste that file in your bug report. Paste any sequence
 146 of relevant shell commands before you launch Emacs.
 147
 148 *Then*, describe steps taken to reproduce from an
 149 end-user perspective. Try to be as unambiguous as possible.
 150
 151 Also, don't forget to state the Emacs version (use `M-x emacs-version`) and
 152 the yasnippet version you are using (if using the latest from github,
 153 do `git log -1` in the dir).
 154
 155 Any more info is welcome, but don't just paste a backtrace or an error
 156 message string you got. I'm not saying your analysis might not be
 157 useful but following the instructions above immediately gives me a
 158 clear picture of what is happening.
 159
 160 There is also a [YASnippet google group][forum]. I will keep the group
 161 open for reference and for discussion among users, unfortunately I
 162 can't guarantee a timely response, so maybe creating a github issue
 163 clearly marking your intent (user support/bug/feature request).
 164
 165 Finally, thank you very much for using YASnippet!
 166
 167 [docs]: http://capitaomorte.github.com/yasnippet/
 168 [issues]: https://github.com/capitaomorte/yasnippet/issues
 169 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 170 [forum]: http://groups.google.com/group/smart-snippet
 171 [melpa]: http://melpa.milkbox.net/