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