From 037f8fd3ee1e7ff17e1cdd6ccfdf3baec6c728dd Mon Sep 17 00:00:00 2001 From: capitaomorte Date: Thu, 24 Sep 2009 15:59:45 +0000 Subject: [PATCH] * proof-reading the documentation * added link to the new screencast --- doc/changelog.html | 4 +- doc/changelog.rst | 4 +- doc/index.html | 52 +++++----- doc/index.rst | 52 +++++----- doc/snippet-development.html | 189 ++++++++++++++++++---------------- doc/snippet-development.rst | 108 ++++++++++--------- doc/snippet-expansion.html | 70 +++++++------ doc/snippet-expansion.rst | 69 +++++++------ doc/snippet-menu.html | 2 +- doc/snippet-menu.rst | 2 +- doc/snippet-organization.html | 92 +++++++++-------- doc/snippet-organization.rst | 50 ++++----- 12 files changed, 361 insertions(+), 333 deletions(-) diff --git a/doc/changelog.html b/doc/changelog.html index 2882eea..7a0f2c3 100644 --- a/doc/changelog.html +++ b/doc/changelog.html @@ -54,8 +54,8 @@ for other versions can be found here.

-
-

Upcoming 0.6.1c

+
+

0.6.1c / 2009-08-13

  • Fixed issues 99, 98, 93, 90, 91, 88, 87. Thanks everybody.
    • diff --git a/doc/changelog.rst b/doc/changelog.rst index 6b61557..3896fce 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -7,8 +7,8 @@ ChangeLog .. _Writing Snippets: snippet-development.html .. _The YASnippet Menu: snippet-menu.html -Upcoming 0.6.1c -=============== +0.6.1c / 2009-08-13 +=================== * Fixed `issues `_ 99, 98, 93, 90, 91, 88, 87. Thanks everybody. diff --git a/doc/index.html b/doc/index.html index 182d227..4f02a7e 100644 --- a/doc/index.html +++ b/doc/index.html @@ -59,7 +59,7 @@
-

YASnippet is a template system for Emacs. It allows you to type a -abbreviation and automatically expand the abbreviation 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 -import most TextMate templates to YASnippet.

-

YASnippet is a re-write of the extension smart-snippet. Both are -original creations of pluskid.

+

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 +import most TextMate templates. YASnippet is a re-write of the +extension smart-snippet. Both are original creations of pluskid.

Video Demo

- + data="http://www.youtube.com/v/76Ygeg9miao"> + -

