update doc to reflect recent changes, needs reviewing badly

doc/changelog.rst

@@ -7,6 +7,13 @@ ChangeLog
 .. _Writing Snippets: snippet-development.html
 .. _The YASnippet Menu: snippet-menu.html
 
+0.7.0b / ????-??-??
+===================
+
+* Filenames can no longer be snippet triggers. Please upgrade your snippet
+  collections.
+
+
 0.6.1c / 2009-08-13
 ===================
 

doc/snippet-development.rst

@@ -91,19 +91,9 @@ Here's a list of currently supported directives:
 ``# key:`` snippet abbrev
 --------------------------
 
-This is the probably the most important directive, it's the
+This is the probably the most important directive, it's the abbreviation you
-abbreviation you type to expand a snippet just before hitting
+type to expand a snippet just before hitting ``yas/trigger-key``. If you don't
-``yas/trigger-key``.
+specify this the snippet will not be expandable through the key mechanism.
-
-If you don't specify this it will default to the name of the file the
-snippet is being loaded from, unless YASnippet is ignoring file names
-as triggers (see ``yas/ignore-filenames-as-triggers`` in `Organizing
-snippets`_), in which case this snippet
-will not be expandable through the key mechanism.
-
-Sometimes the key of a snippet is non-ASCII or not valid filename
-(e.g. contains ``/``). One can then define the ``key`` property which
-will overwrite the filename as the key to expand the snippet.
 
 ``# name:`` snippet name
 ------------------------
@@ -191,33 +181,14 @@ snippet.
 .. sourcecode:: text
 
   #name : <p>...</p>
-  #binding: "C-c C-c C-m"
+  #binding: C-c C-c C-m
   # --
   <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
 
-This binding will be recorded in the keymap ``html-mode-map``. To
+This binding will be recorded in the keymap
-expand a paragraph tag newlines, just press "C-u C-c C-c
+``html-mode-map``. To expand a paragraph tag newlines, just
-C-m". Omitting the "C-u" will expand the paragraph tag without
+press ``C-u C-c C-c C-m``. Omitting the ``C-u`` will expand the
-newlines.
+paragraph tag without newlines.
-
-To override the keymap choice based on the major mode name. Use a cons
-cell where the first element specifies the name of the keymap where
-you want to record the keybinding.
-
-.. sourcecode:: text
-
-  #name : <p>...</p>
-  #binding: (rinari-minor-mode-map . "C-c C-c C-m")
-  # --
-  <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
-
-**Note**: this feature is still **experimental**, it might go away, be
-changed in future release, and should be used with caution: It is easy
-to override important keybindings for many basic modes and it is hard
-to undefine them. For the moment, the variable
-``yas/active-keybindings`` can tell you what snippet keybindings are
-active and the function ``yas/kill-snippet-keybindings`` will attempt
-to undefine all the keybindings.
 
 ``# contributor:`` snippet author
 ---------------------------------------------------
@@ -225,7 +196,6 @@ to undefine all the keybindings.
 This is optional and has no effect whatsoever on snippet
 functionality, but it looks nice.
 
-
 Template syntax
 ===============
 

doc/snippet-organization.rst

@@ -62,60 +62,22 @@ 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
+Snippet definitions are put in plain text files. They are arranged
-sub-directories, and the snippet tables are named after these directories.
+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. You can also skip snippet storage altogether
+``c-mode`` sub-directory.
-and use the bundle (see `YASnippet bundle`_).
 
-Nested organization
+The ``.yas.parents`` file
--------------------
+-------------------------
 
-Here is an excerpt of a directory hierarchy containing snippets
+It's very useful to have certain modes share snippets between
-for some modes:
+themselves. To do this, choose a mode subdirectory and place a
-
+``.yas-parents`` containing a whitespace-separated list of other
-.. sourcecode:: text
+mode names. When you reload those modes become parents of the
-
+original mode.
-  $ tree
-  .
-  `-- text-mode
-      |-- cc-mode
-      |   |-- c-mode
-      |   |   `-- printf
-      |   |-- for
-      |   |-- java-mode
-      |   |   `-- println
-      |   `-- while
-      |-- email
-      |-- perl-mode
-      |   |-- cperl-mode
-      |   `-- for
-      `-- time
-
-A parent directory acts as a *parent table* of any of its
-sub-directories. This is one of the ways different Emacs major modes
-can share snippet definitions. As you can see above, ``c-mode`` and
-``java-mode`` share the same parent ``cc-mode`` and its ``while``
-snipepts, while all modes are share the ``time`` snippet from
-``text-mode``.
-
-This can be also used to as an *alias* -- ``cperl-mode`` is an empty
-directory whose parent is ``perl-mode``.
-
-.. image:: images/menu-parent.png
-   :align: right
-
-The ``.yas-parents`` file
-------------------------------
-
-An alternate (and preferred) way of setting up parent tables consists
-of placing a plain text file ``.yas-parents`` inside one of the
-sub-directories. By doing this, you avoid complex directory
-nesting. In the ``.yas-parents`` file you just write
-whitespace-separated names of modes. This allows more flexibility and
-readability of your snippet hierarchy.
 
 .. sourcecode:: text
 
@@ -165,38 +127,6 @@ directive inside the snippet definition. See `Writing Snippets`_.
       `-- ...
 
 
-Using plain file names
-----------------------
-
-Normally, file names act as the snippet expansion *abbreviation* (also
-known as the *snippet key* or *snippet trigger*, see `Expanding
-Snippets`_).
-
-However, if you customize the variable
-``yas/ignore-filenames-as-triggers`` to be true *or* place an empty
-file ``.yas-ignore-filename-triggers`` you can use much more
-descriptive file names. This is useful if many snippets within a mode
-share the same trigger key.
-
-.. sourcecode:: text
-
-  $ tree rails-mode/
-  rails-mode/
-  |-- .yas-make-groups
-  |-- .yas-ignore-filename-triggers
-  |-- Insert ERb's <% __ %> or <%= __ %>.yasnippet
-  |-- asserts
-  |   |-- assert(var = assigns(%3Avar)).yasnippet
-  |   |-- assert_difference.yasnippet
-  |   |-- assert_no_difference.yasnippet
-  |   |-- assert_redirected_to (nested path plural).yasnippet
-  |   |-- assert_redirected_to (nested path).yasnippet
-  |   |-- assert_redirected_to (path plural).yasnippet
-  |   |-- assert_redirected_to (path).yasnippet
-  |   |-- assert_rjs.yasnippet
-  |   `-- assert_select.yasnippet
-
-
 YASnippet bundle
 ================