From: Noam Postavsky Date: Sun, 24 Nov 2013 21:00:04 +0000 (-0500) Subject: move index.org subsection into snippet-organization.org X-Git-Url: https://code.delx.au/gnu-emacs-elpa/commitdiff_plain/875ef77dfb20d0096144df76d37cf3a4140a747e move index.org subsection into snippet-organization.org This almost completely overwrites the existing snippet-organization.org which was imported from snippet-organization.rst via pandoc. --- diff --git a/doc/index.org b/doc/index.org index e06f715d5..c4bb052ba 100644 --- a/doc/index.org +++ b/doc/index.org @@ -127,120 +127,6 @@ If you run into problems using YASnippet, or have snippets to contribute, post to the [[http://groups.google.com/group/smart-snippet][yasnippet forum]]. Thank you very much for using YASnippet! -* Organizing snippets - -** 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. - - #+begin_example - . - |-- c-mode - | `-- printf - |-- java-mode - | `-- println - `-- text-mode - |-- email - `-- time - #+end_example - - The collections are loaded into *snippet tables* which the triggering - mechanism (see [[#expand-snippets][Expanding snippets]]) looks up and - (hopefully) cause the right snippet to be expanded for you. - -** 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 - [[sym:yas-global-mode][=yas-global-mode=]] or call - [[sym:yas-reload-all][=yas-reload-all=]] interactively. - - The default considers: - - - a personal collection that lives in =~/.emacs.d/snippets= - - the bundled collection, taken as a relative path to =yasnippet.el= localtion - - When you come across other snippet collections, do the following to try them - out: - - #+begin_src emacs-lisp :exports code - ;; Develop in ~/emacs.d/mysnippets, but also - ;; try out snippets in ~/Downloads/interesting-snippets - (setq yas-snippet-dirs '("~/emacs.d/mysnippets" - "~/Downloads/interesting-snippets")) - - ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets - (setq yas-snippet-dirs (append yas-snippet-dirs - '("~/Downloads/interesting-snippets"))) - #+end_src - - Collections appearing earlier in the list shadow snippets with same names - 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 - - It's very useful to have certain modes share snippets between themselves. To do - this, choose a mode subdirectory and place a =.yas-parents= containing a - whitespace-separated list of other mode names. When you reload those modes - become parents of the original mode. - - #+begin_example - . - |-- c-mode - | |-- .yas-parents # contains "cc-mode text-mode" - | `-- printf - |-- cc-mode - | |-- for - | `-- while - |-- java-mode - | |-- .yas-parents # contains "cc-mode text-mode" - | `-- println - `-- text-mode - |-- email - `-- time - #+end_example - -** 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 considered groups of - snippets and [[snippet-menu][the menu]] is organized much more cleanly: - - (TODO image) - - Another alternative way to achieve this is to place a =# group:= directive - inside the snippet definition. See [[#writing-snippets][Writing Snippets]] - - #+begin_example - $ tree ruby-mode/ - ruby-mode/ - |-- .yas-make-groups - |-- collections - | |-- each - | `-- ... - |-- control structure - | |-- forin - | `-- ... - |-- definitions - | `-- ... - `-- general - `-- ... - #+end_example - - 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 - -** TODO The =.yas-compiled-snippet.el= file - -*** TODO - -** The =.yas-skip= file * Expanding Snippets diff --git a/doc/snippet-organization.org b/doc/snippet-organization.org index 9ca14c067..d145f0575 100644 --- a/doc/snippet-organization.org +++ b/doc/snippet-organization.org @@ -1,107 +1,119 @@ * Organizing snippets -** Loading snippets +** 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. + + #+begin_example + . + |-- c-mode + | `-- printf + |-- java-mode + | `-- println + `-- text-mode + |-- email + `-- time + #+end_example + + The collections are loaded into *snippet tables* which the + 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= + + The emacs variable [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet + which collections to consider. It's used when you activate + [[sym:yas-global-mode][=yas-global-mode=]] or call + [[sym:yas-reload-all][=yas-reload-all=]] interactively. + + The default considers: + + - a personal collection that lives in =~/.emacs.d/snippets= + - the bundled collection, taken as a relative path to =yasnippet.el= localtion + + When you come across other snippet collections, do the following to try them + out: + + #+begin_src emacs-lisp :exports code + ;; Develop in ~/emacs.d/mysnippets, but also + ;; try out snippets in ~/Downloads/interesting-snippets + (setq yas-snippet-dirs '("~/emacs.d/mysnippets" + "~/Downloads/interesting-snippets")) + + ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets + (setq yas-snippet-dirs (append yas-snippet-dirs + '("~/Downloads/interesting-snippets"))) + #+end_src + + Collections appearing earlier in the list shadow snippets with same names + 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 + + It's very useful to have certain modes share snippets between + themselves. To do this, choose a mode subdirectory and place a + =.yas-parents= containing a whitespace-separated list of other mode + names. When you reload those modes become parents of the original + mode. + + #+begin_example + . + |-- c-mode + | |-- .yas-parents # contains "cc-mode text-mode" + | `-- printf + |-- cc-mode + | |-- for + | `-- while + |-- java-mode + | |-- .yas-parents # contains "cc-mode text-mode" + | `-- println + `-- text-mode + |-- email + `-- time + #+end_example + + +** 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 + considered groups of snippets and [[snippet-menu.org][the menu]] is organized much more + cleanly: + + [[images/menu-groups.png]] + + Another way to achieve this is to place a =# group:= directive + inside the snippet definition. See [[snippet-development.org][Writing Snippets]]. + + #+begin_example + $ tree ruby-mode/ + ruby-mode/ + |-- .yas-make-groups + |-- collections + | |-- each + | `-- ... + |-- control structure + | |-- forin + | `-- ... + |-- definitions + | `-- ... + `-- general + `-- ... + #+end_example + + 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 + +** TODO The =.yas-compiled-snippet.el= file + +*** TODO + +** TODO The =.yas-skip= file -Snippet definitions are stored in files in the filesystem. Unless you -use the simpler [[index.html@installation][bundle version]]), these are -arranged so that YASnippet can load them into /snippet tables/. The -triggering mechanisms (see [[snippet-expansion.html][Expanding -snippets]]) will look up these snippet tables and (hopefully) expand the -snippet you intended. - -The non-bundle version of YASnippet, once unpacked, comes with a full -directory of snippets, which you can copy somewhere and use. You can -also create or download more directories. - -Once these directories are in place reference them in the variable -=yas-root-directory= and load them with =yas-load-directory=: - -The point in using =yas-root-directory= (as opposed to calling -=yas-load-directory= directly) is considering "~/emacs.d/mysnippets" for -snippet development, so you can use commands like =yas-new-snippet= and -others described in section [[snippet-development.html][Writing -Snippets]]. - -You can make this variable a list and store more items into it: - -In this last example, the all the directories are loaded and their -snippets considered for expansion. However development still happens in -the first element, "~/emacs.d/mysnippets". - -** Organizing snippets - -Once you've setup =yas-root-directory= , you can store snippets inside -sub-directories of these directories. - -Snippet definitions are put in plain text files. They are arranged by -sub-directories, and the snippet tables are named after these -directories. - -The name corresponds to the Emacs mode where you want expansion to take -place. For example, snippets for =c-mode= are put in the =c-mode= -sub-directory. - -*** 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 -=.yas-parents= containing a whitespace-separated list of other mode -names. When you reload those modes become parents of the original mode. - -*** The =.yas-make-groups= file - -[[images/menu-groups.png]] - -If you place an empty plain text file =.yas-make-groups= inside one of -the mode directories, the names of these sub-directories are considered -groups of snippets and [[snippet-menu.html][The YASnippet Menu]] is -organized much more cleanly, as you can see in the image. - -Another alternative way to achieve this is to place a =# group:= -directive inside the snippet definition. See -[[snippet-development.html][Writing Snippets]]. - -** YASnippet bundle - -The most convenient way to define snippets for YASnippet is to put them -in a directory arranged by the mode and use =yas-load-directory= to load -them. - -However, this might slow down the Emacs start-up speed if you have many -snippets. You can use =yas-define-snippets= to define a bunch of -snippets for a particular mode in an Emacs-lisp file. - -Since this is hard to maintain, there's a better way: define your -snippets in directory and then call =M-x yas-compile-bundle= to compile -it into a bundle file when you modified your snippets. - -The release bundle of YASnippet is produced by =yas-compile-bundle=. The -bundle uses =yas-define-snippets= to define snippets. This avoids the IO -and parsing overhead when loading snippets. - -Further more, the generated bundle is a stand-alone file not depending -on =yasnippet.el=. The released bundles of YASnippet are all generated -this way. - -See the internal documentation for these functions - -- =M-x describe-function RET yas-define-snippets RET= -- =M-x describe-function RET yas-compile-bundle RET=. - -** Customizable variables - -*** =yas-root-directory= - -Root directory that stores the snippets for each major mode. - -If you set this from your .emacs, can also be a list of strings, for -multiple root directories. If you make this a list, the first element is -always the user-created snippets directory. Other directories are used -for bulk reloading of all snippets using =yas-reload-all= - -*** =yas-ignore-filenames-as-triggers= - -If non-nil, don't derive tab triggers from filenames. - -This means a snippet without a =# key:= directive wont have a tab -trigger. +*** TODO