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