code.delx.au - gnu-emacs-elpa/blob - packages/yasnippet/doc/faq.org

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