emacs-elpa-diffs
[Top][All Lists]

## [elpa] master f6cace0 042/177: convert old rst manuals to org mode

 From: João Távora Subject: [elpa] master f6cace0 042/177: convert old rst manuals to org mode Date: Sat, 28 Mar 2015 15:40:42 +0000

branch: master
commit f6cace08f378fe4aff18342860c4ee47220ff056

convert old rst manuals to org mode

This is just the initial conversion with pandoc, they still need to be
fixed up. Also define new org files as a project in yas-doc-helper.el.
---
doc/faq.org                  |   93 +++++++++
doc/index.org                |   40 ++++-
doc/snippet-development.org  |  434 ++++++++++++++++++++++++++++++++++++++++++
doc/snippet-expansion.org    |  333 ++++++++++++++++++++++++++++++++
doc/snippet-organization.org |  107 +++++++++++
doc/yas-doc-helper.el        |   15 ++
7 files changed, 1082 insertions(+), 7 deletions(-)

diff --git a/doc/faq.org b/doc/faq.org
new file mode 100644
index 0000000..d45b2c3
--- /dev/null
+++ b/doc/faq.org
@@ -0,0 +1,93 @@
+
+** Why is there an extra newline?
+
+If you have a newline at the end of the snippet definition file, then
+YASnippet will add a newline when you expanding a snippet. Please don't
+add a newline at the end if you don't want it when you saving the
+snippet file.
+
+Note some editors will automatically add a newline for you. In Emacs, if
+you set =require-final-newline= to =t=, it will add the final newline
+for you automatically.
+
+** Why doesn't TAB expand a snippet?
+
+First check the mode line to see if there's =yas=. If not, then try
+=M-x yas-minor-mode= to manually turn on the minor mode and try to
+expand the snippet again. If it works, then, you can add the following
+
+where =the-major-mode= is the major mode in which =yas-minor-mode= isn't
+enabled by default.
+
+From YASnippet 0.6 you can also use the command =M-x yas-global-mode= to
+turn on YASnippet automatically for /all/ major modes.
+
+If =yas-minor-mode= is on but the snippet still not expanded. Then try
+to see what command is bound to the =TAB= key: press =C-h k= and then
+press =TAB=. Emacs will show you the result.
+
+You'll see a buffer prompted by Emacs saying that
+=TAB runs the command ...=. Alternatively, you might see
+=<tab> runs the command ...=, note the difference between =TAB= and
+=<tab>= where the latter has priority. If you see =<tab>= bound to a
+command other than =yas-expand=, (e.g. in =org-mode=) you can try the
+following code to work around:
+
+replace =org-mode-hook= and =org-mode-map= with the major mode hook you
+are dealing with (Use =C-h m= to see what major mode you are in).
+
+As an alternative, you can also try
+
+To /advise/ the modes indentation function bound to TAB, (in this case
+=ruby-indent-line=) to first try to run =yas-expand=.
+
+If the output of =C-h k RET <tab>= tells you that =<tab>= is indeed
+bound to =yas-expand= but YASnippet still doesn't work, check your
+configuration and you may also ask for help on the
+this particular
+for quite some solutions and alternatives.
+
+Don't forget to attach the information on what command is bound to TAB
+as well as the mode information (Can be obtained by =C-h m=).
+
+** Why doesn't TAB navigation work with flyspell
+
+A workaround is to inhibit flyspell overlays while the snippet is
+active:
+
+This is apparently related to overlay priorities. For some reason, the
+=keymap= property of flyspell's overlays always takes priority over the
+same property in yasnippet's overlays, even if one sets the latter's
+=priority= property to something big. If you know emacs-lisp and can
+solve this problem, drop a line in the
+
+** How do I turn off the minor mode where in some buffers
+
+The best way, since version 0.6.1c, is to set the default value of the
+variable =yas-dont-activate= to a lambda function like so:
+
+This is also the default value starting for that version. It skips the
+minor mode in buffers where it is not applicable (no snippet tables),
+but only once you have setup your yas-root-directory.
+
+** How do I define an abbrev key containing characters not supported by
+the filesystem?
+
+-  *Note*: This question applies if you're still defining
+   snippets :: whose key /is/ the filename. This is behavior stil
+   provided by version 0.6 for backward compatibilty, but is somewhat
+   deprecated...
+
+For example, you want to define a snippet by the key =<= which is not a
+valid character for filename on Windows. This means you can't use the
+filename as a trigger key in this case.
+
+You should rather use the =# key:= directive to specify the key of the
+defined snippet explicitly and name your snippet with an arbitrary valid
+filename, =lt.yasnippet= for example, using =<= for the =# key:=
+directive:
diff --git a/doc/index.org b/doc/index.org
index c6d1535..055013b 100644
--- a/doc/index.org
+++ b/doc/index.org
@@ -2,8 +2,6 @@
#+OPTIONS: toc:1
#+STARTUP: showall

