code.delx.au - gnu-emacs-elpa/blob - doc/faq.rst

   1 ============================
   2  Frequently Asked Questions
   3 ============================
   4
   5 Why is there an extra newline?
   6 ==============================
   7
   8 If you have a newline at the end of the snippet definition file, then
   9 YASnippet will add a newline when you expanding a snippet. Please
  10 don't add a newline at the end if you don't want it when you saving
  11 the snippet file.
  12
  13 Note some editors will automatically add a newline for you. In Emacs,
  14 if you set ``require-final-newline`` to ``t``, it will add the final
  15 newline for you automatically.
  16
  17 Why doesn't TAB expand a snippet?
  18 =================================
  19
  20 First check the mode line to see if there's ``yas``. If not, then try
  21 ``M-x yas/minor-mode`` to manually turn on the minor mode and try to
  22 expand the snippet again. If it works, then, you can add the following
  23 code to your ``.emacs`` *before* loading YASnippet:
  24
  25 .. sourcecode:: lisp
  26
  27   (add-hook 'the-major-mode-hook 'yas/minor-mode-on)
  28
  29 where ``the-major-mode`` is the major mode in which ``yas/minor-mode``
  30 isn't enabled by default.
  31
  32 From YASnippet 0.6 you can also use the command ``M-x
  33 yas/global-mode`` to turn on YASnippet automatically for *all* major
  34 modes.
  35
  36 If ``yas/minor-mode`` is on but the snippet still not expanded. Then
  37 try to see what command is bound to the ``TAB`` key: press ``C-h k``
  38 and then press ``TAB``. Emacs will show you the result.
  39
  40 You'll see a buffer prompted by Emacs saying that ``TAB runs the
  41 command ...``. Alternatively, you might see ``<tab> runs the command
  42 ...``, note the difference between ``TAB`` and ``<tab>`` where the
  43 latter has priority. If you see ``<tab>`` bound to a command other
  44 than ``yas/expand``, (e.g. in ``org-mode``) you can try the following
  45 code to work around:
  46
  47 .. sourcecode:: lisp
  48
  49   (add-hook 'org-mode-hook
  50             (let ((original-command (lookup-key org-mode-map [tab])))
  51               `(lambda ()
  52                  (setq yas/fallback-behavior
  53                        '(apply ,original-command))
  54                  (local-set-key [tab] 'yas/expand))))
  55
  56 replace ``org-mode-hook`` and ``org-mode-map`` with the major mode
  57 hook you are dealing with (Use ``C-h m`` to see what major mode you
  58 are in).
  59
  60 As an alternative, you can also try
  61
  62 .. sourcecode:: lisp
  63
  64   (defun yas/advise-indent-function (function-symbol)
  65     (eval `(defadvice ,function-symbol (around yas/try-expand-first activate)
  66              ,(format
  67                "Try to expand a snippet before point, then call `%s' as usual"
  68                function-symbol)
  69              (let ((yas/fallback-behavior nil))
  70                (unless (and (interactive-p)
  71                             (yas/expand))
  72                  ad-do-it)))))
  73
  74   (yas/advise-indent-function 'ruby-indent-line)
  75
  76 To *advise* the modes indentation function bound to TAB, (in this case
  77 ``ruby-indent-line``) to first try to run ``yas/expand``.
  78
  79 If the output of ``C-h k RET <tab>`` tells you that ``<tab>`` is
  80 indeed bound to ``yas/expand`` but YASnippet still doesn't work, check
  81 your configuration and you may also ask for help on the `discussion
  82 group <http://groups.google.com/group/smart-snippet>`_. See this
  83 particular `thread
  84 <http://code.google.com/p/yasnippet/issues/detail?id=93&can=1>`_ for
  85 quite some solutions and alternatives.
  86
  87 Don't forget to attach the information on what command is bound to TAB
  88 as well as the mode information (Can be obtained by ``C-h m``).
  89
  90 Why doesn't TAB navigation work with flyspell
  91 =============================================
  92
  93 A workaround is to inhibit flyspell overlays while the snippet is active:
  94
  95 .. sourcecode:: lisp
  96
  97   (add-hook 'flyspell-incorrect-hook
  98           #'(lambda (dummy1 dummy2 dymmy3)
  99               (and yas/active-field-overlay
 100                    (overlay-buffer yas/active-field-overlay))))
 101
 102 This is apparently related to overlay priorities. For some reason, the
 103 ``keymap`` property of flyspell's overlays always takes priority over
 104 the same property in yasnippet's overlays, even if one sets the
 105 latter's ``priority`` property to something big. If you know
 106 emacs-lisp and can solve this problem, drop a line in the `discussion
 107 group`_.
 108
 109 How do I turn off the minor mode where in some buffers
 110 ======================================================
 111
 112 The best way, since version 0.6.1c, is to set the default value of the
 113 variable ``yas/dont-activate`` to a lambda function like so:
 114
 115 .. sourcecode:: lisp
 116
 117   (set-default 'yas/dont-activate
 118              #'(lambda ()
 119                  (and yas/root-directory
 120                       (null (yas/get-snippet-tables)))))
 121
 122 This is also the default value starting for that version. It skips the
 123 minor mode in buffers where it is not applicable (no snippet tables),
 124 but only once you have setup your yas/root-directory.
 125
 126
 127 How do I define an abbrev key containing characters not supported by the filesystem?
 128 ====================================================================================
 129
 130 **Note**: This question applies if you're still defining snippets
 131   whose key *is* the filename. This is behavior stil provided by
 132   version 0.6 for backward compatibilty, but is somewhat deprecated...
 133
 134 For example, you want to define a snippet by the key ``<`` which is
 135 not a valid character for filename on Windows. This means you can't
 136 use the filename as a trigger key in this case.
 137
 138 You should rather use the ``# key:`` directive to specify the key of
 139 the defined snippet explicitly and name your snippet with an arbitrary
 140 valid filename, ``lt.yasnippet`` for example, using ``<`` for the
 141 ``# key:`` directive:
 142
 143 .. sourcecode:: text
 144
 145   # key: <
 146   # name: <...></...>
 147   # --
 148   <${1:div}>$0</$1>
 149
 150 .. _discussion group: http://groups.google.com/group/smart-snippet