- - Home + Intro and tutorial
- - Organize + Howto: organize
- - Expand + Howto: expand
- - Write + Howto: write + +
- + Howto: menu
-
FAQ
diff --git a/doc/index.html b/doc/index.html
index 864538c..8b7f40f 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -20,16 +20,19 @@
- - Home + Intro and tutorial
- - Organize + Howto: organize
- - Expand + Howto: expand
- - Write + Howto: write + +
- + Howto: menu
-
FAQ
diff --git a/doc/snippet-development.html b/doc/snippet-development.html
index 3504695..aea88ca 100644
--- a/doc/snippet-development.html
+++ b/doc/snippet-development.html
@@ -20,16 +20,19 @@
- - Home + Intro and tutorial
- - Organize + Howto: organize
- - Expand + Howto: expand
- - Write + Howto: write + +
- + Howto: menu
-
FAQ
diff --git a/doc/snippet-expansion.html b/doc/snippet-expansion.html
index 94e7a2c..6d346f6 100644
--- a/doc/snippet-expansion.html
+++ b/doc/snippet-expansion.html
@@ -20,16 +20,19 @@
- - Home + Intro and tutorial
- - Organize + Howto: organize
- - Expand + Howto: expand
- - Write + Howto: write + +
- + Howto: menu
-
FAQ
diff --git a/doc/snippet-menu.html b/doc/snippet-menu.html
new file mode 100644
index 0000000..32b0bdb
--- /dev/null
+++ b/doc/snippet-menu.html
@@ -0,0 +1,89 @@
+
+
+
+
+
+
+
The menu + + + + + ++ ++ + diff --git a/doc/snippet-organization.html b/doc/snippet-organization.html index 758f550..924a18f 100644 --- a/doc/snippet-organization.html +++ b/doc/snippet-organization.html @@ -20,16 +20,19 @@++++++++The menu
+-
+
- + Intro and tutorial + +
- + Howto: organize + +
- + Howto: expand + +
- + Howto: write + +
- + Howto: menu + +
- + FAQ + +
- + ChangeLog + +
- + Download + +
++++++++YASnippet will setup a menu just after the Buffers Menu in the +menubar. The snippets for all real modes are listed there under the +menu. You can select a snippet from the menu to expand it. Since you +select manually from the menu, you can expand any snippet. For +example, you can expand a snippet defined for python-mode in a +c-mode buffer by selecting it from the menu:
+
+-
+
- Condition system is ignored since you select to expand it +explicitly. +
- There will be no muliple candidates since they are listed in the +menu as different items. +
This can be convenient sometimes. However, if you don't like the +menubar of Emacs and never use it. You can tell YASnippet don't boring +to build a menu by setting yas/use-menu to nil.
+Another thing to note is that only real modes are listed under the +menu. As you know, common snippets can be shared by making up a +virtual parent mode. It's too bad if the menu is floored by those +virtual modes. So YASnippet only show menus for those real +modes. But the snippets fo the virtual modes can still be accessed +through the parent submenu of some real mode.
+YASnippet use a simple way to check whether a mode is real or +virtual: (fboundp mode). For example, the symbol c-mode is +bound to a function while cc-mode is not. But this is not enough, +some modes aren't part of Emacs, and maybe when initializing +YASnippet, those modes haven't been initialized. So YASnippet also +maintain a list of known modes (yas/known-modes). You can add item +to that list if you need.
+- - Home + Intro and tutorial
- - Organize + Howto: organize
- - Expand + Howto: expand
- - Write + Howto: write + +
- + Howto: menu
-
FAQ
@@ -49,270 +52,179 @@
-
Contents
There are three ways to keep your snippets:
--diff --git a/doc/snippet-organization.rst b/doc/snippet-organization.rst index a27e456..c4e5367 100644 --- a/doc/snippet-organization.rst +++ b/doc/snippet-organization.rst @@ -8,300 +8,205 @@ Organizing snippets .. contents:: -There are three ways to keep your snippets: +Loading snippets +================ + +Snippet definitions are stored in files in the filesystem and you have +to arrange for YASnippet to load them (unless you use a `YASnippet +bundleNew-style storage (recommended)
-Hehe
+++Loading snippets
+Snippet definitions are stored in files in the filesystem and you have +to arrange for YASnippet to load them (unless you use a YASnippet +bundle (see No storage (bundle)),
+The non-bundle version of YASsnippet, once unpacked, comes with a full +directory of snippets, which you can copy somewhere and use. You can +also create or download, one or more directories.
+Once these are in place reference them in the variable +yas/root-directory and then load them with yas/load-directory:
++;; Develop and keep personal snippets under ~/emacs.d/mysnippets +(setq yas/root-directory "~/emacs.d/mysnippets") + +;; Load the snippets +(yas/load-directory yas/root-directory) +
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 here)
+If you make this variable a list and store more items into it...
++;; Develop in ~/emacs.d/mysnippets, but also +;; try out snippets in ~/Downloads/interesting-snippets +(setq yas/root-directory '("~/emacs.d/mysnippets" + "~/Downloads/interesting-snippets")) + +;; Map `yas/load-directory' to every element +(mapc 'yas/load-directory yas/root-directory) +, the directories after the first are loaded, their snippets +considered for expansion, but development still happens in +"~/emacs.d/mysnippets"
++Organizing snippets
+Once you've setup yas/root-directory , you can store snippets +inside subdirectories of these directories.
+Common to both cases, snippet definitions are put in plain text +files. They are arranged by subdirectories, and the name of these +directories correspond to the Emacs mode where you want expansion to +take place. For example, snippets for c-mode are put in the +c-mode subdirectory. You can also skip snippet storage altogether +and use the bundle (see No storage (bundle)).
+++Nested organization
+Here is an excerpt of a directory hierarchy containing snippets +for some modes:
++$ tree +. +`-- text-mode + |-- cc-mode + | |-- c-mode + | | `-- printf + | |-- for + | |-- java-mode + | | `-- println + | `-- while + |-- email + |-- perl-mode + | |-- cperl-mode + | `-- for + `-- time +
The parent directory acts as the parent mode. This is the way of +YASnippet to share snippet definitions among different modes. As you +can see above, c-mode and java-mode share the same parents +cc-mode, while all modes are derived from text-mode. This can +be also used to as an alias -- cperl-mode is an empty directory +whose parent is perl-mode.
+++The .yas-parents file
+If you place a plain text file .yas-parents inside one of the +subdirectories you can bypass nesting and still have parent modes. In +this file you just write whitespace-separated names of modes. This +allows more flexibility and readability of your snippet hierarchy.
++$ tree +. +|-- 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 subdirectories are +considered groups of snippets and the YASsnippet 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
++$ tree ruby-mode/ +ruby-mode/ +|-- .yas-make-groups +|-- collections +| |-- each +| `-- ... +|-- control structure +| |-- forin +| `-- ... +|-- definitions +| `-- ... +`-- general + `-- ... +
+-Using plain file names
+Normally, file names act as the snippet trigger key, see Expanding +snippets. However, if you customize the +variable yas/ignore-filenames-as-triggers to be true or place an +empty file .yas-ignore-filename-triggers you can use much more +descriptive file names. This is useful (but not mandatory) if many +snippets within a mode share the same trigger key.
+$ tree rails-mode/ +rails-mode/ +|-- .yas-make-groups +|-- .yas-ignore-filename-triggers +|-- Insert ERb's <% __ %> or <%= __ %>.yasnippet +|-- asserts +| |-- assert(var = assigns(%3Avar)).yasnippet +| |-- assert_difference.yasnippet +| |-- assert_no_difference.yasnippet +| |-- assert_redirected_to (nested path plural).yasnippet +| |-- assert_redirected_to (nested path).yasnippet +| |-- assert_redirected_to (path plural).yasnippet +| |-- assert_redirected_to (path).yasnippet +| |-- assert_rjs.yasnippet +| `-- assert_select.yasnippet +
-Old-style storage (pre 0.6)
-Blabla
--No storage (bundle)
+No storage (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 startup speed if you have many snippets. You can use yas/define-snippets to define a bunch of -snippets for a perticular mode. But this is hard to maintain! So, -there's a better way: define your snippets in directory and use -yas/compile-bundle to compile it into a bundle file when you -modified your snippets.
+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 use yas/define-snippets to -define snippets. This avoid the IO and parsing overhead when loading +yas/compile-bundle. The bundle uses yas/define-snippets to +define snippets. This avoids the IO and parsing overhead when loading snippets.
-Finally, you can use yas/define to define a single snippet at your -convenience. I ofthen use this to do some testing.
--Define snippets in files
---Directory hierarchy
-Here's the directory hierarchy of the snippets directory comes -with YASnippet:
--snippets -`-- text-mode/ - |-- cc-mode/ - | |-- c++-mode/ - | | |-- beginend - | | |-- class - | | `-- using - | |-- c-mode/ - | | `-- fopen - | |-- do - | |-- for - | |-- if - | |-- inc - | |-- inc.1 - | |-- main - | |-- once - | `-- struct - |-- css-mode/ - | |-- background - | |-- background.1 - | `-- border - |-- email - |-- html-mode/ - | |-- div - | |-- doctype - | |-- doctype.xhml1 - | |-- doctype.xhtml1_1 - | |-- doctype.xhtml1_strict - | `-- doctype.xhtml1_transitional - |-- objc-mode/ - | `-- prop - |-- perl-mode/ - | |-- cperl-mode/ - | |-- eval - | |-- for - | |-- fore - | |-- if - | |-- ife - | |-- ifee - | |-- sub - | |-- unless - | |-- while - | |-- xfore - | |-- xif - | |-- xunless - | `-- xwhile - |-- python-mode/ - | |-- __ - | |-- class - | |-- def - | |-- for - | |-- ifmain - | `-- while - |-- rst-mode/ - | |-- chapter - | |-- section - | `-- title - |-- ruby-mode/ - | |-- # - | |-- =b - | |-- Comp - | |-- all - | |-- am - | |-- any - | |-- app - | |-- bm - | |-- case - | |-- cla - | |-- classify - | |-- cls - | |-- collect - | |-- dee - | |-- deli - | |-- det - | |-- ea - | |-- eac - | |-- eai - | |-- eav - | |-- eawi - | |-- forin - | |-- if - | |-- ife - | |-- inject - | |-- mm - | |-- r - | |-- rb - | |-- reject - | |-- req - | |-- rreq - | |-- rw - | |-- select - | |-- w - | |-- y - | `-- zip - `-- time -
Snippet definitions are put in plain text files. They are arranged by -subdirectories. For example, snippets for c-mode are put in the -c-mode directory.
-The parent directory acts as the parent mode. This is the way of -YASnippet to share snippet definitions among different modes. As you -can see above, c-mode and c++-mode share the same parents -cc-mode, while all modes are derived from text-mode. This can -be also used to as an alias -- cperl-mode is an empty directory -whose parent is perl-mode.
-File names act as the snippet trigger key. Note files starting with a -dot (.) are ignored.
--+Define snippets using elisp code
-As I mentioned above, you can define snippets directly by writing -elisp code.
---yas/define-snippets
-The basic syntax of yas/define-snippets is
--(yas/define-snippets MODE SNIPPETS &optional PARENT) -
The parameters are self-descriptive. If you specify a PARENT, then -the snippets of the parents may be shared by MODE. Note if you use -this function several times, the later specified PARENT will -overwrite the original one. However, not specifying a PARENT won't -erase the original parent.
-The SNIPPETS parameter is a list of snippet definitions. Each -element should have the following form:
--(KEY TEMPLATE NAME CONDITION GROUP) -
The NAME, CONDITION and GROUP can be omitted if you don't -want to provide one. Here's an example:
--(yas/define-snippets 'c++-mode -'( - ("using" "using namespace ${std}; -$0" "using namespace ... " nil) - ("class" "class ${1:Name} -{ -public: - $1($2); - virtual ~$1(); -};" "class ... { ... }" nil) - ("beginend" "${1:v}.begin(), $1.end" "v.begin(), v.end()" nil) - ) -'cc-mode) -
The example above is auto-generated code by yas/compile-bundle.
---yas/define
-The basic syntax for yas/define is
--(yas/define mode key template &optional name condition group) -
This is only a syntax sugar for
--(yas/define-snippets mode - (list (list key template name condition group))) -
--yas/compile-bundle
-yas/compile-bundle can be used to parse the snippets from a -directory hierarchy and translate them into the elisp form. The -translated code is faster to load. 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.
---The Menu
-YASnippet will setup a menu just after the Buffers Menu in the -menubar. The snippets for all real modes are listed there under the -menu. You can select a snippet from the menu to expand it. Since you -select manually from the menu, you can expand any snippet. For -example, you can expand a snippet defined for python-mode in a -c-mode buffer by selecting it from the menu:
-
--
-
- Condition system is ignored since you select to expand it -explicitly. -
- There will be no muliple candidates since they are listed in the -menu as different items. -
This can be convenient sometimes. However, if you don't like the -menubar of Emacs and never use it. You can tell YASnippet don't boring -to build a menu by setting yas/use-menu to nil.
-Another thing to note is that only real modes are listed under the -menu. As you know, common snippets can be shared by making up a -virtual parent mode. It's too bad if the menu is floored by those -virtual modes. So YASnippet only show menus for those real -modes. But the snippets fo the virtual modes can still be accessed -through the parent submenu of some real mode.
-YASnippet use a simple way to check whether a mode is real or -virtual: (fboundp mode). For example, the symbol c-mode is -bound to a function while cc-mode is not. But this is not enough, -some modes aren't part of Emacs, and maybe when initializing -YASnippet, those modes haven't been initialized. So YASnippet also -maintain a list of known modes (yas/known-modes). You can add item -to that list if you need.
-The basic syntax of yas/compile-bundle is
--(yas/compile-bundle &optional yasnippet yasnippet-bundle snippet-roots code dropdown) -
As you can see, all the parameters are optional. The default values -for those parameters are convenient for me to produce the default -release bundle:
--(yas/compile-bundle "yasnippet.el" - "./yasnippet-bundle.el" - '("snippets") - "(yas/initialize)" - "dropdown-list.el") -
The snippet-roots can be a list of root directories. This is -useful when you have multiple snippet directories (maybe from other -users). The code parameter can be used to specify your own -customization code instead of the default (yas/initialize). For -example, you can set yas/trigger-key to (kbd "SPC") here if -you like.
-From release 0.6 you have to specify the dropdown-list.el file if -you want it to be a part of the generated bundle.
-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 the functions +yas/define-snippets and yas/compile-bundle.
`_) + +If you make this variable a list and store more items into it... + +.. sourcecode:: common-lisp + :align: right + + ;; Develop in ~/emacs.d/mysnippets, but also + ;; try out snippets in ~/Downloads/interesting-snippets + (setq yas/root-directory '("~/emacs.d/mysnippets" + "~/Downloads/interesting-snippets")) + + ;; Map `yas/load-directory' to every element + (mapc 'yas/load-directory yas/root-directory) + +, the directories after the first are loaded, their snippets +considered for expansion, but development still happens in +"~/emacs.d/mysnippets" + +Organizing snippets +=================== + +Once you've setup ``yas/root-directory`` , you can store snippets +inside subdirectories of these directories. + +Common to *both* cases, snippet definitions are put in plain text +files. They are arranged by subdirectories, and the name of these +directories correspond to the Emacs mode where you want expansion to +take place. For example, snippets for ``c-mode`` are put in the +``c-mode`` subdirectory. You can also skip snippet storage altogether +and use the bundle (see `No storage (bundle)`_). + +Nested organization +------------------- + +Here is an excerpt of a directory hierarchy containing snippets +for some modes: + +.. sourcecode:: text + + $ tree + . + `-- text-mode + |-- cc-mode + | |-- c-mode + | | `-- printf + | |-- for + | |-- java-mode + | | `-- println + | `-- while + |-- email + |-- perl-mode + | |-- cperl-mode + | `-- for + `-- time + +The parent directory acts as the *parent mode*. This is the way of +YASnippet to share snippet definitions among different modes. As you +can see above, ``c-mode`` and ``java-mode`` share the same parents +``cc-mode``, while all modes are derived from ``text-mode``. This can +be also used to as an *alias* -- ``cperl-mode`` is an empty directory +whose parent is ``perl-mode``. + +The ``.yas-parents`` file +------------------------------ + +If you place a plain text file ``.yas-parents`` inside one of the +subdirectories you can bypass nesting and still have parent modes. In +this file you just write whitespace-separated names of modes. This +allows more flexibility and readability of your snippet hierarchy. + +.. sourcecode:: text + + $ tree + . + |-- 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 +----------------------------- + +.. image:: images/group.png + :align: right + +If you place an empty plain text file ``.yas-make-groups`` inside one +of the mode directories, the names of these subdirectories are +considered groups of snippets and the `YASsnippet 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 + `-- ... -New-style storage (recommended) -=============================== +Using plain file names +---------------------- -Hehe +Normally, file names act as the snippet trigger *key*, see `Expanding +snippets `_. However, if you customize the +variable ``yas/ignore-filenames-as-triggers`` to be true *or* place an +empty file ``.yas-ignore-filename-triggers`` you can use much more +descriptive file names. This is useful (but not mandatory) if many +snippets within a mode share the same trigger key. + +.. sourcecode:: text + + $ tree rails-mode/ + rails-mode/ + |-- .yas-make-groups + |-- .yas-ignore-filename-triggers + |-- Insert ERb's <% __ %> or <%= __ %>.yasnippet + |-- asserts + | |-- assert(var = assigns(%3Avar)).yasnippet + | |-- assert_difference.yasnippet + | |-- assert_no_difference.yasnippet + | |-- assert_redirected_to (nested path plural).yasnippet + | |-- assert_redirected_to (nested path).yasnippet + | |-- assert_redirected_to (path plural).yasnippet + | |-- assert_redirected_to (path).yasnippet + | |-- assert_rjs.yasnippet + | `-- assert_select.yasnippet -Old-style storage (pre 0.6) -=========================== -Blabla No storage (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. +``yas/load-directory`` to load them. However, this might slow down the Emacs startup speed if you have many snippets. You can use ``yas/define-snippets`` to define a bunch of -snippets for a perticular mode. But this is hard to maintain! So, -there's a better way: define your snippets in directory and use -``yas/compile-bundle`` to compile it into a bundle file when you -modified your snippets. +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 use ``yas/define-snippets`` to -define snippets. This avoid the IO and parsing overhead when loading +``yas/compile-bundle``. The bundle uses ``yas/define-snippets`` to +define snippets. This avoids the IO and parsing overhead when loading snippets. -Finally, you can use ``yas/define`` to define a single snippet at your -convenience. I ofthen use this to do some testing. +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. -Define snippets in files -======================== - -Directory hierarchy -------------------- - -Here's the directory hierarchy of the ``snippets`` directory comes -with YASnippet: - -.. sourcecode:: text - - snippets - `-- text-mode/ - |-- cc-mode/ - | |-- c++-mode/ - | | |-- beginend - | | |-- class - | | `-- using - | |-- c-mode/ - | | `-- fopen - | |-- do - | |-- for - | |-- if - | |-- inc - | |-- inc.1 - | |-- main - | |-- once - | `-- struct - |-- css-mode/ - | |-- background - | |-- background.1 - | `-- border - |-- email - |-- html-mode/ - | |-- div - | |-- doctype - | |-- doctype.xhml1 - | |-- doctype.xhtml1_1 - | |-- doctype.xhtml1_strict - | `-- doctype.xhtml1_transitional - |-- objc-mode/ - | `-- prop - |-- perl-mode/ - | |-- cperl-mode/ - | |-- eval - | |-- for - | |-- fore - | |-- if - | |-- ife - | |-- ifee - | |-- sub - | |-- unless - | |-- while - | |-- xfore - | |-- xif - | |-- xunless - | `-- xwhile - |-- python-mode/ - | |-- __ - | |-- class - | |-- def - | |-- for - | |-- ifmain - | `-- while - |-- rst-mode/ - | |-- chapter - | |-- section - | `-- title - |-- ruby-mode/ - | |-- # - | |-- =b - | |-- Comp - | |-- all - | |-- am - | |-- any - | |-- app - | |-- bm - | |-- case - | |-- cla - | |-- classify - | |-- cls - | |-- collect - | |-- dee - | |-- deli - | |-- det - | |-- ea - | |-- eac - | |-- eai - | |-- eav - | |-- eawi - | |-- forin - | |-- if - | |-- ife - | |-- inject - | |-- mm - | |-- r - | |-- rb - | |-- reject - | |-- req - | |-- rreq - | |-- rw - | |-- select - | |-- w - | |-- y - | `-- zip - `-- time - -Snippet definitions are put in plain text files. They are arranged by -subdirectories. For example, snippets for ``c-mode`` are put in the -``c-mode`` directory. - -The parent directory acts as the *parent mode*. This is the way of -YASnippet to share snippet definitions among different modes. As you -can see above, ``c-mode`` and ``c++-mode`` share the same parents -``cc-mode``, while all modes are derived from ``text-mode``. This can -be also used to as an *alias* -- ``cperl-mode`` is an empty directory -whose parent is ``perl-mode``. - -File names act as the snippet trigger key. Note files starting with a -dot (``.``) are ignored. - -Define snippets using elisp code --------------------------------- - -As I mentioned above, you can define snippets directly by writing -elisp code. - -yas/define-snippets -~~~~~~~~~~~~~~~~~~~ - -The basic syntax of ``yas/define-snippets`` is - -.. sourcecode:: common-lisp - - (yas/define-snippets MODE SNIPPETS &optional PARENT) - -The parameters are self-descriptive. If you specify a ``PARENT``, then -the snippets of the parents may be shared by ``MODE``. Note if you use -this function several times, the later specified ``PARENT`` will -overwrite the original one. However, not specifying a ``PARENT`` won't -erase the original parent. - -The ``SNIPPETS`` parameter is a list of snippet definitions. Each -element should have the following form: - -.. sourcecode:: common-lisp - - (KEY TEMPLATE NAME CONDITION GROUP) - -The ``NAME``, ``CONDITION`` and ``GROUP`` can be omitted if you don't -want to provide one. Here's an example: - -.. sourcecode:: common-lisp - - (yas/define-snippets 'c++-mode - '( - ("using" "using namespace ${std}; - $0" "using namespace ... " nil) - ("class" "class ${1:Name} - { - public: - $1($2); - virtual ~$1(); - };" "class ... { ... }" nil) - ("beginend" "${1:v}.begin(), $1.end" "v.begin(), v.end()" nil) - ) - 'cc-mode) - -The example above is auto-generated code by ``yas/compile-bundle``. - - -yas/define -~~~~~~~~~~ - -The basic syntax for ``yas/define`` is - -.. sourcecode:: common-lisp - - (yas/define mode key template &optional name condition group) - -This is only a syntax sugar for - -.. sourcecode:: common-lisp - - (yas/define-snippets mode - (list (list key template name condition group))) - -yas/compile-bundle -~~~~~~~~~~~~~~~~~~ - -``yas/compile-bundle`` can be used to parse the snippets from a -directory hierarchy and translate them into the elisp form. The -translated code is faster to load. 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. - - - -The Menu -~~~~~~~~ - -YASnippet will setup a menu just after the *Buffers* Menu in the -menubar. The snippets for all *real* modes are listed there under the -menu. You can select a snippet from the menu to expand it. Since you -select manually from the menu, you can expand any snippet. For -example, you can expand a snippet defined for ``python-mode`` in a -``c-mode`` buffer by selecting it from the menu: - -.. image:: images/menubar.png - :align: right - -* Condition system is ignored since you select to expand it - explicitly. -* There will be no muliple candidates since they are listed in the - menu as different items. - -This can be convenient sometimes. However, if you don't like the -menubar of Emacs and never use it. You can tell YASnippet don't boring -to build a menu by setting ``yas/use-menu`` to nil. - -Another thing to note is that only *real* modes are listed under the -menu. As you know, common snippets can be shared by making up a -*virtual* parent mode. It's too bad if the menu is floored by those -*virtual* modes. So YASnippet only show menus for those *real* -modes. But the snippets fo the *virtual* modes can still be accessed -through the ``parent`` submenu of some *real* mode. - -YASnippet use a simple way to check whether a mode is *real* or -*virtual*: ``(fboundp mode)``. For example, the symbol ``c-mode`` is -bound to a function while ``cc-mode`` is not. But this is not enough, -some modes aren't part of Emacs, and maybe when initializing -YASnippet, those modes haven't been initialized. So YASnippet also -maintain a list of known modes (``yas/known-modes``). You can add item -to that list if you need. - -The basic syntax of ``yas/compile-bundle`` is - -.. sourcecode:: common-lisp - - (yas/compile-bundle &optional yasnippet yasnippet-bundle snippet-roots code dropdown) - -As you can see, all the parameters are optional. The default values -for those parameters are convenient for me to produce the default -release bundle: - -.. sourcecode:: common-lisp - - (yas/compile-bundle "yasnippet.el" - "./yasnippet-bundle.el" - '("snippets") - "(yas/initialize)" - "dropdown-list.el") - -The ``snippet-roots`` can be a list of root directories. This is -useful when you have multiple snippet directories (maybe from other -users). The ``code`` parameter can be used to specify your own -customization code instead of the default ``(yas/initialize)``. For -example, you can set ``yas/trigger-key`` to ``(kbd "SPC")`` here if -you like. - -From release 0.6 you have to specify the ``dropdown-list.el`` file if -you want it to be a part of the generated bundle. +See the internal documentation for the functions +``yas/define-snippets`` and ``yas/compile-bundle``. diff --git a/doc/styles.css b/doc/styles.css index fad0240..e0afa09 100644 --- a/doc/styles.css +++ b/doc/styles.css @@ -59,6 +59,7 @@ ul.primary-links li { list-style-type: none; float: left; margin: 0px; + font-size: 0.8em; padding: 0px; } ul.primary-links li a { diff --git a/doc/template.txt b/doc/template.txt index a99c1a4..59c3f56 100644 --- a/doc/template.txt +++ b/doc/template.txt @@ -11,16 +11,19 @@ - - Home + Intro and tutorial
- - Organize + Howto: organize
- - Expand + Howto: expand
- - Write + Howto: write + +
- + Howto: menu
- FAQ