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

   1 =========================
   2 How to define a snippet ?
   3 =========================
   4
   5 :Author: pluskid
   6 :Contact: pluskid@gmail.com
   7 :Date: 2008-03-20
   8
   9 Why there's an extra newline?
  10 =============================
  11
  12 If you have a newline at the end of the snippet definition file, then
  13 YASnippet will add a newline when you expanding a snippet. Please
  14 don't add a newline at the end if you don't want it when you saving
  15 the snippet file.
  16
  17 Note some editors will automatically add a newline for you. In Emacs,
  18 if you set ``require-final-newline`` to ``t``, it will add the final
  19 newline for you automatically.
  20
  21 Why TAB key doesn't expand a snippet?
  22 =====================================
  23
  24 First check the mode line to see if there's ``yas``. If no, then try
  25 ``M-x yas/minor-mode-on`` to manually turn on ``yas/minor-mode`` and
  26 try to expand the snippet again. If it works, then, you can add the
  27 following code to your ``.emacs`` *before* loading YASnippet:
  28
  29 .. sourcecode:: lisp
  30
  31   (setq yas/extra-mode-hooks '(the-major-mode))
  32
  33 where ``the-major-mode`` is the major mode in which ``yas/minor-mode``
  34 isn't enabled by default.
  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             '(lambda ()
  51                (make-variable-buffer-local 'yas/trigger-key)
  52                (setq yas/trigger-key [tab])))
  53
  54 replace ``org-mode-hook`` with the major mode hook you are dealing
  55 with (``C-h m`` to see what major mode you are in).
  56
  57 If it says ``TAB`` but YASnippet still doesn't work, check your
  58 configuration and you may also ask for help on the `discussion group
  59 <http://groups.google.com/group/smart-snippet>`_. Don't forget to
  60 attach the information on what command is bound to TAB as well as the
  61 mode information (Can be obtained by ``C-h m``).
  62
  63 How to define snippets with named by characters not supported by the filesystem?
  64 ================================================================================
  65 For example, you want to define a snippet by the key ``<`` which is not a
  66 valid character for filename on Windows. In this case, you may use
  67 ``yas/define`` to define the snippet. If you want to enjoy defining
  68 snippets in a file, you can use the ``key`` property to specify the key of
  69 the defined snippet explicitly.
  70
  71 Just name your snippet with an arbitrary valid filename, ``lt`` for
  72 example. and specify ``<`` for the ``key`` property:
  73
  74 .. sourcecode:: text
  75
  76   #key: <
  77   #name: <...></...>
  78   # --
  79   <${1:div}>$0</$1>
  80