--- /dev/null
+#+SETUPFILE: org-setup.inc
+
+#+TITLE: 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 [[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 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
+
+** TODO