ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2025-10-13 21:13:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

a little bitt more work on the documentation

Browse Source
This commit is contained in:
João Távora 2012-07-23 00:33:55 +01:00
parent 2c3d80fcac
commit 6b35140c72
1 changed files with 1826 additions and 1914 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

240
doc/manual.org
View File

@ -100,31 +100,47 @@
Please refer to the comprehensive [[docs][documentation]] for full customization and 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 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 issue tracker]]. (please **do not** submit new issues to the old
tracker]]) [[googlecode-tracker][googlecode tracker]])
If you run into problems using YASnippet, or have snippets to contribute, post 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! to the [[forum][yasnippet forum]]. Thank you very much for using YASnippet!
* Organizing snippets * Organizing snippets
** Setting up =yas/snippet-dirs= ** Basic structure
Snippet collections are stored in specially organized file hierarchies. These Snippet collections can be stored in plain text files. They are arranged by
are loaded by YASnippet into *snippet tables* which the triggering mechanism sub-directories naming *snippet tables*. These mostly name Emacs major names.
(see [[expand-snippets][Expanding snippets]]) looks up and (hopefully) cause the right snippet to
#+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. be expanded for you.
** Setting up =yas/snippet-dirs=
An emacs variable =yas/snippet-dirs= tells YASnippet which collections to An emacs variable =yas/snippet-dirs= tells YASnippet which collections to
consider. It's used when you activate =yas/global-mode= or call consider. It's used when you activate =yas/global-mode= or call
=yas/reload-all= interactively. =yas/reload-all= interactively.
The default considers: The default considers:
- a personal collection that YASnippet decides lives in =~/.emacs.d/snippets= - a personal collection that lives in =~/.emacs.d/snippets=
- the bundled collection, taken as a relative path to =yasnippet.el= localtion - the bundled collection, taken as a relative path to =yasnippet.el= localtion
Once you come across other snippet collections, do the following to try them out: When you come across other snippet collections, do the following to try them
out:
#+begin_src emacs-lisp :exports both #+begin_src emacs-lisp :exports both
;; Develop in ~/emacs.d/mysnippets, but also ;; Develop in ~/emacs.d/mysnippets, but also
@ -137,27 +153,9 @@
'("~/Downloads/interesting-snippets"))) '("~/Downloads/interesting-snippets")))
#+end_src #+end_src
Collections appearing earlier in the list shadow any conflicting snippets Collections appearing earlier in the list shadow snippets with same names
from collections later in the list. =yas/new-snippet= always stores snippets appearing in collections later in the list. =yas/new-snippet= always stores
in the first collection. snippets in the first collection.
** Basic organization
Snippet definitions are stored in plain text files. They are arranged by
sub-directories naming snippet tables, which in turn name Emacs major names.
#+begin_example
.
|-- c-mode
| =-- printf
|-- java-mode
| =-- println
=-- text-mode
|-- email
=-- time
#+end_example
** The =.yas.parents= file ** The =.yas.parents= file
@ -182,163 +180,77 @@
=-- time =-- time
#+end_example #+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:
# 2. =Expanding Snippets=_ (TODO image)
# Describes how YASnippet chooses snippets for expansion at point. Another alternative way to achieve this is to place a ==# group:==
directive inside the snippet definition. See =Writing Snippets=_.
# Maybe, you'll want some snippets to be expanded in a particular #+begin_example
# mode, or only under certain conditions, or be prompted using $ tree ruby-mode/
# ==ido==, etc... ruby-mode/
|-- .yas-make-groups
|-- collections
| |-- each
| =-- ...
|-- control structure
| |-- forin
| =-- ...
|-- definitions
| =-- ...
=-- general
=-- ...
#+end_example
# 3. =Writing Snippets=_ Yet another way to create a nice snippet menu is to write into
=.yas-make-groups= a
# Describes the YASnippet definition syntax, which is very close (but ** TODO The =.yas-setup.el= file
# not equivalent) to Textmate's. Includes a section about converting
# TextMate snippets.
# 4. =The YASnippet menu=_ *** TODO
# Explains how to use the YASnippet menu to explore, learn and modify ** TODO The =.yas-compiled-snippet.el= file
# snippets.
*** TODO
** The =.yas-skip= file
# Loading snippets * Expanding Snippets
# ================
:PROPERTIES:
:CUSTOM_ID: expand-snippets
:END:
This section describes how YASnippet chooses snippets for expansion at point.
# Organizing snippets Maybe, you'll want some snippets to be expanded in a particular
# =================== mode, or only under certain conditions, or be prompted using
# Once you've setup ==yas/root-directory== , you can store snippets ** Triggering expansion
# inside sub-directories of these directories.
You can use YASnippet to expand snippets in different ways:
* Typing an abbreviation, the snippet *trigger key*, and then pressing the key
defined in ==yas/trigger-key== (usually to "TAB"). This works in buffers
where the minor mode ==yas/minor-mode== is active;
* By invoking the command ==yas/insert-snippet== (either by typing ==M-x
yas/insert-snippet== or its keybinding). This does *not*
require ==yas/minor-mode== to be active.
* By using the keybinding associated with an active snippet. This also
requires ==yas/minor-mode== to be active;
# The ==.yas-make-groups== file * By expanding directly from the "YASnippet" menu in the menu-bar
# -----------------------------
# .. image:: images/menu-groups.png * By using hippie-expand
# :align: right
# If you place an empty plain text file ==.yas-make-groups== inside one * Use m2m's excellent auto-complete
# of the mode directories, the names of these sub-directories are
# considered groups of snippets and =The YASnippet Menu=_ is organized
# much more cleanly, as you can see in the image.
# Another alternative way to achieve this is to place a ==# group:==
# directive inside the snippet definition. See =Writing Snippets=_.
# .. sourcecode:: text
# $ tree ruby-mode/
# ruby-mode/
# |-- .yas-make-groups
# |-- collections
# | |-- each
# | =-- ...
# |-- control structure
# | |-- forin
# | =-- ...
# |-- definitions
# | =-- ...
# =-- general
# =-- ...
# YASnippet bundle
# ================
# The most convenient way to define snippets for YASnippet is to put
# them in a directory arranged by the mode and use
# ==yas/load-directory== to load them.
# However, this might slow down the Emacs start-up speed if you have many
# snippets. You can use ==yas/define-snippets== to define a bunch of
# snippets for a particular mode in an Emacs-lisp file.
# Since this is hard to maintain, there's a better way: define your
# snippets in directory and then call ==M-x yas/compile-bundle== to
# compile it into a bundle file when you modified your snippets.
# The release bundle of YASnippet is produced by
# ==yas/compile-bundle==. The bundle uses ==yas/define-snippets== to
# define snippets. This avoids the IO and parsing overhead when loading
# snippets.
# Further more, the generated bundle is a stand-alone file not depending
# on ==yasnippet.el==. The released bundles of YASnippet are all
# generated this way.
# See the internal documentation for these functions
# \* ==M-x describe-function RET yas/define-snippets RET==
# \* ==M-x describe-function RET yas/compile-bundle RET==.
# Customizable variables
# ======================
# ==yas/root-directory==
# ----------------------
# Root directory that stores the snippets for each major mode.
# If you set this from your .emacs, can also be a list of strings,
# for multiple root directories. If you make this a list, the first
# element is always the user-created snippets directory. Other
# directories are used for bulk reloading of all snippets using
# ==yas/reload-all==
# ==yas/ignore-filenames-as-triggers==
# ------------------------------------
# If non-nil, don't derive tab triggers from filenames.
# This means a snippet without a ==# key:== directive wont have a tab
# trigger.
# .. LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl
# .. LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el
# .. LocalWords: rjs RET
# * snippet-expansion.org
# ==================
# Expanding snippets
# ==================
# .. _Organizing Snippets: snippet-organization.html
# .. _Expanding Snippets: snippet-expansion.html
# .. _Writing Snippets: snippet-development.html
# .. _The YASnippet Menu: snippet-menu.html
# .. contents::
# Triggering expansion
# ====================
# You can use YASnippet to expand snippets in different ways:
# \* By typing an abbrev, the snippet *trigger key*, and then pressing
# the key defined in ==yas/trigger-key== (which defaults to
# "TAB"). This works in buffers where the minor mode
# ==yas/minor-mode== is active;
# \* By invoking the command ==yas/insert-snippet== (either by typing
# ==M-x yas/insert-snippet== or its keybinding). This does *not*
# require ==yas/minor-mode== to be active.
# \* By using the keybinding associated with an active snippet. This also
# requires ==yas/minor-mode== to be active;
# \* By expanding directly from the "YASnippet" menu in the menu-bar
# \* By using hippie-expand
# \* Expanding from emacs-lisp code # \* Expanding from emacs-lisp code