[elpa] master 875ef77 044/177: move index.org subsection into snippet-organization.org

[João Távora]

branch: master
commit 875ef77dfb20d0096144df76d37cf3a4140a747e
Author: Noam Postavsky <address@hidden>
Commit: Noam Postavsky <address@hidden>

    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.
---
 doc/index.org                |  114 ----------------------
 doc/snippet-organization.org |  220 ++++++++++++++++++++++--------------------
 2 files changed, 116 insertions(+), 218 deletions(-)

diff --git a/doc/index.org b/doc/index.org
index e06f715..c4bb052 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 9ca14c0..d145f05 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 address@hidden 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