/>
-
* Quick start

*YASnippet* is a template system for Emacs. It allows you to type an
@@ -83,12 +81,40 @@
files that guide it with more difficult importations. The idea is to
deprecate
=/snippets=  and replace it with =extras/imported=.

-** Documentation, issues, etc
+** Documentation
+
+   The documentation has been split into separate parts:
+
+   1. [[file:snippet-organization.org][Organizing Snippets]]
+      #+BEGIN_QUOTE
+      Describes ways to organize your snippets in the hard disk.
+      #+END_QUOTE
+
+   2. [[file:snippet-expansion.org][Expanding Snippets]]
+      #+BEGIN_QUOTE
+      Describes how YASnippet chooses snippets for expansion at point.
+
+      Maybe, you'll want some snippets to be expanded in a particular mode,
+      or only under certain conditions, or be prompted using =ido=, etc...
+      #+END_QUOTE
+
+   3. [[file:snippet-development.org][Writing Snippets]]
+      #+BEGIN_QUOTE
+      Describes the YASnippet definition syntax, which is very close (but
+      not equivalent) to Textmate's. Includes a section about converting
+      TextMate snippets.
+      #+END_QUOTE
+
+      #+BEGIN_QUOTE
+      Explains how to use the YASnippet menu to explore, learn and modify
+      snippets.
+      #+END_QUOTE
+
+** Bugs, discussion, contributions, etc