Watch the demo at YouTube (download a higher +

Watch the demo at YouTube (download a higher resolution version: yasnippet.avi).

Installation

-

There are two archives of YASnippet. One is a single file compiled -“bundle”, and the other is normal. If all you need is to use the -built-in templates, download the bundle one. If you want to add your -own templates, download the normal one.

-
-

Bundle Install

+

There are two archives you can download. 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.

+
+

Install with yasnippet-bundle.el

  1. Download the latest yasnippet-bundle-x.y.z.el.tgz and unpack it.
  2. You'll get a file named yasnippet-bundle.el, put it under @@ -107,7 +105,7 @@ own templates, download the normal one.

That's it. Now open any one of your language file, you'll see a menu YASnippet. you can pull the menu to insert a template. Or, you can -type the pre-defined abbrev and press TAB to expand it.

+type the a trigger key then press TAB to expand it.

To have Emacs load YASnippet automatically when it starts, put the following in your ~/.emacs file:

@@ -116,13 +114,15 @@ following in your ~/.emacs (require 'yasnippet-bundle)
+

The youtube video +demonstrates this quick installation.

Normal Install

-

For full install of the normal archive, just download and unpack the -latest yasnippet-x.y.z.tar.bz2. You'll get a directory named -yasnippet-x.y.z, put it in your ~/.emacs.d/plugins and add the -following in your .emacs file:

+

To install YASnippet as a normal emacs package, download and unpack +the latest yasnippet-x.y.z.tar.bz2. You'll get a directory named +yasnippet-x.y.z, which you can put it in your +~/.emacs.d/plugins and add the following in your .emacs file:

(add-to-list 'load-path
               "~/.emacs.d/plugins/yasnippet-x.y.z")
@@ -167,7 +167,7 @@ TextMate snippets.
  • The YASnippet menu
    • -Explains how to use the YASnippet menu to explore and learn new +Explains how to use the YASnippet menu to explore, learn and modify snippets.
    diff --git a/doc/index.rst b/doc/index.rst index ac2338b..7415186 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,43 +9,40 @@ Yet Another Snippet extension .. contents:: -**YASnippet** is a template system for Emacs. It allows you to type a -abbreviation and automatically expand the abbreviation into function -templates. +**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. -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 `_ -import most TextMate templates to YASnippet. - -YASnippet is a re-write of the extension `smart-snippet`_. Both are -original creations of `pluskid `_. +The snippet syntax is inspired from TextMate's syntax, you can even +`import `_ +import most TextMate templates. YASnippet is a re-write of the +extension `smart-snippet`_. Both are original creations of `pluskid +`_. .. _smart-snippet: http://code.google.com/p/smart-snippet/ Video Demo ========== -.. youtube:: vOj7btx3ATg +.. youtube:: 76Ygeg9miao :align: right Watch the `demo at YouTube -`_ (download a higher +`_ (download a higher resolution version: `yasnippet.avi `_). Installation ============ -There are two archives of YASnippet. One is a single file compiled -“bundle”, and the other is normal. If all you need is to use the -built-in templates, download the bundle one. If you want to add your -own templates, download the normal one. +There are two archives you can download. 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. -Bundle Install --------------- +Install with ``yasnippet-bundle.el`` +------------------------------------ 1. Download the latest ``yasnippet-bundle-x.y.z.el.tgz`` and unpack it. 2. You'll get a file named ``yasnippet-bundle.el``, put it under @@ -54,7 +51,7 @@ Bundle Install That's it. Now open any one of your language file, you'll see a menu YASnippet. you can pull the menu to insert a template. Or, you can -type the pre-defined abbrev and press ``TAB`` to expand it. +type the a *trigger key* then press ``TAB`` to expand it. To have Emacs load YASnippet automatically when it starts, put the following in your ``~/.emacs`` file: @@ -65,13 +62,16 @@ following in your ``~/.emacs`` file: "~/.emacs.d/plugins") (require 'yasnippet-bundle) +The `youtube video `_ +demonstrates this quick installation. + Normal Install -------------- -For full install of the normal archive, just download and unpack the -latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named -``yasnippet-x.y.z``, put it in your ``~/.emacs.d/plugins`` and add the -following in your ``.emacs`` file: +To install YASnippet as a normal emacs package, download and unpack +the latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named +``yasnippet-x.y.z``, which you can put it in your +``~/.emacs.d/plugins`` and add the following in your ``.emacs`` file: .. sourcecode:: common-lisp @@ -114,7 +114,7 @@ Hence this section has been split into separate documents: 4. `The YASnippet menu`_ - Explains how to use the YASnippet menu to explore and learn new + Explains how to use the YASnippet menu to explore, learn and modify snippets. Bugs, Contribution and Support diff --git a/doc/snippet-development.html b/doc/snippet-development.html index 953169d..6b55b4c 100644 --- a/doc/snippet-development.html +++ b/doc/snippet-development.html @@ -66,46 +66,45 @@
  • # key: snippet abbrev
  • # name: snippet name
  • # condition: snippet condition
    • -
  • # expand-env: expand environment
    • -
  • # binding: direct keybinding
    • -
  • # contributor: snippet author
    • +
  • # group: snippet menu grouping
    • +
  • # expand-env: expand environment
    • +
  • # binding: direct keybinding
    • +
  • # contributor: snippet author
    • -
  • Template syntax

    • Snippet development

    Quickly finding snippets

    -

    There are some ways you can quickly find a snippet file. Once you find -this file it will be set to snippet-mode (see ahead) and you can -start editing your snippet.

    +

    There are some ways you can quickly find a snippet file:

    • M-x yas/new-snippet

      Prompts you for a snippet name, then tries to guess a suitable @@ -115,7 +114,8 @@ so you can write your snippet.

    • M-x yas/find-snippets

      Lets you find the snippet file in the directory the snippet was -loaded from (if it exists) like find-file-other-window.

      +loaded from (if it exists) like find-file-other-window. The +directory searching logic is similar to M-x yas/new-snippet.

    • M-x yas/visit-snippet-file

      Prompts you for possible snippet expansions like @@ -123,6 +123,8 @@ loaded from (if it exists) like f directly to the snippet definition's file, if it exists.

    +

    Once you find this file it will be set to snippet-mode (see ahead) +and you can start editing your snippet.

    Using the snippet-mode major mode

    @@ -147,31 +149,26 @@ can see what it looks like. This is bound to -

    There are also snippets for making snippets: vars, field and -mirror.

    +

    There are also snippets for writing snippets: vars, $f and +$m :-).

    File content

    -

    A file defining a snippet may just contain the template for the -snippet. Optionally it can also contains some meta data for the -snippet as well as comments.

    -

    Generally speaking, if the file contains a line of # --, then all -contents above that line are considered directives (meta data) and -comments; below that line lies the snippet template.

    -

    If no # -- is found, the whole file content is considered as the -template.

    +

    A file defining a snippet generally contains the template to be +expanded.

    +

    Optionally, if the file contains a line of # --, the lines above +it count as comments, some of which can be directives (or meta +data). Snippet directives look like # property: value and tweak +certain snippets properties described below. If no # -- is found, +the whole file is considered the snippet template.

    Here's a typical example:

    #contributor : pluskid <pluskid@gmail.com>
 #name : __...__
 # --
 __${init}__
    -

    Meta data are specified in the syntax of

    -
    #data-name : data value
