From 0aebb41aca45a39f952b0a97de9ef33d9caf652b Mon Sep 17 00:00:00 2001 From: Noam Postavsky Date: Mon, 25 Nov 2013 21:55:34 -0500 Subject: [PATCH] move top heading to title and all the other headings one level up. Except for snippet-reference.org; yas--document-symbols doesn't quite work right in that case, fix it later. --- doc/faq.org | 12 ++++----- doc/index.org | 1 - doc/snippet-development.org | 47 ++++++++++++++++++------------------ doc/snippet-expansion.org | 34 +++++++++++++------------- doc/snippet-menu.org | 12 ++++----- doc/snippet-organization.org | 22 ++++++++--------- doc/snippet-reference.org | 3 +++ 7 files changed, 66 insertions(+), 65 deletions(-) diff --git a/doc/faq.org b/doc/faq.org index d811816..622a3d7 100644 --- a/doc/faq.org +++ b/doc/faq.org @@ -1,8 +1,8 @@ #+SETUPFILE: org-setup.inc -* Frequently Asked Questions +#+TITLE: Frequently Asked Questions -** Why is there 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 don't @@ -13,7 +13,7 @@ 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? +* 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 @@ -80,7 +80,7 @@ See this particular [[http://code.google.com/p/yasnippet/issues/detail?id=93&can 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 +* Why doesn't TAB navigation work with flyspell A workaround is to inhibit flyspell overlays while the snippet is active: @@ -99,7 +99,7 @@ same property in yasnippet's overlays, even if one sets the latter's solve this problem, drop a line in the [[http://groups.google.com/group/smart-snippet][discussion group]]. -** How do I turn off the minor mode where in some buffers +* 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 [[sym:yas-dont-activate][=yas-dont-activate=]] to a lambda function like so: @@ -115,7 +115,7 @@ 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 +* How do I define an abbrev key containing characters not supported by the filesystem? - *Note*: This question applies if you're still defining snippets diff --git a/doc/index.org b/doc/index.org index a3c6dcf..ffc0c67 100644 --- a/doc/index.org +++ b/doc/index.org @@ -1,5 +1,4 @@ #+TITLE: Yet another snippet extension -#+OPTIONS: toc:1 #+STARTUP: showall #+SETUPFILE: org-setup.inc diff --git a/doc/snippet-development.org b/doc/snippet-development.org index f85ee05..2e86624 100644 --- a/doc/snippet-development.org +++ b/doc/snippet-development.org @@ -1,10 +1,9 @@ #+SETUPFILE: org-setup.inc +#+TITLE: Writing snippets -* Writing snippets +* Snippet development -** Snippet development - -*** Quickly finding snippets +** Quickly finding snippets There are some ways you can quickly find a snippet file: @@ -30,7 +29,7 @@ There are some ways you can quickly find a snippet file: Once you find this file it will be set to =snippet-mode= (see ahead) and you can start editing your snippet. -*** Using the =snippet-mode= major mode +** Using the =snippet-mode= major mode There is a major mode =snippet-mode= to edit snippets. You can set the buffer to this mode with =M-x snippet-mode=. It provides reasonably @@ -54,7 +53,7 @@ Two commands are defined in this mode: There are also /snippets for writing snippets/: =vars=, =$f= and =$m= :-). -** File content +* File content A file defining a snippet generally contains the template to be expanded. @@ -76,14 +75,14 @@ Here's a typical example: Here's a list of currently supported directives: -*** =# key:= snippet abbrev +** =# key:= snippet abbrev This is the probably the most important directive, it's the abbreviation you type to expand a snippet just before hitting [[sym:yas-trigger-key][=yas-trigger-key=]]. If you don't specify this the snippet will not be expandable through the key mechanism. -*** =# name:= snippet name +** =# name:= snippet name This is a one-line description of the snippet. It will be displayed in the menu. It's a good idea to select a descriptive name for a snippet -- @@ -92,7 +91,7 @@ especially distinguishable among similar snippets. If you omit this name it will default to the file name the snippet was loaded from. -*** =# condition:= snippet condition +** =# condition:= snippet condition This is a piece of Emacs-lisp code. If a snippet has a condition, then it will only be expanded when the condition code evaluate to some @@ -101,7 +100,7 @@ non-nil value. See also [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] in [[./snippet-expansion.org][Expanding snippets]] -*** =# group:= snippet menu grouping +** =# group:= snippet menu grouping When expanding/visiting snippets from the menu-bar menu, snippets for a given mode can be grouped into sub-menus . This is useful if one has too @@ -118,7 +117,7 @@ Refer to the bundled snippets for =ruby-mode= for examples on the =control structure.loops= tells that the snippet is under the =loops= group which is under the =control structure= group. -*** =# expand-env:= expand environment +** =# expand-env:= expand environment This is another piece of Emacs-lisp code in the form of a =let= /varlist form/, i.e. a list of lists assigning values to variables. It can be @@ -148,7 +147,7 @@ You can then use: +--+-+--+ #+END_SRC -*** =# binding:= direct keybinding +** =# binding:= direct keybinding You can use this directive to expand a snippet directly from a normal Emacs keybinding. The keybinding will be registered in the Emacs keymap @@ -169,24 +168,24 @@ This binding will be recorded in the keymap =html-mode-map=. To expand a paragraph tag newlines, just press =C-u C-c C-c C-m=. Omitting the =C-u= will expand the paragraph tag without newlines. -*** =# contributor:= snippet author +** =# contributor:= snippet author This is optional and has no effect whatsoever on snippet functionality, but it looks nice. -** Template syntax +* Template syntax The syntax of the snippet template is simple but powerful, very similar to TextMate's. -*** Plain Text +** Plain Text Arbitrary text can be included as the content of a template. They are usually interpreted as plain text, except =$= and ==. You need to use \` to escape them: =\$= and =\=. The \` itself may also needed to be escaped as =\\= sometimes. -*** Embedded Emacs-lisp code +** Embedded Emacs-lisp code Emacs-Lisp code can be embedded inside the template, written inside back-quotes (==). The lisp forms are evaluated when the snippet is @@ -219,7 +218,7 @@ to "wrap" the selected region inside your recently inserted snippet. Alternatively, you can also customize the variable [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] to =t= which will do this automatically. -*** Tab stop fields +** Tab stop fields Tab stops are fields that you can navigate back and forth by =TAB= and =S-TAB=. They are written by =$= followed with a number. =$0= has the @@ -231,7 +230,7 @@ to go when you've traveled all the fields. Here's a typical example: $0 #+END_SRC -*** Placeholder fields +** Placeholder fields Tab stops can have default values -- a.k.a placeholders. The syntax is like this: @@ -245,7 +244,7 @@ type at a tab stop, the default value will be replaced by your typing. The number can be omitted if you don't want to create [[mirrors]] or [[transformations]] for this field. -*** <> +** <> We refer the tab stops with placeholders as a /field/. A field can have mirrors. Its mirrors will get updated when you change the text of a @@ -265,7 +264,7 @@ The tab stops with the same number to the field act as its mirrors. If none of the tab stops has an initial value, the first one is selected as the field and others mirrors. -*** Mirrors with <> +** Mirrors with <> If the value of an =${n:=-construct starts with and contains =$(=, then it is interpreted as a mirror for field =n= with a transformation. The @@ -323,7 +322,7 @@ is not. Here's an snippet for rst title: $0 #+END_SRC -*** Fields with transformations +** Fields with transformations From version 0.6 on, you can also have lisp transformation inside fields. These work mostly mirror transformations but are evaluated when @@ -351,7 +350,7 @@ value of the field and sets it its internal modification state to =true=. As a consequence, the auto-deletion behaviour of normal fields does not take place. This is by design. -*** Choosing fields value from a list and other tricks +** Choosing fields value from a list and other tricks As mentioned, the field transformation is invoked just after you enter the field, and with some useful variables bound, notably @@ -384,7 +383,7 @@ The function [[sym:yas-verify-value][=yas-verify-value=]] has another neat trick [[sym:yas-moving-away-p][=yas-moving-away-p=]]. Try it and see! Also, check out this [[http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662][thread]] -*** Nested placeholder fields +** Nested placeholder fields From version 0.6 on, you can also have nested placeholders of the type: @@ -402,7 +401,7 @@ By the way, =C-d= will only clear the field if you cursor is at the beginning of the field /and/ it hasn't been changed yet. Otherwise, it performs the normal Emacs =delete-char= command. -** Importing TextMate snippets +* Importing TextMate snippets There are a couple of tools that take TextMate's ".tmSnippet" xml files and create YASnippet definitions: diff --git a/doc/snippet-expansion.org b/doc/snippet-expansion.org index 349b352..9b31d64 100644 --- a/doc/snippet-expansion.org +++ b/doc/snippet-expansion.org @@ -1,14 +1,14 @@ #+SETUPFILE: org-setup.inc #+OPTIONS: H:4 -* Expanding snippets +#+TITLE: Expanding snippets This section describes how YASnippet chooses snippets for expansion at point. Maybe, you'll want some snippets to be expanded in a particular mode, or only under certain conditions, or be prompted using -** Triggering expansion +* Triggering expansion You can use YASnippet to expand snippets in different ways: @@ -30,7 +30,7 @@ - Expanding from emacs-lisp code -*** Trigger key +** Trigger key [[sym:yas-expand][=yas-expand=]] tries to expand a /snippet abbrev/ (also known as /snippet key/) before point. @@ -54,7 +54,7 @@ When you use [[sym:yas-global-mode][=yas-global-mode=]] you can also selectively YASnippet in some buffers by setting the buffer-local variable [[sym:yas-dont-active][=yas-dont-active=]] in the buffer's mode hook. -**** Fallback bahaviour +*** Fallback bahaviour [[sym:yas-fallback-behaviour][=yas-fallback-behaviour=]] is a customization variable bound to '=call-other-command= by default. If [[sym:yas-expand][=yas-expand=]] failed to find any @@ -70,7 +70,7 @@ However, you can change this behavior by customizing the '=return-nil=, it will return =nil= instead of trying to call the /original/ command when no snippet is found. -*** Insert at point +** Insert at point The command [[#yas-insert-snippet][=yas-insert-snippet=]] lets you insert snippets at point /for your current major mode/. It prompts you for the snippet key @@ -84,22 +84,22 @@ snippets for the major mode, prefix this command with =C-u=. The prompting methods used are again controlled by [[sym:yas-prompt-functions][=yas-prompt-functions=]]. -*** Snippet keybinding +** Snippet keybinding See the section of the =# binding:= directive in [[./snippet-development.org][Writing Snippets]]. -*** Expanding from the menu +** Expanding from the menu See [[./snippet-menu.org][the YASnippet Menu]]. -*** Expanding with =hippie-expand= +** Expanding with =hippie-expand= To integrate with =hippie-expand=, just put [[sym:yas-hippie-try-expand][=yas-hippie-try-expand=]] in =hippie-expand-try-functions-list=. This probably makes more sense when placed at the top of the list, but it can be put anywhere you prefer. -*** Expanding from emacs-lisp code +** Expanding from emacs-lisp code Sometimes you might want to expand a snippet directly from you own elisp code. You should call [[sym:yas-expand-snippet][=yas-expand-snippet=]] instead of [[sym:yas-expand][=yas-expand=]] in @@ -116,9 +116,9 @@ YASnippet menu has the same effect of evaluating the follow code: See the internal documentation on [[sym:yas-expand-snippet][=yas-expand-snippet=]] for more information. -** Controlling expansion +* Controlling expansion -*** Eligible snippets +** Eligible snippets YASnippet does quite a bit of filtering to find out which snippets are eligible for expanding at the current cursor position. @@ -165,7 +165,7 @@ In particular, the following things matter: expand snippets inside comments or string literals for example. See The condition system\_ for more info. -*** The condition system +** The condition system Consider this scenario: you are an old Emacs hacker. You like the abbrev-way and bind [[sym:yas-expand][=yas-expand=]] to =SPC=. However, you don't want @@ -200,7 +200,7 @@ expanded in comment. For the full set of possible conditions, see the documentation for [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]. -*** Multiples snippet with the same key +** Multiples snippet with the same key The rules outlined [[Eligible%20snippets][above]] can return more than one snippet to be expanded at point. @@ -220,7 +220,7 @@ can put in your emacs-file: Currently there are some alternatives solution with YASnippet. -**** Use the X window system +*** Use the X window system [[./images/x-menu.png]] @@ -234,7 +234,7 @@ means: navigate this menu. - This function can't be used when in a terminal. -**** Minibuffer prompting +*** Minibuffer prompting [[./images/ido-menu.png]] @@ -242,7 +242,7 @@ You can use functions [[sym:yas-completing-prompt][=yas-completing-prompt=]] for completion method or [[sym:yas-ido-prompt][=yas-ido-prompt=]] for a much nicer looking method. The best way is to try it. This works in a terminal. -**** Use =dropdown-menu.el= +*** Use =dropdown-menu.el= [[./images/dropdown-menu.png]] @@ -253,7 +253,7 @@ This works in both window system and terminal and is customizable, you can use =C-n=, =C-p= to navigate, =q= to quit and even press =6= as a shortcut to select the 6th candidate. -**** Roll your own +*** Roll your own See the documentation on variable [[sym:yas-prompt-functions][=yas-prompt-functions=]] diff --git a/doc/snippet-menu.org b/doc/snippet-menu.org index 8477dab..46b9b0c 100644 --- a/doc/snippet-menu.org +++ b/doc/snippet-menu.org @@ -1,6 +1,6 @@ #+SETUPFILE: org-setup.inc -* YASnippet menu +#+TITLE: YASnippet menu When [[sym:yas-minor-mode][=yas-minor-mode=]] is active, YASnippet will setup a menu just after the "Buffers" menu in the menubar. @@ -19,7 +19,7 @@ In this menu, you can find [[./images/menu-1.png]] -** Loading snippets from menu +* Loading snippets from menu Invoking "Load snippets..." from the menu invokes [[sym:yas-load-directory][=yas-load-directory=]] and prompts you for a snippet directory hierarchy to load. @@ -28,7 +28,7 @@ Also useful is the "Reload everything" item to invoke [[#yas-reload-all][=yas-re which uncondionally reloads all the snippets directories defined in [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] and rebuilds the menus. -** Snippet menu behavior +* Snippet menu behavior YASnippet will list in this section all the loaded snippet definitions organized by snippet table name. @@ -51,19 +51,19 @@ mode, set [[sym:yas-use-menu][=yas-use-menu=]] to =abbreviate=. These customizations can also be found in the menu itself, under the "Snippet menu behavior" submenu. -** Controlling indenting +* Controlling indenting The "Indenting" submenu contains options to control the values of [[sym:yas-indent-line][=yas-indent-line=]] and [[sym:yas-also-auto-indent-first-line][=yas-also-auto-indent-first-line=]]. See [[./snippet-development.org][Writing snippets]] . -** Prompting method +* Prompting method The "Prompting method" submenu contains options to control the value of [[sym:yas-prompt-functions][=yas-prompt-functions=]]. See [[./snippet-expansion.org][Expanding snippets]] . -** Misc +* Misc The "Misc" submenu contains options to control the values of more variables. diff --git a/doc/snippet-organization.org b/doc/snippet-organization.org index 2adb048..0ec12a1 100644 --- a/doc/snippet-organization.org +++ b/doc/snippet-organization.org @@ -1,8 +1,8 @@ #+SETUPFILE: org-setup.inc -* Organizing snippets +#+TITLE: Organizing snippets -** Basic structure +* Basic structure Snippet collections can be stored in plain text files. They are arranged by sub-directories naming *snippet tables*. These mostly name Emacs major names. @@ -22,7 +22,7 @@ triggering mechanism (see [[file:snippet-expansion.org][Expanding Snippets]]) looks up and (hopefully) causes the right snippet to be expanded for you. -** Setting up =yas-snippet-dirs= +* Setting up =yas-snippet-dirs= The emacs variable [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet which collections to consider. It's used when you activate @@ -52,7 +52,7 @@ appearing in collections later in the list. [[sym:yas-new-snippet][=yas-new-snippet=]] always stores snippets in the first collection. -** The =.yas-parents= file +* The =.yas-parents= file It's very useful to have certain modes share snippets between themselves. To do this, choose a mode subdirectory and place a @@ -77,7 +77,7 @@ #+end_example -** TODO The =.yas-make-groups= file +* TODO The =.yas-make-groups= file If you place an empty plain text file =.yas-make-groups= inside one of the mode directories, the names of these sub-directories are @@ -108,14 +108,14 @@ Yet another way to create a nice snippet menu is to write into =.yas-make-groups= a menu definition. TODO -** TODO The =.yas-setup.el= file +* TODO The =.yas-setup.el= file -*** TODO +** TODO -** TODO The =.yas-compiled-snippet.el= file +* TODO The =.yas-compiled-snippet.el= file -*** TODO +** TODO -** TODO The =.yas-skip= file +* TODO The =.yas-skip= file -*** TODO +** TODO diff --git a/doc/snippet-reference.org b/doc/snippet-reference.org index 14fef9e..316a9c8 100644 --- a/doc/snippet-reference.org +++ b/doc/snippet-reference.org @@ -1,6 +1,9 @@ #+STARTUP: showall +#+TITLE: Reference + * Reference + #+BEGIN_SRC emacs-lisp :exports results :results value raw (yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form) `("Customization variables" . ,#'(lambda (sym)