-   Please refer to the comprehensive
[[http://capitaomorte.github.com/yasnippet][documentation]] for full
customization and
-   support. If you think you've found a bug, please report it on
[[https://github.com/capitaomorte/yasnippet/issues][the GitHub
-   issue tracker]]. (please **do not** submit new issues to the old
-   tracker]])
+   If you think you've found a bug, please report it on
[[https://github.com/capitaomorte/yasnippet/issues][the GitHub issue tracker]]
+   (please **do not** submit new issues to the old

If you run into problems using YASnippet, or have snippets to contribute,
forum]]. Thank you very much for using YASnippet!
diff --git a/doc/snippet-development.org b/doc/snippet-development.org
new file mode 100644
index 0000000..7298ff9
--- /dev/null
+++ b/doc/snippet-development.org
@@ -0,0 +1,434 @@
+* Writing snippets
+
+** Snippet development
+
+*** Quickly finding snippets
+
+There are some ways you can quickly find a snippet file:
+
+-  =M-x yas-new-snippet=
+
+   Prompts you for a snippet name, then tries to guess a suitable
+   directory to store it, prompting you for creation if it does not
+   exist. Finally, places you in a new buffer set to =snippet-mode= so
+   you can write your snippet.
+
+-  =M-x yas-find-snippets=
+
+   Lets you find the snippet file in the directory the snippet was
+   loaded from (if it exists) like =find-file-other-window=. The
+   directory searching logic is similar to =M-x yas-new-snippet=.
+
+-  =M-x yas-visit-snippet-file=
+
+   Prompts you for possible snippet expansions like
+   =yas-insert-snippet=, but instead of expanding it, takes you directly
+   to the snippet definition's file, if it exists.
+
+Once you find this file it will be set to =snippet-mode= (see ahead) and
+you can start editing your snippet.
+
+*** Using the =snippet-mode= major mode
+
+There is a major mode =snippet-mode= to edit snippets. You can set the
+buffer to this mode with =M-x snippet-mode=. It provides reasonably
+useful syntax highlighting.
+
+Two commands are defined in this mode:
+
+
+   #+BEGIN_QUOTE
+     When editing a snippet, this loads the snippet into the correct
+     mode and menu. Bound to =C-c C-c= by default while in
+     =snippet-mode=.
+   #+END_QUOTE
+
+-  =M-x yas-tryout-snippet=
+
+   #+BEGIN_QUOTE
+     When editing a snippet, this opens a new empty buffer, sets it to
+     the appropriate major mode and inserts the snippet there, so you
+     can see what it looks like. This is bound to =C-c C-t= while in
+     =snippet-mode=.
+   #+END_QUOTE
+
+There are also /snippets for writing snippets/: =vars=, =$f= and =$m=
+:-).
+
+** File content
+
+A file defining a snippet generally contains the template to be
+expanded.
+
+Optionally, if the file contains a line of =# --=, the lines above it
+count as comments, some of which can be /directives/ (or meta data).
+Snippet directives look like =# property: value= and tweak certain
+snippets properties described below. If no =# --= is found, the whole
+file is considered the snippet template.
+
+Here's a typical example:
+
+Here's a list of currently supported directives:
+
+*** =# key:= snippet abbrev
+
+This is the probably the most important directive, it's the abbreviation
+you type to expand a snippet just before hitting =yas-trigger-key=. If
+you don't specify this the snippet will not be expandable through the
+key mechanism.
+
+*** =# name:= snippet name
+
+This is a one-line description of the snippet. It will be displayed in
+the menu. It's a good idea to select a descriptive name for a snippet --
+especially distinguishable among similar snippets.
+
+If you omit this name it will default to the file name the snippet was
+
+*** =# condition:= snippet condition
+
+This is a piece of Emacs-lisp code. If a snippet has a condition, then
+it will only be expanded when the condition code evaluate to some
+non-nil value.
+
+[[snippet-expansion.html][Expanding snippets]]
+
+*** =# group:= snippet menu grouping
+
+given mode can be grouped into sub-menus . This is useful if one has too
+many snippets for a mode which will make the menu too long.
+
+The =# group:= property only affect menu construction (See
+achieved by grouping snippets into sub-directories and using the
+=.yas-make-groups= special file (for this see
+[[snippet-organization.html][Organizing Snippets]]
+
+Refer to the bundled snippets for =ruby-mode= for examples on the
+=# group:= directive. Group can also be nested, e.g.
+=control structure.loops= tells that the snippet is under the =loops=
+group which is under the =control structure= group.
+
+*** =# expand-env:= expand environment
+
+This is another piece of Emacs-lisp code in the form of a =let= /varlist
+form/, i.e. a list of lists assigning values to variables. It can be
+used to override variable values while the snippet is being expanded.
+
+Interesting variables to override are =yas-wrap-around-region= and
+=yas-indent-line= (see [[snippet-expansion.html][Expanding Snippets]]).
+
+As an example, you might normally have =yas-indent-line= set to ='auto=
+and =yas-wrap-around-region= set to =t=, but for this particularly
+brilliant piece of ASCII art these values would mess up your hard work.
+You can then use:
+
+*** =# binding:= direct keybinding
+
+You can use this directive to expand a snippet directly from a normal
+Emacs keybinding. The keybinding will be registered in the Emacs keymap
+named after the major mode the snippet is active for.
+
+Additionally a variable =yas-prefix= is set to to the prefix argument
+you normally use for a command. This allows for small variations on the
+same snippet, for example in this "html-mode" snippet.
+
+This binding will be recorded in the keymap =html-mode-map=. To expand a
+paragraph tag newlines, just press =C-u C-c C-c C-m=. Omitting the =C-u=
+will expand the paragraph tag without newlines.
+
+*** =# contributor:= snippet author
+
+This is optional and has no effect whatsoever on snippet functionality,
+but it looks nice.
+
+** Template syntax
+
+The syntax of the snippet template is simple but powerful, very similar
+to TextMate's.
+
+*** Plain Text
+
+Arbitrary text can be included as the content of a template. They are
+usually interpreted as plain text, except =$= and ==. You need to +use \ to escape them: =\$= and =\=. The \ itself may also needed to be
+escaped as =\\= sometimes.
+
+*** Embedded Emacs-lisp code
+
+Emacs-Lisp code can be embedded inside the template, written inside
+back-quotes (==). The lisp forms are evaluated when the snippet is
+being expanded. The evaluation is done in the same buffer as the
+snippet being expanded.
+
+Here's an example for c-mode to calculate the header file guard
+dynamically:
+
+From version 0.6, snippets expansions are run with some special
+Emacs-lisp variables bound. One of this is =yas-selected-text=. You can
+therefore define a snippet like:
+
+to "wrap" the selected region inside your recently inserted snippet.
+Alternatively, you can also customize the variable
+=yas-wrap-around-region= to =t= which will do this automatically.
+
+*** Tab stop fields
+
+Tab stops are fields that you can navigate back and forth by =TAB= and
+=S-TAB=. They are written by =$= followed with a number. =$0= has the
+special meaning of the /exit point/ of a snippet. That is the last place
+to go when you've traveled all the fields. Here's a typical example:
+
+*** Placeholder fields
+
+Tab stops can have default values -- a.k.a placeholders. The syntax is
+like this:
+
+They acts as the default value for a tab stop. But when you firstly type
+at a tab stop, the default value will be replaced by your typing. The
+number can be omitted if you don't want to create mirrors\_ or
+transformations\_ for this field.
+
+*** Mirrors
+
+We refer the tab stops with placeholders as a /field/. A field can have
+mirrors. Its mirrors will get updated when you change the text of a
+field. Here's an example:
+
+When you type ="document"= at =${1:enumerate}=, the word ="document"= +will also be inserted at =\end{$1}=. The best explanation is to see the
+
+The tab stops with the same number to the field act as its mirrors. If
+none of the tab stops has an initial value, the first one is selected as
+the field and others mirrors.
+
+*** Mirrors with transformations
+
+If the value of an =${n:=-construct starts with and contains =$(=, then
+it is interpreted as a mirror for field =n= with a transformation. The
+mirror's text content is calculated according to this transformation,
+which is Emacs-lisp code that gets evaluated in an environment where the
+variable =text= (or =yas-text=) is bound to the text content (string)
+contained in the field =n=.Here's an example for Objective-C:
+
+Look at =${2:$(capitalize text)}=, it is a mirror with transformation
+instead of a field. The actual field is at the first line: =${2:foo}=. +When you type text in =${2:foo}=, the transformation will be evaluated
+and the result will be placed there as the transformed text. So in this
+example, if you type "baz" in the field, the transformed text will be
+"Baz". This example is also available in the screencast.
+
+Another example is for =rst-mode=. In reStructuredText, the document
+title can be some text surrounded by "===" below and above. The "==="
+should be at least as long as the text. So
+
+is a valid title but
+
+is not. Here's an snippet for rst title:
+
+*** Fields with transformations
+
+From version 0.6 on, you can also have lisp transformation inside
+fields. These work mostly mirror transformations but are evaluated when
+you first enter the field, after each change you make to the field and
+also just before you exit the field.
+
+The syntax is also a tiny bit different, so that the parser can
+distinguish between fields and mirrors. In the following example
+
+=mydefine= gets automatically upcased to =MYDEFINE= once you enter the
+field. As you type text, it gets filtered through the transformation
+every time.
+
+Note that to tell this kind of expression from a mirror with a
+transformation, YASnippet needs extra text between the =:= and the
+transformation's =$=. If you don't want this extra-text, you can use two +=$='s instead.
+
+Please note that as soon as a transformation takes place, it changes the
+value of the field and sets it its internal modification state to
+=true=. As a consequence, the auto-deletion behaviour of normal fields
+does not take place. This is by design.
+
+*** Choosing fields value from a list and other tricks
+
+As mentioned, the field transformation is invoked just after you enter
+the field, and with some useful variables bound, notably
+=yas-modified-p= and =yas-moving-away-p=. Because of this feature you
+can place a transformation in the primary field that lets you select
+default values for it.
+
+The =yas-choose-value= does this work for you. For example:
+
+See the definition of =yas-choose-value= to see how it was written using
+the two variables.
+
+Here's another use, for LaTeX-mode, which calls reftex-label just as you
+enter snippet field 2. This one makes use of =yas-modified-p= directly.
+
+The function =yas-verify-value= has another neat trick, and makes use of
+=yas-moving-away-p=. Try it and see! Also, check out this
+
+*** Nested placeholder fields
+
+From version 0.6 on, you can also have nested placeholders of the type:
+
+This allows you to choose if you want to give this =div= an =id=
+attribute. If you tab forward after expanding it will let you change
+"some\_id" to whatever you like. Alternatively, you can just press =C-d=
+(which executes =yas-skip-and-clear-or-delete-char=) and go straight to
+the exit marker.
+
+By the way, =C-d= will only clear the field if you cursor is at the
+beginning of the field /and/ it hasn't been changed yet. Otherwise, it
+performs the normal Emacs =delete-char= command.
+
+** Customizable variables
+
+*** =yas-trigger-key=
+
+The key bound to =yas-expand= when function =yas-minor-mode= is active.
+
+Value is a string that is converted to the internal Emacs key
+
+Default value is ="TAB"=.
+
+*** =yas-next-field-key=
+
+The key to navigate to next field when a snippet is active.
+
+Value is a string that is converted to the internal Emacs key
+
+Can also be a list of keys.
+
+Default value is ="TAB"=.
+
+*** =yas-prev-field-key=
+
+The key to navigate to previous field when a snippet is active.
+
+Value is a string that is converted to the internal Emacs key
+
+Can also be a list of keys.
+
+Default value is =("<backtab>" "<S-tab>)"=.
+
+*** =yas-skip-and-clear-key=
+
+The key to clear the currently active field.
+
+Value is a string that is converted to the internal Emacs key
+
+Can also be a list of keys.
+
+Default value is ="C-d"=.
+
+*** =yas-good-grace=
+
+If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
+snippet definitions. An error string "[yas] error" is returned instead.
+
+*** =yas-indent-line=
+
+The variable =yas-indent-line= controls the indenting. It is bound to
+='auto= by default, which causes your snippet to be indented according
+to the mode of the buffer it was inserted in.
+
+Another variable =yas-also-auto-indent-first-line=, when non-nil does
+exactly that :-).
+
+To use the hard-coded indentation in your snippet template, set this
+variable to =fixed=.
+
+=# expand-env:= in [[snippet-development.html][Writing Snippets]].
+
+For backward compatibility with earlier versions of YASnippet, you can
+also place a =\$>= in your snippet, an =(indent-according-to-mode)= will
+be executed there to indent the line. This only takes effect when
+=yas-indent-line= is set to something other than ='auto=.
+
+*** =yas-wrap-around-region=
+
+If non-nil, YASnippet will try to expand the snippet's exit marker
+around the currently selected region. When this variable is set to t,
+this has the same effect has using the =yas-selected-text= inline
+evaluation.
+
+Because on most systems starting to type deletes the currently selected
+region, this works mostly for snippets with direct keybindings or with
+the =yas-insert-snippet= command.
+
+However, when the value is of this variable is =cua= YASnippet will
+additionally look-up any recently selected that you deleted by starting
+typing. This allows you select a region, type a snippet key (deleting
+the region), then press =yas-trigger-key= to see the deleted region
+spring back to life inside your new snippet.
+
+*** =yas-triggers-in-field=
+
+If non-nil, =yas-next-field-key= can trigger stacked expansions, that is
+a snippet expansion inside another snippet expansion. Otherwise,
+=yas-next-field-key= just tries to move on to the next field.
+
+*** =yas-snippet-revival=
+
+Non-nil means re-activate snippet fields after undo/redo.
+
+*** =yas-after-exit-snippet-hook= and =yas-before-expand-snippet-hook=
+
+These hooks are called, respectively, before the insertion of a snippet
+and after exiting the snippet. If you find any strange but functional
+use for them, that's probably a design flaw in YASnippet, so let us
+know.
+
+** Importing TextMate snippets
+
+There are a couple of tools that take TextMate's ".tmSnippet" xml files
+and create YASnippet definitions:
+
+#+BEGIN_QUOTE
+
+  -
[[http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py][a
+     python script by Jeff Wheeler]]
+
+  -  a
+
+     tool]] , =textmate_import.rb= adapted from
+     [[http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/][Rob
+     Christie's]], which I have uploaded to the repository.
+
+#+END_QUOTE
+
+In this section, i'll shortly cover the *second* option.
+
+interested in.
+
+Then invoke =textmate_import.rb= like this:
+
+You should end up with a =html-mode= subdir containing snippets exported
+from textmate.
+
+The =-g= is optional but helps the tool figure out the grouping.
+According to [[snippet-organization.html][Organizing Snippets]], don't
+forget to touch =.yas-make-groups= and =.yas-ignore-filename-triggers=
+inside the =html-mode= dir.
+
+Also try =textmate_import.rb --help= for a list of options.
+
+Please note that snippet importation is not yet perfect. You'll probably
+=textmate_import.rb= to automatically perform them and submit that.
diff --git a/doc/snippet-expansion.org b/doc/snippet-expansion.org
new file mode 100644
index 0000000..75efe86
--- /dev/null
+++ b/doc/snippet-expansion.org
@@ -0,0 +1,333 @@
+* Expanding snippets
+
+** Triggering expansion
+
+You can use YASnippet to expand snippets in different ways:
+
+-  By typing an abbrev, the snippet /trigger key/, and then pressing the
+   key defined in =yas-trigger-key= (which defaults to "TAB"). This
+   works in buffers where the minor mode =yas-minor-mode= is active;
+
+-  By invoking the command =yas-insert-snippet= (either by typing
+   =M-x yas-insert-snippet= or its keybinding). This does /not/ require
+   =yas-minor-mode= to be active.
+
+-  By using the keybinding associated with an active snippet. This also
+   requires =yas-minor-mode= to be active;
+
+
+-  By using hippie-expand
+
+-  Expanding from emacs-lisp code
+
+*** Trigger key
+
+When =yas-minor-mode= is enabled, the keybinding taken from
+=yas-trigger-key= will take effect.
+
+=yas-trigger-key= invokes =yas-expand=, which tries to expand a /snippet
+abbrev/ (also known as /snippet key/) before point.
+
+The default key is ="TAB"=, however, you can freely set it to some other
+key.
+
+[[images/minor-mode-indicator.png]]
+
+To enable the YASnippet minor mode in all buffers globally use the
+command =yas-global-mode=.
+
+When you use =yas-global-mode= you can also selectively disable
+YASnippet in some buffers by setting the buffer-local variable
+=yas-dont-active= in the buffer's mode hook.
+
+Trouble when using or understanding the =yas-trigger-key= is easily the
+most controversial issue in YASsnippet. See the [[faq.html][FAQ]].
+
+**** Fallback bahaviour
+
+=yas-fallback-behaviour= is a customization variable bound to
+='call-other-command= by default. If =yas-expand= failed to find any
+suitable snippet to expand, it will disable the minor mode temporarily
+and find if there's any other command bound the =yas-trigger-key=.
+
+If found, the command will be called. Usually this works very well
+--when there's a snippet, expand it, otherwise, call whatever command
+originally bind to the trigger key.
+
+However, you can change this behavior by customizing the
+=yas-fallback-behavior= variable. If you set this variable to
+='return-nil=, it will return =nil= instead of trying to call the
+/original/ command when no snippet is found.
+
+*** Insert at point
+
+The command =M-x yas-insert-snippet= lets you insert snippets at point
+/for you current major mode/. It prompts you for the snippet key first,
+and then for a snippet template if more than one template exists for the
+same key.
+
+The list presented contains the snippets that can be inserted at point,
+according to the condition system. If you want to see all applicable
+snippets for the major mode, prefix this command with =C-u=.
+
+The prompting methods used are again controlled by
+=yas-prompt-functions=.
+
+*** Snippet keybinding
+
+See the section of the =# binding:= directive in
+[[snippet-development.html][Writing Snippets]].
+
+
+
+*** Expanding with =hippie-expand=
+
+To integrate with =hippie-expand=, just put =yas-hippie-try-expand= in
+=hippie-expand-try-functions-list=. This probably makes more sense when
+placed at the top of the list, but it can be put anywhere you prefer.
+
+*** Expanding from emacs-lisp code
+
+Sometimes you might want to expand a snippet directly from you own elisp
+code. You should call =yas-expand-snippet= instead of =yas-expand= in
+this case.
+
+As with expanding from the menubar, the condition system and multiple
+candidates doesn't affect expansion. In fact, expanding from the
+
+See the internal documentation on =yas-expand-snippet= for more
+information.
+
+** Controlling expansion
+
+*** Eligible snippets
+
+YASnippet does quite a bit of filtering to find out which snippets are
+eligible for expanding at the current cursor position.
+
+In particular, the following things matter:
+
+
+   These are loaded from a directory hierarchy in your file system. See
+   [[snippet-organization.html][Organizing Snippets]]. They are named
+   after major modes like =html-mode=, =ruby-mode=, etc...
+
+-  Major mode of the current buffer
+
+   If the currrent major mode matches one of the loaded snippet tables,
+   then all that table's snippets are considered for expansion. Use
+   =M-x describe-variable RET major-mode RET= to find out which major
+   mode you are in currently.
+
+-  Parent tables
+
+   Snippet tables defined as the parent of some other eligible table are
+   also considered. This works recursively, i.e. parents of parents of
+   eligible tables are also considered.
+
+-  Buffer-local =yas-mode-symbol= variable
+
+   This can be used to consider snippet tables whose name does not
+   correspond to a major mode. If you set this variable to a name , like
+   =rinari-minor-mode=, you can have some snippets expand only in that
+   minor mode. Naturally, you want to set this conditionally, i.e. only
+   when entering that minor mode, so using a hook is a good idea.
+
+-  Buffer-local =yas-buffer-local-condition= variable
+
+   This variable provides finer grained control over what snippets can
+   be expanded in the current buffer. The default value won't let you
+   expand snippets inside comments or string literals for example. See
+
+*** The condition system
+
+Consider this scenario: you are an old Emacs hacker. You like the
+abbrev-way and set =yas-trigger-key= to ="SPC"=. However, you don't want
+=if= to be expanded as a snippet when you are typing in a comment block
+or a string (e.g. in =python-mode=).
+
+If you use the =# condition := directive (see
+[[snippet-development.html][Writing Snippets]]) you could just specify
+the condition for =if= to be =(not (python-in-string/comment))=. But how
+about =while=, =for=, etc. ? Writing the same condition for all the
+snippets is just boring. So has a buffer local variable
+=yas-buffer-local-condition=. You can set this variable to
+=(not (python-in-string/comment))= in =python-mode-hook=.
+
+Then, what if you really want some particular snippet to expand even
+inside a comment? This is also possible! But let's stop telling the
+story and look at the rules:
+
+-  If =yas-buffer-local-condition= evaluate to nil, no snippets will be
+   considered for expansion.
+
+-  If it evaluates to the a /cons cell/ where the =car= is the symbol
+   =require-snippet-condition= and the =cdr= is a symbol (let's call it
+   =requirement=), then:
+
+   -  Snippets having no =# condition:= directive won't be considered;
+
+   -  Snippets with conditions that evaluate to nil (or produce an
+      error) won't be considered;
+
+   -  If the snippet has a condition that evaluates to non-nil (let's
+      call it =result=):
+
+      -  If =requirement= is =t=, the snippet is ready to be expanded;
+
+      -  If =requirement= is =eq= to =result=, the snippet is ready to
+         be expanded;
+
+      -  Otherwise the snippet won't be considered.
+
+-  If it evaluates to the symbol =always=, all snippets are considered
+   for expansion, regardless of any conditions.
+
+-  If it evaluate to =t= or some other non-nil value:
+
+   -  If the snippet has no condition, or has a condition that evaluate
+      to non-nil, it is ready to be expanded.
+
+   -  Otherwise, it won't be considered.
+
+In the mentioned scenario, set =yas-buffer-local-condition= like this
+
+... and specify the condition for a snippet that you're going to expand
+in comment to be evaluated to the symbol =force-in-comment=. Then it can
+be expanded as you expected, while other snippets like =if= still can't
+expanded in comment.
+
+*** Multiples snippet with the same key
+
+The rules outlined [[Eligible%20snippets][above]] can return more than
+one snippet to be expanded at point.
+
+When there are multiple candidates, YASnippet will let you select one.
+The UI for selecting multiple candidate can be customized through
+=yas-prompt-functions= , which defines your preferred methods of being
+prompted for snippets.
+
+You can customize it with
+=M-x customize-variable RET yas-prompt-functions RET=. Alternatively you
+
+Currently there are some alternatives solution with YASnippet.
+
+
+**** Use the X window system
+
+The function =yas-x-prompt= can be used to show a popup menu for you to
+select. This menu will be part of you native window system widget, which
+means:
+
+-  It usually looks beautiful. E.g. when you compile Emacs with gtk
+-  Your window system may or may not allow to you use =C-n=, =C-p= to
+-  This function can't be used when in a terminal.
+
+
+**** Minibuffer prompting
+
+You can use functions =yas-completing-prompt= for the classic emacs
+completion method or =yas-ido-prompt= for a much nicer looking method.
+The best way is to try it. This works in a terminal.
+
+
+
+The function =yas-dropdown-prompt= can also be placed in the
+=yas-prompt-functions= list.
+
+This works in both window system and terminal and is customizable, you
+can use =C-n=, =C-p= to navigate, =q= to quit and even press =6= as a
+shortcut to select the 6th candidate.
+
+
+See below for the documentation on variable =yas-prompt-functions=
+
+** Customizable Variables
+
+*** =yas-prompt-functions=
+
+You can write a function and add it to the =yas-prompt-functions= list.
+These functions are called with the following arguments:
+
+-  PROMPT: A string to prompt the user;
+
+-  CHOICES: A list of strings or objects;
+
+-  optional DISPLAY-FN : A function. When applied to each of the objects
+   in CHOICES it will return a string;
+
+The return value of any function you put here should be one of the
+objects in CHOICES, properly formatted with DISPLAY-FN (if that is
+passed).
+
+-  To signal that your particular style of prompting is unavailable at
+   the moment, you can also have the function return nil.
+
+-  To signal that the user quit the prompting process, you can signal
+   =quit= with =(signal 'quit "user quit!")=
+
+*** =yas-fallback-behavior=
+
+How to act when =yas-expand= does /not/ expand a snippet.
+
+-  =call-other-command= means try to temporarily disable YASnippet
+   and :: call the next command bound to =yas-trigger-key=.
+
+=return-nil= means return nil. (i.e. do nothing)
+
+An entry (apply COMMAND . ARGS) means interactively call COMMAND, if
+ARGS is non-nil, call COMMAND non-interactively with ARGS as arguments.
+
+*** =yas-choose-keys-first=
+
+If non-nil, prompt for snippet key first, then for template.
+
+Otherwise prompts for all possible snippet names.
+
+This affects =yas-insert-snippet= and =yas-visit-snippet-file=.
+
+*** =yas-choose-tables-first=
+
+If non-nil, and multiple eligible snippet tables, prompts user for
+tables first.
+
+Otherwise, user chooses between the merging together of all eligible
+tables.
+
+This affects =yas-insert-snippet=, =yas-visit-snippet-file=
+
+*** =yas-key-syntaxes=
+
+The default searching strategy is quite powerful. For example, in
+=c-mode=, =bar=, =foo_bar=, ="#foo_bar"= can all be recognized as a
+snippet key. Furthermore, the searching is in that order. In other
+words, if =bar= is found to be a key to some /valid/ snippet, then that
+snippet is expanded and replaces the =bar=. Snippets pointed to by
+=foo_bar= and ="#foobar= won't be considered.
+
+However, this strategy can also be customized easily from the
+=yas-key-syntaxes= variable. It is a list of syntax rules, the default
+value is =("w" "w_" "w_." "^ ")=. Which means search the following thing
+until found one:
+
+-  a word.
+-  a symbol. In lisp, =-= and =?= can all be part of a symbol.
+-  a sequence of characters of either word, symbol or punctuation.
+-  a sequence of characters of non-whitespace characters.
+
+But you'd better keep the default value unless you want to understand
+how Emacs's syntax rules work...
new file mode 100644
index 0000000..cf5dec5
--- /dev/null
@@ -0,0 +1,67 @@
+
+When =yas-minor-mode= is active, YASnippet will setup a menu just after
+
+In this menu, you can find
+
+-  The currently loaded snippet definitions, organized by major mode,
+   and optional grouping.
+
+-  A rundown of the most common commands, (followed by their
+   snippet definitions.
+
+-  A series of submenus for customizing and exploring YASnippet
+   behavior.
+
+
+
+and prompts you for a snippet directory hierarchy to load.
+
+the snippets directories defined in =yas-root-directory= and rebuilds
+
+
+YASnippet will list in this section all the loaded snippet definitions
+organized by snippet table name.
+
+You can use this section to explore currently loaded snippets. If you
+click on one of them, the default behavior is to expand it,
+unconditionally, inside the current buffer.
+
+You can however, customize variable =yas-visit-from-menu= to be =t=
+which will take you to the snippet definition file when you select it
+
+If you want the menu show only snippet tables whose name corresponds to
+a "real" major mode. You do this by setting =yas-use-menu= to
+='real-modes=.
+
+Finally, to have the menu show only the tables for the currently active
+
+These customizations can also be found in the menu itself, under the
+
+** Controlling indenting
+
+The "Indenting" submenu contains options to control the values of
+=yas-indent-line= and =yas-also-auto-indent-first-line=. See
+[[snippet-development.html][Writing snippets]] .
+
+** Prompting method
+
+The "Prompting method" submenu contains options to control the value of
+=yas-prompt-functions=. See [[snippet-expansion.html][Expanding
+snippets]] .
+
+** Misc
+
+The "Misc" submenu contains options to control the values of more
+variables.
diff --git a/doc/snippet-organization.org b/doc/snippet-organization.org
new file mode 100644
index 0000000..9ca14c0
--- /dev/null
+++ b/doc/snippet-organization.org
@@ -0,0 +1,107 @@
+* Organizing snippets
+
+
+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
+
+Once these directories are in place reference them in the variable
+
+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
+
+
+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
+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
+
+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
+
+*** =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.
diff --git a/doc/yas-doc-helper.el b/doc/yas-doc-helper.el
index 39c9716..4300597 100755
--- a/doc/yas-doc-helper.el
+++ b/doc/yas-doc-helper.el
@@ -92,6 +92,21 @@

+;; This lets all the org files be exported to HTML with
+;; org-publish-current-project' (C-c C-e P).
+(progn
+  (defvar yas--document-org-project-plist
+    (:style
+      :base-directory ,default-directory
+      :publishing-directory ,default-directory))
+
+  (let ((project (assoc "yasnippet" org-publish-project-alist)))
+    (if project
+        (setcdr project yas--document-org-project-plist)
+      (push ("yasnippet" . ,yas--document-org-project-plist)
+            org-publish-project-alist))))
+
(provide 'yas-doc-helper)
;;; yas-doc-helper.el ends here
;; Local Variables: