X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/4e3ecebe4b0db3f0b36ed702d0dbea7c6478d519..146b161112b68c99ecd607ec5360accc1f4db3cd:/README.mdown diff --git a/README.mdown b/README.mdown index 6d84d7977..664655749 100644 --- a/README.mdown +++ b/README.mdown @@ -1,76 +1,171 @@ -# Intro +[![Build Status](https://travis-ci.org/capitaomorte/yasnippet.png)](https://travis-ci.org/capitaomorte/yasnippet) -**YASnippet** is a template system for Emacs. It allows you to type an -abbreviation and automatically expand it into function -templates. Bundled language templates includes: C, C++, C#, Perl, -Python, Ruby, +# Intro -SQL, LaTeX, HTML, CSS and more. The snippet syntax is inspired from -[TextMate's][textmate-snippets] syntax, you can even -[import][import-docs] most TextMate templates to YASnippet. Watch -[a demo on YouTube][youtube-demo] or download a -[higher resolution version][high-res-demo] +**YASnippet** is a template system for Emacs. It allows you to +type an abbreviation and automatically expand it into function +templates. Bundled language templates include: C, C++, C#, Perl, +Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax +is inspired from [TextMate's][textmate-snippets] syntax, you can +even [import](#import) most TextMate templates to +YASnippet. Watch [a demo on YouTube][youtube-demo]. [textmate-snippets]: http://manual.macromates.com/en/snippets -[import-docs]: http://yasnippet.googlecode.com/svn/trunk/doc/snippet-development.html#importing-textmate-snippets -[youtube-demo]: http://www.youtube.com/watch?v=76Ygeg9miao -[high-res-demo]: http://yasnippet.googlecode.com/files/yas_demo.avi - -# Install with yasnippet-bundle.el - -To quickly tryout YASnippet, download the simpler "bundle" version. -If you plan to modify the bundled templates and/or build your own, -download the "normal" package. - -* Download `yasnippet-bundle` from the downloads section. - -* You'll get a file named `yasnippet-bundle.el`, put it in - `~/.emacs.d/plugins/` (create that directory if not exists). - -* Open the file in Emacs, and type `M-x eval-buffer RET`. - -That's it. Now open any file, you'll see a menu "YASnippet". You can -pull down the menu to insert a template. Or, you can type a -pre-defined abbrev and press TAB to expand it! - -To have Emacs load YASnippet automatically when it starts, put the -following in your ~/.emacs file: - - (add-to-list 'load-path - "~/.emacs.d/plugins") - (require 'yasnippet-bundle) +[youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg +# Installation -# Install +## Install the most recent version -To install the normal archive, download and unpack the latest -`yasnippet-x.y.z.tar.bz2`. You'll get a directory named -`yasnippet-x.y.z`, put it in some `~/.emacs.d/plugins` dir and add the -following in your `.emacs` file: +Clone this repository somewhere + + $ cd ~/.emacs.d/plugins + $ git clone --recursive https://github.com/capitaomorte/yasnippet + +Add the following in your `.emacs` file: (add-to-list 'load-path - "~/.emacs.d/plugins/yasnippet-x.y.z") - (require 'yasnippet) ;; not yasnippet-bundle - (yas/initialize) - (yas/load-directory "~/.emacs.d/plugins/yasnippet-x.y.z/snippets") + "~/.emacs.d/plugins/yasnippet") + (require 'yasnippet) + (yas-global-mode 1) +Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`. -# How-tos, Bugs, Contributions... +## Install with `package-install` -Please refer to the comprehensive [documentation] [docs] for full -customization and support. If you find a bug, please report it on -[the GitHub issue tracker][issues]. (please **do not** the deprecated -[googlecode tracker][googlecode tracker]) +In a recent emacs `M-x list-packages` is the recommended way to list and install packages. +[MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.org/#installing. -If you run into problems using YASnippet, or have snippets to -contribute, post to the -[yasnippet google group][forum]. Thank -you very much for using YASnippet! +## Install with el-get -[docs]: http://yasnippet.googlecode.com/svn/trunk/doc/index.html -[issues]: https://github.com/capitaomorte/yasnippet/issues -[googlecode tracker]: http://code.google.com/p/yasnippet/issues/list -[forum]: http://groups.google.com/group/smart-snippet +El-get is a nice way to get the most recent version, too. See +https://github.com/dimitri/el-get for instructions. + +## Use `yas-minor-mode` on a per-buffer basis + +To use YASnippet as a non-global minor mode, don't call +`yas-global-mode`; instead call `yas-reload-all` to load the snippet +tables and then call `yas-minor-mode` from the hooks of major-modes +where you want YASnippet enabled. + + (yas-reload-all) + (add-hook 'prog-mode-hook #'yas-minor-mode) + +# Where are the snippets? + + + +Yasnippet no longer bundles snippets directly, but it's very easy to +get some! + +If you git-cloned yasnippet with the `--recursive` option you'll also +download "git submodules" and find two subdirs under the main tree. + +1. `snippets/` + + Points to [yasnippet-snippets] the snippet collection of + [AndreaCrotti](https://github.com/AndreaCrotti). + + The default configuraiton already points to this dir, so to use + them, just make sure the submodule really was downloaded + (i.e. there are some files under `snippets/`) + +2. `yasmate/` + + Points to a github repo of the [yasmate] tool, which is dedicated + to converting textmate bundles into yasnippet snippets. + + To use these snippets you have to run the tool first, so + [see its doc][yasmate]), and then point the `yas-snippet-dirs` + variable to the `.../yasmate/snippets` subdir. + + If you have a working ruby environment, you can probably get lucky + directly with `rake convert-bundles`. +3. [textmate-to-yas.el] + This is another textmate bundle converting tool using Elisp + instead of Ruby. +Naturally, you can point `yas-snippet-dirs` to good snippet collections out +there. If you have created snippets for a mode, or multiple modes, +consider creating a repository to host them, then tell users that it +should be added like this to `yas-snippet-dirs`: + + (setq yas-snippet-dirs + '("~/.emacs.d/snippets" ;; personal snippets + "/path/to/some/collection/" ;; foo-mode and bar-mode snippet collection + "/path/to/yasnippet/yasmate/snippets" ;; the yasmate collection + "/path/to/yasnippet/snippets" ;; the default collection + )) + + (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already. + +# Manual, issues etc + +Please refer to the comprehensive [documentation][docs] for full +customisation and support. If you find a bug in the code or in the +documentation, please report it on [the GitHub issue tracker][issues]. + +## Important note regarding bug reporting + +Your bug reports are very valuable. + +The most important thing when reporting bugs is making sure that we have +a way to reproduce the problem exactly like it happened to you. + +To do this, we need to rule out interference from external factors +like other Emacs extensions or your own customisations. + +Here's an example report that "sandboxes" an Emacs session just for +reproducing a bug. + +``` +$ emacs --version +Emacs 24.3 +$ cd /tmp/ +$ git clone https://github.com/capitaomorte/yasnippet.git yasnippet-bug +$ cd yasnippet-bug +$ git log -1 --oneline +6053db0 Closes #527: Unbreak case where yas-fallback-behaviour is a list +$ HOME=$PWD emacs -L . # This "sandboxes" your emacs, melpa configuration, etc + +(require 'yasnippet) +(yas-global-mode 1) + +When I open a foo-mode file I don't see foo-mode under the "YASnippet" menu! +OR +When loading yasnippet I see "Error: failed to frobnicate"! +``` + +Using `emacs -Q` or temporarily moving your `.emacs` init file to the side +is another way to achieve good reproducibility. + +Here's a +[another example](https://github.com/capitaomorte/yasnippet/issues/318) +of a bug report. It has everything needed for a successful analysis +and speedy resolution. + +Also, don't forget to state the Emacs version (use `M-x emacs-version`) and +the yasnippet version you are using (if using the latest from github, +do `git log -1` in the dir). + +Any more info is welcome, but don't just paste a backtrace or an error +message string you got, unless we ask for it. + +There is also a [YASnippet google group][forum]. I will keep the group +open for reference and for discussion among users. Unfortunately I +can't guarantee a timely response, so maybe it's better to create a +github issue clearly marking your intent (user support/bug/feature +request). + +Finally, thank you very much for using YASnippet! + +[docs]: http://capitaomorte.github.com/yasnippet/ +[issues]: https://github.com/capitaomorte/yasnippet/issues +[googlecode tracker]: http://code.google.com/p/yasnippet/issues/list +[forum]: http://groups.google.com/group/smart-snippet +[melpa]: http://melpa.milkbox.net/ +[yasmate]: http://github.com/capitaomorte/yasmate +[textmate-to-yas.el]: https://github.com/mattfidler/textmate-to-yas.el +[yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets