improves the documentation

doc/neosnippet.txt

@@ -41,9 +41,9 @@ Changelog		|neosnippet-changelog|
 INTRODUCTION					*neosnippet-introduction*
 
 This plugin analyzes snippet files which you can use for completion. It offers
-functionality similar to |snipMate.vim| or |snippetsEmu.vim|. Since you can
+functionality similar to snipMate.vim or snippetsEmu.vim. Since you can choose
-choose snippets with the neocomplcache interface, you might have less trouble
+snippets with the neocomplcache interface, you might have less trouble using
-using them, because you do not have to remember each snippet name.
+them, because you do not have to remember each snippet name.
 
 ==============================================================================
 INSTALL						*neosnippet-install*
@@ -126,15 +126,20 @@ VARIABLES 					*neosnippet-variables*
 
 g:neosnippet#snippets_directory		*g:neosnippet#snippets_directory*
 		This variable appoints a path to user-defined snippet files.
-		You can set multiple values in comma-separated form.
+		You can set multiple values in comma-separated form. Non existing 
-		If the directory doesn't exist, it is ignored.
+		directories are ignored.
 
-		User defined snippets are read after built-in snippet files,
+		User defined snippet files are read after the built-in snippet files.
-		and redundant snippets get overwritten.
+		If redundant snippets occur they get overwritten and only the last 
+		one remains.
 		
-		Note: Neosnippet loads the file type snippet files as follows. 
+		Note: The neosnippet plug-in loads file type snippets from several 
-		If you edit "vim" file types files, neosnippet loads
+		files if available. For example if you edit a "Vim" file then it loads the 
-		"vim.snip*", "vim_*.snip*" and "vim/**/*.snip" snippet files.
+		snippets from:
+
+		- "vim.snip*"
+		- "vim_*.snip*" 
+	        - "vim/**/*.snip" 
 
 						*g:neocomplcache_snippets_dir*
 		Note: |g:neocomplcache_snippets_dir| is an obsolete name.
@@ -143,10 +148,10 @@ g:neosnippet#snippets_directory		*g:neosnippet#snippets_directory*
 
 g:neosnippet#disable_select_mode_mappings
 				*g:neosnippet#disable_select_mode_mappings*
-		This variable disables key-mappings in |Select-mode| where 
+		This variable disables key-mappings in |Select-mode| where the 
 		snippets_complete performs the snippet completion. Usually it
 		it better to leave it as it is. But if you have troubles with 
-		the buffer switcher LustyJuggler it helps to disable them.
+		the buffer switcher LustyJuggler you can switch them of.
 		
 				*g:neocomplcache_disable_select_mode_mappings*
 		Note: |g:neocomplcache_disable_select_mode_mappings| is an
@@ -156,13 +161,13 @@ g:neosnippet#disable_select_mode_mappings
 
 g:neosnippet#disable_runtime_snippets
 				*g:neosnippet#disable_runtime_snippets*
-		This is a dictionary variable which uses the file type as key.
+		This is a dictionary variable which uses file types as key.
-		To set the value of a file type entry to 1 prevents loading all
+		If you set the value of a file type entry to 1, this prevents 
-		built-in snippets for that file type. This is very useful to 
+		loading all the file type specific built-in snippets. This is 
-		prevent snippet conflicts between self defined snippet files 
+		very useful to to prevent snippet conflicts between self defined 
-		and the built-in snippet files of neosnippet. If you use "_" as 
+		snippet files and the built-in snippet files of neosnippet. 
-		key for an entry, this will be treated as default for all
+		If you use a "_" as key for an entry this will treat the value of 
-		file types.
+		the entry as default value for all file types.
 
 		Note: This dictionary must be set in your .vimrc.
 
@@ -191,8 +196,8 @@ KEY MAPPINGS 					*neosnippet-key-mappings*
 					*<Plug>(neosnippet_expand_or_jump)*
 s_<Plug>(neosnippet_expand_or_jump)
 					*s_<Plug>(neosnippet_expand_or_jump)*
-		Expands a cursor snippet of plural lines. When there is no
+		Expand a snippet in the current cursor position. If there is no snippet 
-		snippet, it jumps to the next placeholder.
+		available it jumps to the next placeholder of the buffer.
 
 				*<Plug>(neocomplcache_snippets_expand)*
 		Note: |<Plug>(neocomplcache_snippets_expand)| is an obsolete
@@ -202,8 +207,8 @@ s_<Plug>(neosnippet_expand_or_jump)
 				*<Plug>(neosnippet_jump_or_expand)*
 s_<Plug>(neosnippet_jump_or_expand)
 				*s_<Plug>(neosnippet_jump_or_expand)*
-		Jump to the next placeholder. If there is no placeholder, it expands a
+		Jump to the next available placeholder in the buffer. If there is no 
-		multi line cursor snippet.
+		placeholder it expands a snippet in the current cursor position. 
 
 				*<Plug>(neocomplcache_snippets_jump)*
 		Note: |<Plug>(neocomplcache_snippets_jump)| is an obsolete
@@ -213,7 +218,9 @@ s_<Plug>(neosnippet_jump_or_expand)
 						*<Plug>(neosnippet_expand)*
 s_<Plug>(neosnippet_expand)
 						*s_<Plug>(neosnippet_expand)*
-		Expand a cursor snippet. It does nothing if there is no snippet.
+		Expand a snippet in current cursor position. It only takes effect 
+		if there is a snippet text to expand or if you have chosen one from
+	        the neocomplcache drop down menu.
 
 				*<Plug>(neocomplcache_snippets_force_expand)*
 		Note: |<Plug>(neocomplcache_snippets_force_expand)| is
@@ -223,8 +230,7 @@ s_<Plug>(neosnippet_expand)
 						*<Plug>(neosnippet_jump)*
 s_<Plug>(neosnippet_jump)
 						*s_<Plug>(neosnippet_jump)*
-		Jump to the next place holder. Do not expand any snippet. When
+		Jump to the next placeholder key. It does not expand any snippets.
-		you do not want to expand a snippet name, use this key mapping.
 
 				*<Plug>(neocomplcache_snippets_force_jump)*
 		Note: |<Plug>(neocomplcache_snippets_force_jump)| is
@@ -233,8 +239,8 @@ s_<Plug>(neosnippet_jump)
 i_<Plug>(neosnippet_start_unite_snippet)
 				*i_<Plug>(neosnippet_start_unite_snippet)*
 		Starts the unite snippet source. You can expand a snippet by the 
-		unite interface. Note: The plugin |unite.vim| is required for
+		unite interface. Note: The plug-in |unite.vim| is required for
-		that.
+		that feature.
 
 				*<Plug>(neocomplcache_start_unite_snippet)*
 		Note: |<Plug>(neocomplcache_start_unite_snippet)| is an obsolete
@@ -318,7 +324,8 @@ EXAMPLES					*neosnippet-examples*
 ==============================================================================
 SNIPPET SYNTAX					*neosnippet-snippet-syntax*
 
-The snippet syntax is similar to |snipMate|.
+The neosnippet snippet syntax is quite similar to the snippet syntax 
+of |snipMate|.
 
 Example:
 >
@@ -329,41 +336,53 @@ Example:
 	        ${2}
 	    endif
 <
-snippet {snippet_name} syntax is the snippet name.
-abbr {abbr_name} is the completion abbrevation (same to completion "abbr"
-key).
 
-By the way, it is warned that the snippet name was already defined by other
+The example above displays the structure of the syntax. Each snippet starts with
-snippet file.  If you want to overwrite it explicitly, please use:
+the keyword "snippet" which is directly followed by the snippet name. After
+that you can define an abbreviation which will be used for the drop down menu
+of neocomplcache. The options line restricts the environment the snippet gets
+expanded. In this case it is restricted to the head of the line.
+
+Note: If a snippets is defined multiple times in different snippet files,
+neosnippet produces a warning. If you want to overwrite a snippet explicitly,
+please use:
+
 >
 	delete snippets_name
 <
-and redefine the snippet.
 
-When including external files or other snippet file's snippets are overwrited,
+After that you can redefine the snippet. But this does not work if you include
-you will not be warned.
+other files or external snippet files. If you include external snippet file's
+there will be no warning when snippets of those files get overwritten.
 
 Snippet include feature is available.
+
 >
 	include c.snip
 <
+
 If you want to include a whole filetype directory snippets.
+
 >
 	include javascript/*
 <
 
 Eval snippet feature is available.
+
 >
 	snippet     hoge
 	options     head
 	    `expand("%")`
 <
+
 Note: You want to use backticks in snippet, you must escape backticks.
+
 >
 	snippet code
 	abbr code
 	    \`${1}\`${2}
 <
+
 If you use |:NeoSnippetEdit| command for easy snippet editing, the file will
 be loaded automatically when you save the file.
 
@@ -540,7 +559,6 @@ CHANGELOG			*neosnippet-changelog*
 - Added indent option.
 - Added <Plug>(neosnippet_register_oneshot_snippet).
 - Refactored snippets files.
-- Fixed indentation.
 
 2012-10-29
 - Improved parse of snippets file.