update packages

2026-06-27 11:34:21 +02:00
parent 4be4f859c4
commit 1aaef48596
246 changed files with 7997 additions and 4359 deletions
@@ -0,0 +1,132 @@
+#+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 mode 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= location
+
+   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 override 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 [[file: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
+
+* The =.yas-setup.el= file
+
+  If there is file named =.yas-setup.el= in a mode's snippet
+  subdirectory, it is loaded along with the snippets.  Utility
+  functions used by the snippets can be put here.
+
+* The =.yas-compiled-snippet.el= file
+
+   You may compile a top-level snippet directory with the
+   =yas-compile-directory= function, which will create a
+   =.yas-compiled-snippets.el= file under each mode subdirectory,
+   which contains definitions for all snippets in the subdirectory.
+   Compilation helps improve loading time.
+
+   Alternatively, you may compile all directories in the list
+   =yas-snippet-dirs= with the =yas-recompile-all= function.
+
+* The =.yas-skip= file
+
+  A =.yas-skip= file in a mode's snippet subdirectory tells YASnippet
+  not to load snippets from there.