X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/b312bc8c386dbd5a739054696a56314571f682b9..f36ca47f699d3dd0c3e031f15eb09f241d8d8d41:/doc/faq.rst diff --git a/doc/faq.rst b/doc/faq.rst index e136cd09b..ad1fa72e3 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -1,13 +1,9 @@ -========================= -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 @@ -17,3 +13,138 @@ the snippet file. Note some editors will automatically add a newline for you. In Emacs, if you set ``require-final-newline`` to ``t``, it will add the final newline for you automatically. + +Why doesn't TAB expand a snippet? +================================= + +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 + + (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. + +You'll see a buffer prompted by Emacs saying that ``TAB runs the +command ...``. Alternatively, you might see `` runs the command +...``, note the difference between ``TAB`` and ```` where the +latter has priority. If you see ```` bound to a command other +than ``yas/expand``, (e.g. in ``org-mode``) you can try the following +code to work around: + +.. sourcecode:: lisp + + (add-hook 'org-mode-hook + (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 `` tells you that ```` 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 `_. See this +particular `thread +`_ 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 + + #key: < + #name: <...> + # -- + <${1:div}>$0 + +.. _discussion group: http://groups.google.com/group/smart-snippet