-=========================
-How to define a snippet ?
-=========================
+============================
+ Frequently Asked Questions
+============================
-:Author: pluskid
-:Contact: pluskid@gmail.com
-:Date: 2008-03-20
-
-Why there's an extra newline?
-=============================
+Why is there an extra newline?
+==============================
If you have a newline at the end of the snippet definition file, then
YASnippet will add a newline when you expanding a snippet. Please
if you set ``require-final-newline`` to ``t``, it will add the final
newline for you automatically.
-Why TAB key doesn't expand a snippet?
-=====================================
+Why doesn't TAB expand a snippet?
+=================================
-First check the mode line to see if there's ``yas``. If no, then try
-``M-x yas/minor-mode-on`` to manually turn on ``yas/minor-mode`` and
-try to expand the snippet again. If it works, then, you can add the
-following code to your ``.emacs`` *before* loading YASnippet:
+First check the mode line to see if there's ``yas``. If not, then try
+``M-x yas/minor-mode`` to manually turn on the minor mode and try to
+expand the snippet again. If it works, then, you can add the following
+code to your ``.emacs`` *before* loading YASnippet:
.. sourcecode:: lisp
- (setq yas/extra-mode-hooks '(the-major-mode))
+ (add-hook 'the-major-mode-hook 'yas/minor-mode-on)
where ``the-major-mode`` is the major mode in which ``yas/minor-mode``
isn't enabled by default.
+From YASnippet 0.6 you can also use the command ``M-x
+yas/global-mode`` to turn on YASnippet automatically for *all* major
+modes.
+
If ``yas/minor-mode`` is on but the snippet still not expanded. Then
try to see what command is bound to the ``TAB`` key: press ``C-h k``
and then press ``TAB``. Emacs will show you the result.
.. sourcecode:: lisp
(add-hook 'org-mode-hook
- '(lambda ()
- (make-variable-buffer-local 'yas/trigger-key)
- (setq yas/trigger-key [tab])))
-
-replace ``org-mode-hook`` with the major mode hook you are dealing
-with (``C-h m`` to see what major mode you are in).
-
-If it says ``TAB`` but YASnippet still doesn't work, check your
-configuration and you may also ask for help on the `discussion group
-<http://groups.google.com/group/smart-snippet>`_. Don't forget to
-attach the information on what command is bound to TAB as well as the
-mode information (Can be obtained by ``C-h m``).
-
-How to define snippets with named by characters not supported by the filesystem?
-================================================================================
-For example, you want to define a snippet by the key ``<`` which is not a
-valid character for filename on Windows. In this case, you may use
-``yas/define`` to define the snippet. If you want to enjoy defining
-snippets in a file, you can use the ``key`` property to specify the key of
-the defined snippet explicitly.
-
-Just name your snippet with an arbitrary valid filename, ``lt`` for
-example. and specify ``<`` for the ``key`` property:
+ (let ((original-command (lookup-key org-mode-map [tab])))
+ `(lambda ()
+ (setq yas/fallback-behavior
+ '(apply ,original-command))
+ (local-set-key [tab] 'yas/expand))))
+
+replace ``org-mode-hook`` and ``org-mode-map`` with the major mode
+hook you are dealing with (Use ``C-h m`` to see what major mode you
+are in).
+
+As an alternative, you can also try
+
+.. sourcecode:: lisp
+
+ (defun yas/advise-indent-function (function-symbol)
+ (eval `(defadvice ,function-symbol (around yas/try-expand-first activate)
+ ,(format
+ "Try to expand a snippet before point, then call `%s' as usual"
+ function-symbol)
+ (let ((yas/fallback-behavior nil))
+ (unless (and (interactive-p)
+ (yas/expand))
+ ad-do-it)))))
+
+ (yas/advise-indent-function 'ruby-indent-line)
+
+To *advise* the modes indentation function bound to TAB, (in this case
+``ruby-indent-line``) to first try to run ``yas/expand``.
+
+If the output of ``C-h k RET <tab>`` tells you that ``<tab>`` is
+indeed bound to ``yas/expand`` but YASnippet still doesn't work, check
+your configuration and you may also ask for help on the `discussion
+group <http://groups.google.com/group/smart-snippet>`_. See this
+particular `thread
+<http://code.google.com/p/yasnippet/issues/detail?id=93&can=1>`_ for
+quite some solutions and alternatives.
+
+Don't forget to attach the information on what command is bound to TAB
+as well as the mode information (Can be obtained by ``C-h m``).
+
+Why doesn't TAB navigation work with flyspell
+=============================================
+
+A workaround is to inhibit flyspell overlays while the snippet is active:
+
+.. sourcecode:: lisp
+
+ (add-hook 'flyspell-incorrect-hook
+ #'(lambda (dummy1 dummy2 dymmy3)
+ (and yas/active-field-overlay
+ (overlay-buffer yas/active-field-overlay))))
+
+This is apparently related to overlay priorities. For some reason, the
+``keymap`` property of flyspell's overlays always takes priority over
+the same property in yasnippet's overlays, even if one sets the
+latter's ``priority`` property to something big. If you know
+emacs-lisp and can solve this problem, drop a line in the `discussion
+group`_.
+
+How do I turn off the minor mode where in some buffers
+======================================================
+
+The best way, since version 0.6.1c, is to set the default value of the
+variable ``yas/dont-activate`` to a lambda function like so:
+
+.. sourcecode:: lisp
+
+ (set-default 'yas/dont-activate
+ #'(lambda ()
+ (and yas/root-directory
+ (null (yas/get-snippet-tables)))))
+
+This is also the default value starting for that version. It skips the
+minor mode in buffers where it is not applicable (no snippet tables),
+but only once you have setup your yas/root-directory.
+
+
+How do I define an abbrev key containing characters not supported by the filesystem?
+====================================================================================
+
+**Note**: This question applies if you're still defining snippets
+ whose key *is* the filename. This is behavior stil provided by
+ version 0.6 for backward compatibilty, but is somewhat deprecated...
+
+For example, you want to define a snippet by the key ``<`` which is
+not a valid character for filename on Windows. This means you can't
+use the filename as a trigger key in this case.
+
+You should rather use the ``# key:`` directive to specify the key of
+the defined snippet explicitly and name your snippet with an arbitrary
+valid filename, ``lt.yasnippet`` for example, using ``<`` for the
+``# key:`` directive:
.. sourcecode:: text
# --
<${1:div}>$0</$1>
+.. _discussion group: http://groups.google.com/group/smart-snippet