-
    -

    Any other text above # -- is considered as comment and -ignored. Here's a list of currently supported directives:

    +

    Here's a list of currently supported directives:

    # key: snippet abbrev

    This is the probably the most important directive, it's the @@ -200,7 +197,9 @@ loaded from.

    will only be expanded when the condition code evaluate to some non-nil value.

    See also yas/buffer-local-condition in Expanding snippets

    -

    # group snippet menu grouping

    +
    +
    +

    # group: snippet menu grouping

    When expanding/visiting snippets from the menu-bar menu, snippets for a given mode can be grouped into sub-menus . This is useful if one has too many snippets for a mode which will make the menu too @@ -215,10 +214,11 @@ special file (for this see control structure group.

    -

    # expand-env: expand environment

    -

    This is another piece of Emacs-lisp code in the form of a let varlist -form, i.e. a list of lists assigning values to variables. It can be -used to override variable values while the snippet is being expanded.

    +

    # expand-env: expand environment

    +

    This is another piece of Emacs-lisp code in the form of a let +varlist form, i.e. a list of lists assigning values to variables. It +can be used to override variable values while the snippet is being +expanded.

    Interesting variables to override are yas/wrap-around-region and yas/indent-line (see Expanding Snippets).

    As an example, you might normally have yas/indent-line set to @@ -241,7 +241,7 @@ your hard work. You can then use:

    -

    # binding: direct keybinding

    +

    # binding: direct keybinding

    You can use this directive to expand a snippet directly from a normal Emacs keybinding. The keybinding will be registered in the Emacs keymap named after the major mode the snippet is active @@ -267,38 +267,39 @@ you want to record the keybinding.

    # -- <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
    -

    Note that this feature is still experimental, it might go away, -be changed in future release, and should be used with caution: It is -easy to override important keybindings for many basic modes and it is -hard to undefine them. For the moment, the variable -yas/active-keybinding can tell you what snippet keybindings are -active and the function yas/kill-snippet-keybindings will attempt to -undefine all the keybindings.

    +

    Note: this feature is still experimental, it might go away, be +changed in future release, and should be used with caution: It is easy +to override important keybindings for many basic modes and it is hard +to undefine them. For the moment, the variable +yas/active-keybindings can tell you what snippet keybindings are +active and the function yas/kill-snippet-keybindings will attempt +to undefine all the keybindings.

    -

    # contributor: snippet author

    +

    # contributor: snippet author

    This is optional and has no effect whatsoever on snippet functionality, but it looks nice.

    -

    Template syntax

    +

    Template syntax

    The syntax of the snippet template is simple but powerful, very similar to TextMate's.

    -

    Plain Text

    +

    Plain Text

    Arbitrary text can be included as the content of a template. They are usually interpreted as plain text, except $ and `. You need to use \ to escape them: \$ and \`. The \ itself may also needed to be escaped as \\ sometimes.

    -

    Embedded Emacs-lisp code

    -

    Emacs-Lisp code can be embedded inside the template. They are written -inside back-quotes (`):

    -

    They are evaluated when the snippet is being expanded. The evaluation -is done in the same buffer as the snippet being expanded. Here's an -example for c-mode to calculate the header file guard dynamically:

    +

    Embedded Emacs-lisp code

    +

    Emacs-Lisp code can be embedded inside the template, written inside +back-quotes (`). The lisp forms are evaluated when the snippet is +being expanded. The evaluation is done in the same buffer as the +snippet being expanded.

    +

    Here's an example for c-mode to calculate the header file guard +dynamically:

    #ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
 #define $1
 
@@ -306,7 +307,7 @@ $0
 
 #endif /* $1 */
    -

    From version 0.6.0, snippets expansions are run with some special +

    From version 0.6, snippets expansions are run with some special Emacs-lisp variables bound. One of this is yas/selected-text. You can therefore define a snippet like:

    for ($1;$2;$3) {
@@ -318,7 +319,7 @@ snippet. Alternatively, you can also customize the variable
 yas/wrap-around-region to t which will do this automatically.
    -

    Tab stop fields

    +

    Tab stop fields

    Tab stops are fields that you can navigate back and forth by TAB and S-TAB. They are written by $ followed with a number. $0 has the special meaning of the exit point of a @@ -330,7 +331,7 @@ fields. Here's a typical example:

    -

    Placeholder fields

    +

    Placeholder fields

    Tab stops can have default values -- a.k.a placeholders. The syntax is like this:

    ${N:default value}
@@ -341,7 +342,7 @@ typing. The number can be omitted if you don't want to create
 mirrors or transformations for this field.
    -

    Mirrors

    +

    Mirrors

    We refer the tab stops with placeholders as a field. A field can have mirrors. Its mirrors will get updated when you change the text of a field. Here's an example:

    @@ -357,7 +358,7 @@ none of the tab stops has an initial value, the first one is selected as the field and others mirrors.

    -

    Mirrors with transformations

    +

    Mirrors with transformations

    If the value of an ${n:-construct starts with and contains $(, then it is interpreted as a mirror for field n with a transformation. The mirror's text content is calculated according to @@ -405,7 +406,7 @@ $0

    -

    Fields with transformations

    +

    Fields with transformations

    From version 0.6 on, you can also have lisp transformation inside fields. These work mostly mirror transformations but are evaluated when you first enter the field, after each change you make to the @@ -428,8 +429,8 @@ the value of the field and sets it its internal modification state to true. As a consequence, the auto-deletion behaviour of normal fields does not take place. This is by design.

    -
    -

    Choosing fields value from a list

    +
    +

    Choosing fields value from a list and other tricks

    As mentioned, the field transformation is invoked just after you enter the field, and with some useful variables bound, notably yas/field-modified-p and yas/moving-away-p. Because of this @@ -441,11 +442,21 @@ you select default values for it.

    </div>

    See the definition of yas/choose-value to see how it was written -using the two variables. Also check out yas/verify-value for -another neat trick.

    +using the two variables.

    +

    Here's another use, for LaTeX-mode, which calls reftex-label just as +you enter snippet field 2. This one makes use of yas/modified-p +directly.

    +
    \section{${1:"Titel der Tour"}}%
+\index{$1}%
+\label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-
+insert))}}%
+
    +

    The function yas/verify-value has another neat trick, and makes +use of yas/moving-away-p. Try it and see! Also, check out this +thread

    -

    Nested placeholder fields

    +

    Nested placeholder fields

    From version 0.6 on, you can also have nested placeholders of the type:

    <div${1: id="${2:some_id}"}>$0</div>
    @@ -460,9 +471,9 @@ performs the normal Emacs delete-
    -

    Customizable variables

    +

    Customizable variables

    -

    yas/trigger-key

    +

    yas/trigger-key

    The key bound to yas/expand when function yas/minor-mode is active.

    Value is a string that is converted to the internal Emacs key @@ -470,7 +481,7 @@ representation using read-kbd-mac

    Default value is "TAB".

    -

    yas/next-field-key

    +

    yas/next-field-key

    The key to navigate to next field when a snippet is active.

    Value is a string that is converted to the internal Emacs key representation using read-kbd-macro.

    @@ -478,7 +489,7 @@ representation using read-kbd-mac

    Default value is "TAB".

    -

    yas/prev-field-key

    +

    yas/prev-field-key

    The key to navigate to previous field when a snippet is active.

    Value is a string that is converted to the internal Emacs key representation using read-kbd-macro.

    @@ -486,7 +497,7 @@ representation using read-kbd-mac

    Default value is ("<backtab>" "<S-tab>)".

    -

    yas/skip-and-clear-key

    +

    yas/skip-and-clear-key

    The key to clear the currently active field.

    Value is a string that is converted to the internal Emacs key representation using read-kbd-macro.

    @@ -494,12 +505,12 @@ representation using read-kbd-mac

    Default value is "C-d".

    -

    yas/good-grace

    +

    yas/good-grace

    If non-nil, don't raise errors in inline Emacs-lisp evaluation inside snippet definitions. An error string "[yas] error" is returned instead.

    -

    yas/indent-line

    +

    yas/indent-line

    The variable yas/indent-line controls the indenting. It is bound to 'auto by default, which causes your snippet to be indented according to the mode of the buffer it was inserted in.

    @@ -520,7 +531,7 @@ $0$>
    -

    yas/wrap-around-region

    +

    yas/wrap-around-region

    If non-nil, YASnippet will try to expand the snippet's exit marker around the currently selected region. When this variable is set to t, this has the same effect has using the `yas/selected-text` inline @@ -534,18 +545,18 @@ the region), then press yas/trigg spring back to life inside your new snippet.

    -

    yas/triggers-in-field

    +

    yas/triggers-in-field

    If non-nil, yas/next-field-key can trigger stacked expansions, that is a snippet expansion inside another snippet expansion. Otherwise, yas/next-field-key just tries to move on to the next field.

    -

    yas/snippet-revival

    +

    yas/snippet-revival

    Non-nil means re-activate snippet fields after undo/redo.

    -

    yas/after-exit-snippet-hook and yas/before-expand-snippet-hook

    +

    yas/after-exit-snippet-hook and yas/before-expand-snippet-hook

    These hooks are called, respectively, before the insertion of a snippet and after exiting the snippet. If you find any strange but functional use for them, that's probably a design flaw in YASnippet, @@ -553,7 +564,7 @@ so let us know.

    -

    Importing TextMate snippets

    +

    Importing TextMate snippets

    There are a couple of tools that take TextMate's ".tmSnippet" xml files and create YASnippet definitions:

    diff --git a/doc/snippet-development.rst b/doc/snippet-development.rst index abecd78..837c876 100644 --- a/doc/snippet-development.rst +++ b/doc/snippet-development.rst @@ -15,9 +15,7 @@ Snippet development Quickly finding snippets ------------------------ -There are some ways you can quickly find a snippet file. Once you find -this file it will be set to ``snippet-mode`` (see ahead) and you can -start editing your snippet. +There are some ways you can quickly find a snippet file: * ``M-x yas/new-snippet`` @@ -29,7 +27,8 @@ start editing your snippet. * ``M-x yas/find-snippets`` Lets you find the snippet file in the directory the snippet was - loaded from (if it exists) like ``find-file-other-window``. + loaded from (if it exists) like ``find-file-other-window``. The + directory searching logic is similar to ``M-x yas/new-snippet``. * ``M-x yas/visit-snippet-file`` @@ -37,6 +36,9 @@ start editing your snippet. ``yas/insert-snippet``, but instead of expanding it, takes you directly to the snippet definition's file, if it exists. +Once you find this file it will be set to ``snippet-mode`` (see ahead) +and you can start editing your snippet. + Using the ``snippet-mode`` major mode ------------------------------------- @@ -60,22 +62,20 @@ Two commands are defined in this mode: can see what it looks like. This is bound to ``C-c C-t`` while in ``snippet-mode``. -There are also snippets for making snippets: ``vars``, ``field`` and -``mirror``. +There are also *snippets for writing snippets*: ``vars``, ``$f`` and +``$m`` :-). File content ============ -A file defining a snippet may just contain the template for the -snippet. Optionally it can also contains some meta data for the -snippet as well as comments. +A file defining a snippet generally contains the template to be +expanded. -Generally speaking, if the file contains a line of ``# --``, then all -contents above that line are considered directives (meta data) and -comments; below that line lies the snippet template. - -If no ``# --`` is found, the whole file content is considered as the -template. +Optionally, if the file contains a line of ``# --``, the lines above +it count as comments, some of which can be *directives* (or meta +data). Snippet directives look like ``# property: value`` and tweak +certain snippets properties described below. If no ``# --`` is found, +the whole file is considered the snippet template. Here's a typical example: @@ -86,14 +86,7 @@ Here's a typical example: # -- __${init}__ -Meta data are specified in the syntax of - -.. sourcecode:: text - - #data-name : data value - -Any other text above ``# --`` is considered as comment and -ignored. Here's a list of currently supported directives: +Here's a list of currently supported directives: ``# key:`` snippet abbrev -------------------------- @@ -122,7 +115,6 @@ snippet -- especially distinguishable among similar snippets. If you omit this name it will default to the file name the snippet was loaded from. - ``# condition:`` snippet condition ---------------------------------- This is a piece of Emacs-lisp code. If a snippet has a condition, then it @@ -132,8 +124,8 @@ value. See also ``yas/buffer-local-condition`` in `Expanding snippets`_ - -``# group`` snippet menu grouping +``# group:`` snippet menu grouping +---------------------------------- When expanding/visiting snippets from the menu-bar menu, snippets for a given mode can be grouped into sub-menus . This is useful if one has @@ -154,14 +146,14 @@ which is under the ``control structure`` group. ``# expand-env:`` expand environment ------------------------------------ -This is another piece of Emacs-lisp code in the form of a ``let`` *varlist* -form, i.e. a list of lists assigning values to variables. It can be -used to override variable values while the snippet is being expanded. +This is another piece of Emacs-lisp code in the form of a ``let`` +*varlist form*, i.e. a list of lists assigning values to variables. It +can be used to override variable values while the snippet is being +expanded. Interesting variables to override are ``yas/wrap-around-region`` and ``yas/indent-line`` (see `Expanding Snippets`_). - As an example, you might normally have ``yas/indent-line`` set to ``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this particularly brilliant piece of ASCII art these values would mess up @@ -219,13 +211,13 @@ you want to record the keybinding. # --

    `(when yas/prefix "\n")`$0`(when yas/prefix "\n")`

    -*Note* that this feature is still **experimental**, it might go away, -be changed in future release, and should be used with caution: It is -easy to override important keybindings for many basic modes and it is -hard to undefine them. For the moment, the variable -``yas/active-keybinding`` can tell you what snippet keybindings are -active and the function ``yas/kill-snippet-keybindings`` will attempt to -undefine all the keybindings. +**Note**: this feature is still **experimental**, it might go away, be +changed in future release, and should be used with caution: It is easy +to override important keybindings for many basic modes and it is hard +to undefine them. For the moment, the variable +``yas/active-keybindings`` can tell you what snippet keybindings are +active and the function ``yas/kill-snippet-keybindings`` will attempt +to undefine all the keybindings. ``# contributor:`` snippet author --------------------------------------------------- @@ -251,12 +243,13 @@ needed to be escaped as ``\\`` sometimes. Embedded Emacs-lisp code ------------------------ -Emacs-Lisp code can be embedded inside the template. They are written -inside back-quotes (`````): +Emacs-Lisp code can be embedded inside the template, written inside +back-quotes (`````). The lisp forms are evaluated when the snippet is +being expanded. The evaluation is done in the same buffer as the +snippet being expanded. -They are evaluated when the snippet is being expanded. The evaluation -is done in the same buffer as the snippet being expanded. Here's an -example for ``c-mode`` to calculate the header file guard dynamically: +Here's an example for ``c-mode`` to calculate the header file guard +dynamically: .. sourcecode:: text @@ -267,7 +260,7 @@ example for ``c-mode`` to calculate the header file guard dynamically: #endif /* $1 */ -From version 0.6.0, snippets expansions are run with some special +From version 0.6, snippets expansions are run with some special Emacs-lisp variables bound. One of this is ``yas/selected-text``. You can therefore define a snippet like: @@ -432,8 +425,8 @@ the value of the field and sets it its internal modification state to ``true``. As a consequence, the auto-deletion behaviour of normal fields does not take place. This is by design. -Choosing fields value from a list ---------------------------------- +Choosing fields value from a list and other tricks +-------------------------------------------------- As mentioned, the field transformation is invoked just after you enter the field, and with some useful variables bound, notably @@ -445,13 +438,28 @@ The ``yas/choose-value`` does this work for you. For example: .. sourcecode:: text -
    - $0 -
    +
    + $0 +
    See the definition of ``yas/choose-value`` to see how it was written -using the two variables. Also check out ``yas/verify-value`` for -another neat trick. +using the two variables. + +Here's another use, for LaTeX-mode, which calls reftex-label just as +you enter snippet field 2. This one makes use of ``yas/modified-p`` +directly. + +.. sourcecode:: text + + \section{${1:"Titel der Tour"}}% + \index{$1}% + \label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont- + insert))}}% + +The function ``yas/verify-value`` has another neat trick, and makes +use of ``yas/moving-away-p``. Try it and see! Also, check out this +`thread +`_ Nested placeholder fields ------------------------- diff --git a/doc/snippet-expansion.html b/doc/snippet-expansion.html index 93c0533..2f0256c 100644 --- a/doc/snippet-expansion.html +++ b/doc/snippet-expansion.html @@ -74,7 +74,7 @@
  • The condition system
  • Multiples snippet with the same key @@ -95,9 +95,10 @@

    Triggering expansion

    You can use YASnippet to expand snippets in different ways:

      -
    • By typing a snippet abbrev and then pressing the key defined in -yas/trigger-key (which defaults to "TAB"). This works in a -buffer where the minor mode yas/minor-mode is active;
      • +
    • 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.
      • @@ -171,12 +172,12 @@ prefer.

    • Expanding from emacs-lisp code

    -

    Sometimes you might want to expand a snippet directly by calling a -functin from elisp code. You should call yas/expand-snippet -instead of yas/expand in this case.

    -

    As with expanding from the menubar, condition system and multiple -candidates won't exists here. In fact, expanding from menubar has the -same effect of evaluating the follow code:

    +

    Sometimes you might want to expand a snippet directly from you own +elisp code. You should call yas/expand-snippet instead of +yas/expand in this case.

    +

    As with expanding from the menubar, the condition system and multiple +candidates doesn't affect expansion. In fact, expanding from the +YASnippet menu has the same effect of evaluating the follow code:

    (yas/expand-snippet template)

    See the internal documentation on yas/expand-snippet for more @@ -188,7 +189,7 @@ information.

    Eligible snippets

    YASnippet does quite a bit of filtering to find out which snippets are -eligible for expanding at point.

    +eligible for expanding at the current cursor position.

    In particular, the following things matter:

    • Currently loaded snippets tables

      @@ -197,21 +198,22 @@ eligible for expanding at point.

      html-mode, ruby-mode, etc...

    • Major mode of the current buffer

      -

      If it matches one of the loaded snippet tables, then all that -table's snippets are considered for expansion. Use M-x -describe-variable RET major-mode RET to find out which mode you -are in currently.

      +

      If the currrent major mode matches one of the loaded snippet tables, +then all that table's snippets are considered for expansion. Use +M-x describe-variable RET major-mode RET to find out which major +mode you are in currently.

    • Parent tables

      -

      Snippet tables defined as parent of some other table considered in -the previous step are also considered.

      +

      Snippet tables defined as the parent of some other eligible table +are also considered. This works recursively, i.e. parents of parents +of eligible tables are also considered.

    • Buffer-local yas/mode-symbol variable

      This can be used to consider snippet tables whose name does not correspond to a major mode. If you set this variable to a name , like rinari-minor-mode, you can have some snippets expand only in that minor mode. Naturally, you want to set this conditionally, -i.e. only when entering that minor mode, using a hook is a good +i.e. only when entering that minor mode, so using a hook is a good idea.

    @@ -223,10 +225,10 @@ idea.

    • Buffer-local yas/buffer-local-condition variable

      -

      This variable provides more fine grained control over what snippets -can be expanded in the current buffer. The default value, won't let -you expand snippets inside comments or string literals for -example. See The condition system for more info.

      +

      This variable provides finer grained control over what snippets can +be expanded in the current buffer. The default value won't let you +expand snippets inside comments or string literals for example. See +The condition system for more info.

    @@ -294,9 +296,9 @@ other snippets like ifThe rules outlined above can return more than one snippet to be expanded at point.

    When there are multiple candidates, YASnippet will let you select -one. The UI for selecting multiple candidate can be customized. A -customization variable, called yas/prompt-functions defines your -preferred method of being prompted for snippets.

    +one. The UI for selecting multiple candidate can be customized through +yas/prompt-functions , which defines your preferred methods of +being prompted for snippets.

    You can customize it with M-x customize-variable RET yas/prompt-functions RET. Alternatively you can put in your emacs-file:

    @@ -318,8 +320,8 @@ support, this menu will be rendered with your gtk theme. images/ido-menu.png -
    -

    Use built-in Emacs selection methods

    +
    +

    Minibuffer prompting

    You can use functions yas/completing-prompt for the classic emacs completion method or yas/ido-prompt for a much nicer looking method. The best way is to try it. This works in a terminal.

    @@ -390,11 +392,11 @@ eligible tables.

    yas/key-syntaxes

    The default searching strategy is quite powerful. For example, in -c-mode, "bar", "foo_bar", "#foo_bar" can all be -recognized as a snippet key. Furthermore, the searching is in that -order. In other words, if "bar" is found to be a key to some -valid snippet, then "foo_bar" and "#foobar" won't be -searched.

    +c-mode, bar, foo_bar, "#foo_bar" can all be recognized +as a snippet key. Furthermore, the searching is in that order. In +other words, if bar is found to be a key to some valid snippet, +then that snippet is expanded and replaces the bar. Snippets +pointed to by foo_bar and "#foobar won't be considered.

    However, this strategy can also be customized easily from the yas/key-syntaxes variable. It is a list of syntax rules, the default value is ("w" "w_" "w_." "^ "). Which means search the @@ -405,8 +407,8 @@ following thing until found one:

  • a sequence of characters of either word, symbol or punctuation.
  • a sequence of characters of non-whitespace characters.
    • -

    But you'd better keep the default value unless you understand what -Emacs's syntax rule mean.

    +

    But you'd better keep the default value unless you want to understand +how Emacs's syntax rules work...

    diff --git a/doc/snippet-expansion.rst b/doc/snippet-expansion.rst index 67e7d6c..c251173 100644 --- a/doc/snippet-expansion.rst +++ b/doc/snippet-expansion.rst @@ -15,9 +15,10 @@ Triggering expansion You can use YASnippet to expand snippets in different ways: -* By typing a snippet abbrev and then pressing the key defined in - ``yas/trigger-key`` (which defaults to "TAB"). This works in a - buffer where the minor mode ``yas/minor-mode`` is active; +* 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* @@ -115,13 +116,13 @@ prefer. Expanding from emacs-lisp code ------------------------------ -Sometimes you might want to expand a snippet directly by calling a -functin from elisp code. You should call ``yas/expand-snippet`` -instead of ``yas/expand`` in this case. +Sometimes you might want to expand a snippet directly from you own +elisp code. You should call ``yas/expand-snippet`` instead of +``yas/expand`` in this case. -As with expanding from the menubar, condition system and multiple -candidates won't exists here. In fact, expanding from menubar has the -same effect of evaluating the follow code: +As with expanding from the menubar, the condition system and multiple +candidates doesn't affect expansion. In fact, expanding from the +YASnippet menu has the same effect of evaluating the follow code: .. sourcecode:: common-lisp @@ -137,7 +138,7 @@ Eligible snippets ----------------- YASnippet does quite a bit of filtering to find out which snippets are -eligible for expanding at point. +eligible for expanding at the current cursor position. In particular, the following things matter: @@ -149,15 +150,16 @@ In particular, the following things matter: * Major mode of the current buffer - If it matches one of the loaded snippet tables, then all that - table's snippets are considered for expansion. Use ``M-x - describe-variable RET major-mode RET`` to find out which mode you - are in currently. + If the currrent major mode matches one of the loaded snippet tables, + then all that table's snippets are considered for expansion. Use + ``M-x describe-variable RET major-mode RET`` to find out which major + mode you are in currently. * Parent tables - Snippet tables defined as parent of some other table considered in - the previous step are also considered. + Snippet tables defined as the parent of some other eligible table + are also considered. This works recursively, i.e. parents of parents + of eligible tables are also considered. * Buffer-local ``yas/mode-symbol`` variable @@ -165,7 +167,7 @@ In particular, the following things matter: correspond to a major mode. If you set this variable to a name , like ``rinari-minor-mode``, you can have some snippets expand only in that minor mode. Naturally, you want to set this conditionally, - i.e. only when entering that minor mode, using a hook is a good + i.e. only when entering that minor mode, so using a hook is a good idea. .. sourcecode:: common-lisp @@ -178,10 +180,10 @@ In particular, the following things matter: * Buffer-local ``yas/buffer-local-condition`` variable - This variable provides more fine grained control over what snippets - can be expanded in the current buffer. The default value, won't let - you expand snippets inside comments or string literals for - example. See `The condition system`_ for more info. + This variable provides finer grained control over what snippets can + be expanded in the current buffer. The default value won't let you + expand snippets inside comments or string literals for example. See + `The condition system`_ for more info. The condition system -------------------- @@ -260,9 +262,9 @@ The rules outlined `above `_ can return more than one snippet to be expanded at point. When there are multiple candidates, YASnippet will let you select -one. The UI for selecting multiple candidate can be customized. A -customization variable, called ``yas/prompt-functions`` defines your -preferred method of being prompted for snippets. +one. The UI for selecting multiple candidate can be customized through +``yas/prompt-functions`` , which defines your preferred methods of +being prompted for snippets. You can customize it with ``M-x customize-variable RET yas/prompt-functions RET``. Alternatively you can put in your @@ -293,8 +295,8 @@ which means: .. image:: images/ido-menu.png :align: right -Use built-in Emacs selection methods -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Minibuffer prompting +~~~~~~~~~~~~~~~~~~~~ You can use functions ``yas/completing-prompt`` for the classic emacs completion method or ``yas/ido-prompt`` for a much nicer looking @@ -324,7 +326,6 @@ Customizable Variables ``yas/prompt-functions`` ------------------------ - You can write a function and add it to the ``yas/prompt-functions`` list. These functions are called with the following arguments: @@ -383,11 +384,11 @@ This affects ``yas/insert-snippet``, ``yas/visit-snippet-file`` -------------------- The default searching strategy is quite powerful. For example, in -``c-mode``, ``"bar"``, ``"foo_bar"``, ``"#foo_bar"`` can all be -recognized as a snippet key. Furthermore, the searching is in that -order. In other words, if ``"bar"`` is found to be a key to some -*valid* snippet, then ``"foo_bar"`` and ``"#foobar"`` won't be -searched. +``c-mode``, ``bar``, ``foo_bar``, ``"#foo_bar"`` can all be recognized +as a snippet key. Furthermore, the searching is in that order. In +other words, if ``bar`` is found to be a key to some *valid* snippet, +then that snippet is expanded and replaces the ``bar``. Snippets +pointed to by ``foo_bar`` and ``"#foobar`` won't be considered. However, this strategy can also be customized easily from the ``yas/key-syntaxes`` variable. It is a list of syntax rules, the @@ -399,7 +400,7 @@ following thing until found one: * a sequence of characters of either word, symbol or punctuation. * a sequence of characters of non-whitespace characters. -But you'd better keep the default value unless you understand what -Emacs's syntax rule mean. +But you'd better keep the default value unless you want to understand +how Emacs's syntax rules work... diff --git a/doc/snippet-menu.html b/doc/snippet-menu.html index b91f1b9..ad9811b 100644 --- a/doc/snippet-menu.html +++ b/doc/snippet-menu.html @@ -65,7 +65,7 @@

    When yas/minor-mode is active, YASnippet will setup a menu just -after the Buffers Menu in the menubar.

    +after the "Buffers" menu in the menubar.

    In this menu, you can find

    • The currently loaded snippet definitions, organized by major mode, diff --git a/doc/snippet-menu.rst b/doc/snippet-menu.rst index 40b367d..a40c5a8 100644 --- a/doc/snippet-menu.rst +++ b/doc/snippet-menu.rst @@ -5,7 +5,7 @@ YASnippet menu .. contents:: When ``yas/minor-mode`` is active, YASnippet will setup a menu just -after the Buffers Menu in the menubar. +after the "Buffers" menu in the menubar. In this menu, you can find diff --git a/doc/snippet-organization.html b/doc/snippet-organization.html index b61c6e4..efb3a2e 100644 --- a/doc/snippet-organization.html +++ b/doc/snippet-organization.html @@ -57,34 +57,35 @@
      -

      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) into snippet tables.

      -

      The triggering mechanisms (see Expanding snippets) will look up -these snippet tables and (hopefully) expand your intended snippet.

      +

      Loading snippets

      +

      Snippet definitions are stored in files in the filesystem. Unless you +use the simpler bundle version), these +are arranged so that YASnippet can load them into snippet +tables. The triggering mechanisms (see Expanding snippets) will +look up these snippet tables and (hopefully) expand the snippet you +intended.

      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, one or more directories.

      +also create or download more directories.

      Once these directories are in place reference them in the variable -yas/root-directory and then load them with yas/load-directory:

      +yas/root-directory and load them with yas/load-directory:

      ;; Develop and keep personal snippets under ~/emacs.d/mysnippets
 (setq yas/root-directory "~/emacs.d/mysnippets")
 
@@ -105,12 +106,12 @@ Snippets.
      
 ;; Map `yas/load-directory' to every element
 (mapc 'yas/load-directory yas/root-directory)
      -

      Here the directories after the first are loaded, their snippets -considered for expansion, but development still happens in -"~/emacs.d/mysnippets"

      +

      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".

      -

      Organizing snippets

      +

      Organizing snippets

      Once you've setup yas/root-directory , you can store snippets inside sub-directories of these directories.

      Snippet definitions are put in plain text files. They are arranged by @@ -118,9 +119,9 @@ sub-directories, and the snippet tables are named after these directories.

      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. You can also skip snippet storage altogether -and use the bundle (see YASnippet bundle).

      +and use the bundle (see YASnippet bundle).

      -

      Nested organization

      +

      Nested organization

      Here is an excerpt of a directory hierarchy containing snippets for some modes:

      $ tree
@@ -140,20 +141,23 @@ for some modes:
      
     `-- time

      A parent directory acts as a parent table of any of its -sub-directories. This is one of the ways YASnippet can 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.

      +sub-directories. This is one of the ways different Emacs major modes +can share snippet definitions. As you can see above, c-mode and +java-mode share the same parent cc-mode and its while +snipepts, while all modes are share the time snippet from +text-mode.

      This can be also used to as an alias -- cperl-mode is an empty directory whose parent is perl-mode.

      images/menu-parent.png
      -

      The .yas-parents file

      -

      If you place a plain text file .yas-parents inside one of the -sub-directories you can bypass nesting and still have parent modes. In -this file you just write white-space-separated names of modes. This -allows more flexibility and readability of your snippet hierarchy.

      +

      The .yas-parents file

      +

      An alternate (and preferred) way of setting up parent tables consists +of placing a plain text file .yas-parents inside one of the +sub-directories. By doing this, you avoid complex directory +nesting. In the .yas-parents file you just write +whitespace-separated names of modes. This allows more flexibility and +readability of your snippet hierarchy.

      $ tree
 .
 |-- c-mode
@@ -171,7 +175,7 @@ allows more flexibility and readability of your snippet hierarchy.
      -

      The .yas-make-groups file

      +

      The .yas-make-groups file

      images/menu-groups.png

      If you place an empty plain text file .yas-make-groups inside one of the mode directories, the names of these sub-directories are @@ -195,7 +199,7 @@ ruby-mode/

      -

      Using plain file names

      +

      Using plain file names

      Normally, file names act as the snippet expansion abbreviation (also known as the snippet key or snippet trigger, see Expanding Snippets).

      @@ -222,8 +226,8 @@ rails-mode/
      -
      -

      YASnippet bundle

      +
      +

      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.

      @@ -247,18 +251,18 @@ generated this way.

    -

    Customizable variables

    +

    Customizable variables

    -

    yas/root-directory

    +

    yas/root-directory

    Root directory that stores the snippets for each major mode.

    -

    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 +

    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

    +

    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.

    diff --git a/doc/snippet-organization.rst b/doc/snippet-organization.rst index 909bef4..dc7018c 100644 --- a/doc/snippet-organization.rst +++ b/doc/snippet-organization.rst @@ -12,19 +12,19 @@ Organizing 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 -bundle `_) into *snippet tables*. - -The triggering mechanisms (see `Expanding snippets`_) will look up -these snippet tables and (hopefully) expand your intended snippet. +Snippet definitions are stored in files in the filesystem. Unless you +use the simpler `bundle version `_), these +are arranged so that YASnippet can load them into *snippet +tables*. The triggering mechanisms (see `Expanding snippets`_) will +look up these snippet tables and (hopefully) expand the snippet you +intended. 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, one or more directories. +also create or download more directories. Once these directories are in place reference them in the variable -``yas/root-directory`` and then load them with ``yas/load-directory``: +``yas/root-directory`` and load them with ``yas/load-directory``: .. sourcecode:: common-lisp @@ -52,9 +52,9 @@ You can make this variable a list and store more items into it: ;; Map `yas/load-directory' to every element (mapc 'yas/load-directory yas/root-directory) -Here the directories after the first are loaded, their snippets -considered for expansion, but development still happens in -"~/emacs.d/mysnippets" +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". Organizing snippets =================== @@ -95,10 +95,11 @@ for some modes: `-- time A parent directory acts as a *parent table* of any of its -sub-directories. This is one of the ways YASnippet can 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``. +sub-directories. This is one of the ways different Emacs major modes +can share snippet definitions. As you can see above, ``c-mode`` and +``java-mode`` share the same parent ``cc-mode`` and its ``while`` +snipepts, while all modes are share the ``time`` snippet from +``text-mode``. This can be also used to as an *alias* -- ``cperl-mode`` is an empty directory whose parent is ``perl-mode``. @@ -109,10 +110,12 @@ directory whose parent is ``perl-mode``. The ``.yas-parents`` file ------------------------------ -If you place a plain text file ``.yas-parents`` inside one of the -sub-directories you can bypass nesting and still have parent modes. In -this file you just write white-space-separated names of modes. This -allows more flexibility and readability of your snippet hierarchy. +An alternate (and preferred) way of setting up parent tables consists +of placing a plain text file ``.yas-parents`` inside one of the +sub-directories. By doing this, you avoid complex directory +nesting. In the ``.yas-parents`` file you just write +whitespace-separated names of modes. This allows more flexibility and +readability of your snippet hierarchy. .. sourcecode:: text @@ -231,11 +234,10 @@ Customizable variables Root directory that stores the snippets for each major mode. -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 +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``