mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 13:13:03 +00:00
doc: finally decided to write the manual in markdown
will use same or similar doc helpers
This commit is contained in:
João Távora
parent
ccea21bf99
commit
636c01d34a
257
doc/manual.mdown
Normal file
257
doc/manual.mdown
Normal file
@ -0,0 +1,257 @@
|
||||
Quick start
|
||||
===========
|
||||
|
||||
*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, SQL, LaTeX, HTML,
|
||||
CSS and more. The snippet syntax is inspired from TextMate's syntax, you can
|
||||
even [import most TextMate snippets](#import-textmate)
|
||||
|
||||
YASnippet is an original creation of [pluskid][pluskid] who also wrote its predecessor
|
||||
[smart-snippet][smart-snippet].
|
||||
|
||||
Watch a demo
|
||||
------------
|
||||
|
||||
Do so on [youtube][youtube]
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
Clone this repository somewhere
|
||||
|
||||
$ cd ~/.emacs.d/plugins
|
||||
$ git clone https://github.com/capitaomorte/yasnippet
|
||||
|
||||
Add the following in your =.emacs= file:
|
||||
|
||||
(add-to-list 'load-path
|
||||
"~/.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`.
|
||||
|
||||
Import textmate snippets (rails example)
|
||||
----------------------------------------
|
||||
|
||||
YASnippet lets you use TextMate bundles directly:
|
||||
|
||||
$ cd ~/.emacs.d/plugins
|
||||
$ git clone https://github.com/capitaomorte/yasnippet
|
||||
$ cd yasnippet
|
||||
$ git submodule init
|
||||
$ git submodule update
|
||||
$ gem install plist trollop
|
||||
$ rake convert_bundles # will convert ruby, rails and html bundles from drnic
|
||||
|
||||
Then, in your `.emacs` file
|
||||
|
||||
|
||||
(add-to-list 'load-path
|
||||
"~/.emacs.d/plugins/yasnippet")
|
||||
(require 'yasnippet)
|
||||
(setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))
|
||||
(yas/global-mode 1)
|
||||
|
||||
Open some rails file (model, app, etc) and start using the textmate
|
||||
snippets. Consider that this is a work-in-progress and many snippets/commands
|
||||
might not work. Patches welcome!
|
||||
|
||||
Contributing snippets
|
||||
---------------------
|
||||
|
||||
Please *do not ask me* to add snippets to the default collection under
|
||||
`/snippets`. This collection is considered frozen. By customizing
|
||||
`yas-snippet-dirs` you can point yasnippet to good snippet collections out
|
||||
there.
|
||||
|
||||
The `extras/textmate-import.rb` tool can import many actual Textmate snippets.
|
||||
I'm focusing on developing it and the accompanying `yas-setup.el` files that
|
||||
guide it with more difficult importations. The idea is to deprecate `/snippets=
|
||||
and replace it with =extras/imported`.
|
||||
|
||||
Documentation, issues, etc
|
||||
--------------------------
|
||||
|
||||
Please refer to the comprehensive [documentation](docs) for full
|
||||
customization and support. If you think you've found a bug, please report it
|
||||
on [the GitHub issue tracker](issues). (please **do not** submit new
|
||||
issues to the old [googlecode tracker](googlecode-tracker))
|
||||
|
||||
If you run into problems using YASnippet, or have snippets to contribute,
|
||||
post to the [yasnippet forum](forum). Thank you very much for using
|
||||
YASnippet!
|
||||
|
||||
Organizing snippets
|
||||
===================
|
||||
|
||||
Basic structure
|
||||
---------------
|
||||
|
||||
Snippet collections can be stored in plain text files. They are arranged by
|
||||
sub-directories naming *snippet tables*. These mostly name Emacs major names.
|
||||
|
||||
.
|
||||
|-- c-mode
|
||||
| `-- printf
|
||||
|-- java-mode
|
||||
| `-- println
|
||||
`-- text-mode
|
||||
|-- email
|
||||
`-- time
|
||||
|
||||
The collections are loaded into *snippet tables* which the triggering
|
||||
mechanism (see [Expanding snippets](#expand-snippets)) looks up and
|
||||
(hopefully) cause the right snippet to be expanded for you.
|
||||
|
||||
Setting up `yas-snippet-dirs`
|
||||
-----------------------------
|
||||
|
||||
The emacs variable `yas-snippet-dirs` tells YASnippet
|
||||
which collections to consider. It's used when you activate
|
||||
`yas-global-mode` or call
|
||||
`yas-reload-all` interactively.
|
||||
|
||||
The default considers:
|
||||
|
||||
- a personal collection that lives in `~/.emacs.d/snippets`
|
||||
- the bundled collection, taken as a relative path to `yasnippet.el` localtion
|
||||
|
||||
When you come across other snippet collections, do the following to try them
|
||||
out:
|
||||
|
||||
;; Develop in ~/emacs.d/mysnippets, but also
|
||||
;; try out snippets in ~/Downloads/interesting-snippets
|
||||
(setq yas/snippet-dirs '("~/emacs.d/mysnippets"
|
||||
"~/Downloads/interesting-snippets"))
|
||||
|
||||
;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
|
||||
(setq yas/snippet-dirs (append yas/snippet-dirs
|
||||
'("~/Downloads/interesting-snippets")))
|
||||
|
||||
Collections appearing earlier in the list shadow snippets with same names
|
||||
appearing in collections later in the list. `yas-new-snippet` always stores
|
||||
snippets in the first collection.
|
||||
|
||||
The `.yas.parents` file
|
||||
-----------------------
|
||||
|
||||
It's very useful to have certain modes share snippets between themselves. To do
|
||||
this, choose a mode subdirectory and place a `.yas-parents` containing a
|
||||
whitespace-separated list of other mode names. When you reload those modes
|
||||
become parents of the original mode.
|
||||
|
||||
.
|
||||
|-- c-mode
|
||||
| |-- .yas-parents # contains "cc-mode text-mode"
|
||||
| `-- printf
|
||||
|-- cc-mode
|
||||
| |-- for
|
||||
| `-- while
|
||||
|-- java-mode
|
||||
| |-- .yas-parents # contains "cc-mode text-mode"
|
||||
| `-- println
|
||||
`-- text-mode
|
||||
|-- email
|
||||
`-- time
|
||||
|
||||
The `.yas-make-groups` file
|
||||
---------------------------
|
||||
|
||||
If you place an empty plain text file `.yas-make-groups` inside one of the mode
|
||||
directories, the names of these sub-directories are considered groups of
|
||||
snippets and [the menu](snippet-menu) is organized much more cleanly:
|
||||
|
||||
(TODO image)
|
||||
|
||||
Another alternative way to achieve this is to place a `# group:` directive
|
||||
inside the snippet definition. See [Writing Snippets](#writing-snippets)
|
||||
|
||||
|
||||
$ tree ruby-mode/
|
||||
ruby-mode/
|
||||
|-- .yas-make-groups
|
||||
|-- collections
|
||||
| |-- each
|
||||
| `-- ...
|
||||
|-- control structure
|
||||
| |-- forin
|
||||
| `-- ...
|
||||
|-- definitions
|
||||
| `-- ...
|
||||
`-- general
|
||||
`-- ...
|
||||
|
||||
|
||||
Yet another way to create a nice snippet menu is to write into
|
||||
`.yas-make-groups` a menu definition. TODO
|
||||
|
||||
TODO The `.yas-setup.el` file
|
||||
-----------------------------
|
||||
|
||||
*** TODO
|
||||
|
||||
TODO The `.yas-compiled-snippet.el` file
|
||||
----------------------------------------
|
||||
|
||||
*** TODO
|
||||
|
||||
The `.yas-skip` file
|
||||
--------------------
|
||||
|
||||
Expanding Snippets
|
||||
==================
|
||||
|
||||
This section describes how YASnippet chooses snippets for expansion at point.
|
||||
|
||||
Maybe, you'll want some snippets to be expanded in a particular
|
||||
mode, or only under certain conditions, or be prompted using
|
||||
|
||||
Triggering expansion
|
||||
--------------------
|
||||
|
||||
To make a snippet expand after the cursor:
|
||||
|
||||
* Type an the snippet's *trigger key* then press the key defined in
|
||||
`yas-trigger-key`.
|
||||
|
||||
* Use the snippet's *keybinding*.
|
||||
|
||||
* Call [`yas-insert-snippet=](#yas-insert-snippet) (use `M-x
|
||||
yas-insert-snippet`= or its keybinding =C-c & C-s`).
|
||||
|
||||
* By expanding directly from the "YASnippet" menu in the menu-bar
|
||||
|
||||
* Using hippie-expand
|
||||
|
||||
* Use m2m's excellent [auto-complete](http://github.com/m2m/autocomplete)
|
||||
|
||||
Reference
|
||||
=========
|
||||
|
||||
(yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
|
||||
`("Customization variables" . ,#'(lambda (sym)
|
||||
(and (boundp sym)
|
||||
(get sym 'standard-value))))
|
||||
`("Useful functions" . ,#'fboundp)
|
||||
`("Useful variables" . ,#'boundp))
|
||||
|
||||
[smart-snippet]: http://code.google.com/p/smart-snippet
|
||||
[pluskid]: http://pluskid.lifegoo.org
|
||||
[screencast]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
|
||||
[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
|
||||
|
||||
|
||||
|
||||
<!--
|
||||
!-- Local Variables:
|
||||
!-- mode: markdown
|
||||
!-- fill-column: 80
|
||||
!-- coding: utf-8
|
||||
!-- End:
|
||||
!-- -->
|
||||
266
doc/manual.org
266
doc/manual.org
@ -1,266 +0,0 @@
|
||||
#+TITLE: Yet another snippet extension
|
||||
#+OPTIONS: toc:1
|
||||
#+STARTUP: showall
|
||||
|
||||
#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheets/styles.css" />
|
||||
|
||||
# External links
|
||||
#
|
||||
#+LINK: smart-snippet http://code.google.com/p/smart-snippet
|
||||
#+LINK: pluskid http://pluskid.lifegoo.org
|
||||
|
||||
#+LINK: screencast http://www.youtube.com/watch?v=ZCGmZK4V7Sg
|
||||
#+LINK: docs http://capitaomorte.github.com/yasnippet
|
||||
#+LINK: issues https://github.com/capitaomorte/yasnippet/issues
|
||||
#+LINK: googlecode-tracker http://code.google.com/p/yasnippet/issues/list
|
||||
#+LINK: forum http://groups.google.com/group/smart-snippet
|
||||
|
||||
|
||||
* Quick start
|
||||
|
||||
*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, SQL, LaTeX, HTML,
|
||||
CSS and more. The snippet syntax is inspired from TextMate's syntax, you can
|
||||
even [[#import-textmate][import most TextMate snippets]]
|
||||
|
||||
YASnippet is an original creation of [[pluskid]] who also wrote its predecessor
|
||||
[[smart-snippet]].
|
||||
|
||||
** Watch a demo
|
||||
|
||||
[[youtube]]
|
||||
|
||||
** Installation
|
||||
|
||||
Clone this repository somewhere
|
||||
|
||||
#+begin_example
|
||||
$ cd ~/.emacs.d/plugins
|
||||
$ git clone https://github.com/capitaomorte/yasnippet
|
||||
#+end_example
|
||||
|
||||
Add the following in your =.emacs= file:
|
||||
|
||||
#+begin_src emacs-lisp :exports code
|
||||
(add-to-list 'load-path
|
||||
"~/.emacs.d/plugins/yasnippet")
|
||||
(require 'yasnippet)
|
||||
(yas/global-mode 1)
|
||||
#+end_src
|
||||
|
||||
Add your own snippets to =~/.emacs.d/snippets= by placing files there or
|
||||
invoking [[#yas-new-snippet][=yas-new-snippet=]].
|
||||
|
||||
** Import textmate snippets (rails example)
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: import-textmate
|
||||
:END:
|
||||
|
||||
YASnippet lets you use TextMate bundles directly:
|
||||
|
||||
#+begin_example
|
||||
$ cd ~/.emacs.d/plugins
|
||||
$ git clone https://github.com/capitaomorte/yasnippet
|
||||
$ cd yasnippet
|
||||
$ git submodule init
|
||||
$ git submodule update
|
||||
$ gem install plist trollop
|
||||
$ rake convert_bundles # will convert ruby, rails and html bundles from drnic
|
||||
#+end_example
|
||||
|
||||
Then, in your =.emacs= file
|
||||
|
||||
#+begin_example
|
||||
(add-to-list 'load-path
|
||||
"~/.emacs.d/plugins/yasnippet")
|
||||
(require 'yasnippet)
|
||||
(setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))
|
||||
(yas/global-mode 1)
|
||||
#+end_example
|
||||
|
||||
Open some rails file (model, app, etc) and start using the textmate
|
||||
snippets. Consider that this is a work-in-progress and many snippets/commands
|
||||
might not work. Patches welcome!
|
||||
|
||||
** Contributing snippets
|
||||
|
||||
Please *do not ask me* to add snippets to the default collection under
|
||||
=/snippets=. This collection is considered frozen. By customizing
|
||||
[[#yas-snippet-dirs][=yas-snippet-dirs=]] you can point yasnippet to good
|
||||
snippet collections out there.
|
||||
|
||||
The =extras/textmate-import.rb= tool can import many actual Textmate
|
||||
snippets. I'm focusing on developing it and the accompanying =yas-setup.el=
|
||||
files that guide it with more difficult importations. The idea is to deprecate
|
||||
=/snippets= and replace it with =extras/imported=.
|
||||
|
||||
** Documentation, issues, etc
|
||||
|
||||
Please refer to the comprehensive [[docs][documentation]] for full
|
||||
customization and support. If you think you've found a bug, please report it
|
||||
on [[issues][the GitHub issue tracker]]. (please **do not** submit new
|
||||
issues to the old [[googlecode-tracker][googlecode tracker]])
|
||||
|
||||
If you run into problems using YASnippet, or have snippets to contribute,
|
||||
post to the [[forum][yasnippet forum]]. Thank you very much for using
|
||||
YASnippet!
|
||||
|
||||
* Organizing snippets
|
||||
|
||||
** Basic structure
|
||||
|
||||
Snippet collections can be stored in plain text files. They are arranged by
|
||||
sub-directories naming *snippet tables*. These mostly name Emacs major names.
|
||||
|
||||
#+begin_example
|
||||
.
|
||||
|-- c-mode
|
||||
| `-- printf
|
||||
|-- java-mode
|
||||
| `-- println
|
||||
`-- text-mode
|
||||
|-- email
|
||||
`-- time
|
||||
#+end_example
|
||||
|
||||
The collections are loaded into *snippet tables* which the triggering
|
||||
mechanism (see [[#expand-snippets][Expanding snippets]]) looks up and
|
||||
(hopefully) cause the right snippet to be expanded for you.
|
||||
|
||||
** Setting up =yas-snippet-dirs=
|
||||
|
||||
The emacs variable [[#yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
|
||||
which collections to consider. It's used when you activate
|
||||
[[#yas-global-mode][=yas-global-mode=]] or call
|
||||
[[#yas-reload-all][=yas-reload-all=]] interactively.
|
||||
|
||||
The default considers:
|
||||
|
||||
- a personal collection that lives in =~/.emacs.d/snippets=
|
||||
- the bundled collection, taken as a relative path to =yasnippet.el= localtion
|
||||
|
||||
When you come across other snippet collections, do the following to try them
|
||||
out:
|
||||
|
||||
#+begin_src emacs-lisp :exports code
|
||||
;; Develop in ~/emacs.d/mysnippets, but also
|
||||
;; try out snippets in ~/Downloads/interesting-snippets
|
||||
(setq yas/snippet-dirs '("~/emacs.d/mysnippets"
|
||||
"~/Downloads/interesting-snippets"))
|
||||
|
||||
;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
|
||||
(setq yas/snippet-dirs (append yas/snippet-dirs
|
||||
'("~/Downloads/interesting-snippets")))
|
||||
#+end_src
|
||||
|
||||
Collections appearing earlier in the list shadow snippets with same names
|
||||
appearing in collections later in the list. [[#yas-new-snippet][=yas-new-snippet=]] always stores
|
||||
snippets in the first collection.
|
||||
|
||||
** The =.yas.parents= file
|
||||
|
||||
It's very useful to have certain modes share snippets between themselves. To do
|
||||
this, choose a mode subdirectory and place a =.yas-parents= containing a
|
||||
whitespace-separated list of other mode names. When you reload those modes
|
||||
become parents of the original mode.
|
||||
|
||||
#+begin_example
|
||||
.
|
||||
|-- c-mode
|
||||
| |-- .yas-parents # contains "cc-mode text-mode"
|
||||
| `-- printf
|
||||
|-- cc-mode
|
||||
| |-- for
|
||||
| `-- while
|
||||
|-- java-mode
|
||||
| |-- .yas-parents # contains "cc-mode text-mode"
|
||||
| `-- println
|
||||
`-- text-mode
|
||||
|-- email
|
||||
`-- time
|
||||
#+end_example
|
||||
|
||||
** TODO The =.yas-make-groups= file
|
||||
|
||||
If you place an empty plain text file =.yas-make-groups= inside one of the
|
||||
mode directories, the names of these sub-directories are considered groups of
|
||||
snippets and [[snippet-menu][the menu]] is organized much more cleanly:
|
||||
|
||||
(TODO image)
|
||||
|
||||
Another alternative way to achieve this is to place a =# group:= directive
|
||||
inside the snippet definition. See [[#writing-snippets][Writing Snippets]]
|
||||
|
||||
#+begin_example
|
||||
$ tree ruby-mode/
|
||||
ruby-mode/
|
||||
|-- .yas-make-groups
|
||||
|-- collections
|
||||
| |-- each
|
||||
| `-- ...
|
||||
|-- control structure
|
||||
| |-- forin
|
||||
| `-- ...
|
||||
|-- definitions
|
||||
| `-- ...
|
||||
`-- general
|
||||
`-- ...
|
||||
#+end_example
|
||||
|
||||
Yet another way to create a nice snippet menu is to write into
|
||||
=.yas-make-groups= a menu definition. TODO
|
||||
|
||||
** TODO The =.yas-setup.el= file
|
||||
|
||||
*** TODO
|
||||
|
||||
** TODO The =.yas-compiled-snippet.el= file
|
||||
|
||||
*** TODO
|
||||
|
||||
** The =.yas-skip= file
|
||||
|
||||
* Expanding Snippets
|
||||
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: expand-snippets
|
||||
:END:
|
||||
|
||||
This section describes how YASnippet chooses snippets for expansion at point.
|
||||
|
||||
Maybe, you'll want some snippets to be expanded in a particular
|
||||
mode, or only under certain conditions, or be prompted using
|
||||
|
||||
** Triggering expansion
|
||||
|
||||
To make a snippet expand after the cursor:
|
||||
|
||||
* Type an the snippet's *trigger key* then press the key defined in
|
||||
[[#yas-trigger-key][=yas-trigger-key=]] (usually to "TAB").
|
||||
|
||||
* Use the snippet's *keybinding*.
|
||||
|
||||
* Call [[#yas-insert-snippet][=yas-insert-snippet=]] (use =M-x
|
||||
yas-insert-snippet== or its keybinding =C-c & C-s=).
|
||||
|
||||
* By expanding directly from the "YASnippet" menu in the menu-bar
|
||||
|
||||
* Using hippie-expand
|
||||
|
||||
* Use m2m's excellent auto-complete
|
||||
|
||||
* Reference
|
||||
#+BEGIN_SRC emacs-lisp :exports results :results value raw
|
||||
(yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
|
||||
`("Customization variables" . ,#'(lambda (sym)
|
||||
(and (boundp sym)
|
||||
(get sym 'standard-value))))
|
||||
`("Useful functions" . ,#'fboundp)
|
||||
`("Useful variables" . ,#'boundp))
|
||||
#+END_SRC
|
||||
# Local Variables:
|
||||
# mode: org
|
||||
# fill-column: 80
|
||||
# coding: utf-8
|
||||
# End:
|
||||
Loading…
x
Reference in New Issue
Block a user