mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 21:13:04 +00:00
move index.org subsection into snippet-organization.org
This almost completely overwrites the existing snippet-organization.org which was imported from snippet-organization.rst via pandoc.
This commit is contained in:
Noam Postavsky
parent
5acc976712
commit
875ef77dfb
114
doc/index.org
114
doc/index.org
@ -127,120 +127,6 @@
|
||||
If you run into problems using YASnippet, or have snippets to contribute,
|
||||
post to the [[http://groups.google.com/group/smart-snippet][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 [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
|
||||
which collections to consider. It's used when you activate
|
||||
[[sym:yas-global-mode][=yas-global-mode=]] or call
|
||||
[[sym: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. [[sym: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
|
||||
|
||||
|
||||
@ -1,107 +1,119 @@
|
||||
* Organizing snippets
|
||||
|
||||
** Loading snippets
|
||||
** Basic structure
|
||||
|
||||
Snippet definitions are stored in files in the filesystem. Unless you
|
||||
use the simpler [[index.html@installation][bundle version]]), these are
|
||||
arranged so that YASnippet can load them into /snippet tables/. The
|
||||
triggering mechanisms (see [[snippet-expansion.html][Expanding
|
||||
snippets]]) will look up these snippet tables and (hopefully) expand the
|
||||
snippet you intended.
|
||||
Snippet collections can be stored in plain text files. They are arranged by
|
||||
sub-directories naming *snippet tables*. These mostly name Emacs major names.
|
||||
|
||||
The non-bundle version of YASnippet, once unpacked, comes with a full
|
||||
directory of snippets, which you can copy somewhere and use. You can
|
||||
also create or download more directories.
|
||||
#+begin_example
|
||||
.
|
||||
|-- c-mode
|
||||
| `-- printf
|
||||
|-- java-mode
|
||||
| `-- println
|
||||
`-- text-mode
|
||||
|-- email
|
||||
`-- time
|
||||
#+end_example
|
||||
|
||||
Once these directories are in place reference them in the variable
|
||||
=yas-root-directory= and load them with =yas-load-directory=:
|
||||
The collections are loaded into *snippet tables* which the
|
||||
triggering mechanism (see [[file:snippet-expansion.org][Expanding Snippets]]) looks up and
|
||||
(hopefully) causes the right snippet to be expanded for you.
|
||||
|
||||
The point in using =yas-root-directory= (as opposed to calling
|
||||
=yas-load-directory= directly) is considering "~/emacs.d/mysnippets" for
|
||||
snippet development, so you can use commands like =yas-new-snippet= and
|
||||
others described in section [[snippet-development.html][Writing
|
||||
Snippets]].
|
||||
** Setting up =yas-snippet-dirs=
|
||||
|
||||
You can make this variable a list and store more items into it:
|
||||
The emacs variable [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
|
||||
which collections to consider. It's used when you activate
|
||||
[[sym:yas-global-mode][=yas-global-mode=]] or call
|
||||
[[sym:yas-reload-all][=yas-reload-all=]] interactively.
|
||||
|
||||
In this last example, the all the directories are loaded and their
|
||||
snippets considered for expansion. However development still happens in
|
||||
the first element, "~/emacs.d/mysnippets".
|
||||
The default considers:
|
||||
|
||||
** Organizing snippets
|
||||
- a personal collection that lives in =~/.emacs.d/snippets=
|
||||
- the bundled collection, taken as a relative path to =yasnippet.el= localtion
|
||||
|
||||
Once you've setup =yas-root-directory= , you can store snippets inside
|
||||
sub-directories of these directories.
|
||||
When you come across other snippet collections, do the following to try them
|
||||
out:
|
||||
|
||||
Snippet definitions are put in plain text files. They are arranged by
|
||||
sub-directories, and the snippet tables are named after these
|
||||
directories.
|
||||
#+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"))
|
||||
|
||||
The name corresponds to the Emacs mode where you want expansion to take
|
||||
place. For example, snippets for =c-mode= are put in the =c-mode=
|
||||
sub-directory.
|
||||
;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
|
||||
(setq yas-snippet-dirs (append yas-snippet-dirs
|
||||
'("~/Downloads/interesting-snippets")))
|
||||
#+end_src
|
||||
|
||||
*** The =.yas.parents= file
|
||||
Collections appearing earlier in the list shadow snippets with same names
|
||||
appearing in collections later in the list. [[sym:yas-new-snippet][=yas-new-snippet=]] always stores
|
||||
snippets in the first collection.
|
||||
|
||||
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.
|
||||
** The =.yas-parents= file
|
||||
|
||||
*** The =.yas-make-groups= 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.
|
||||
|
||||
[[images/menu-groups.png]]
|
||||
#+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
|
||||
|
||||
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.html][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
|
||||
[[snippet-development.html][Writing Snippets]].
|
||||
** TODO The =.yas-make-groups= file
|
||||
|
||||
** YASnippet bundle
|
||||
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.org][the menu]] is organized much more
|
||||
cleanly:
|
||||
|
||||
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.
|
||||
[[images/menu-groups.png]]
|
||||
|
||||
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.
|
||||
Another way to achieve this is to place a =# group:= directive
|
||||
inside the snippet definition. See [[snippet-development.org][Writing Snippets]].
|
||||
|
||||
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.
|
||||
#+begin_example
|
||||
$ tree ruby-mode/
|
||||
ruby-mode/
|
||||
|-- .yas-make-groups
|
||||
|-- collections
|
||||
| |-- each
|
||||
| `-- ...
|
||||
|-- control structure
|
||||
| |-- forin
|
||||
| `-- ...
|
||||
|-- definitions
|
||||
| `-- ...
|
||||
`-- general
|
||||
`-- ...
|
||||
#+end_example
|
||||
|
||||
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.
|
||||
Yet another way to create a nice snippet menu is to write into
|
||||
=.yas-make-groups= a menu definition. TODO
|
||||
|
||||
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.
|
||||
** TODO The =.yas-setup.el= file
|
||||
|
||||
See the internal documentation for these functions
|
||||
*** TODO
|
||||
|
||||
- =M-x describe-function RET yas-define-snippets RET=
|
||||
- =M-x describe-function RET yas-compile-bundle RET=.
|
||||
** TODO The =.yas-compiled-snippet.el= file
|
||||
|
||||
** Customizable variables
|
||||
*** TODO
|
||||
|
||||
*** =yas-root-directory=
|
||||
** TODO The =.yas-skip= file
|
||||
|
||||
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.
|
||||
*** TODO
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user