From d5ae1f721a9431005b080e7ec41a7420a081ce89 Mon Sep 17 00:00:00 2001
From: Marc Weber <marco-oweber@gmx.de>
Date: Tue, 4 Mar 2014 09:26:10 +0100
Subject: [PATCH] changes for README from SirVers 32650 (last commit of last
PR)
---
README.md | 109 +++++++++++++++++++++---------------------------------
1 file changed, 43 insertions(+), 66 deletions(-)
diff --git a/README.md b/README.md
index 64733ebcc..fb186b2bf 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,3 @@
-IMPORTANT: comment on: [What about merging with Ultisnip using its engine](https://github.com/garbas/vim-snipmate/issues/114)
-
Snipmate & UltiSnip Snippets
============================
@@ -9,51 +7,48 @@ It is community-maintained and many people have contributed snippet files and
other improvements already.
Contents
-========
+--------
- snippets/*: snippets using snipmate format
- UltiSnips/*: snippets using UltiSnips format
+- `snippets/*`: snippets using snipmate format
+- `UltiSnips/*`: snippets using UltiSnips format
Snippet engines supporting vim-snippets
-========================================
+----------------------------------------
There are different forks of snippet engines which allow the user to insert
snippets by typing the name of a snippet hitting the expansion mapping.
- github.com/garbas/vim-snipmate:
- VimL, snipmate-snippets, engine sometimes behaves strange, supports
- rewriting snippets on the fly (eg adding a second version with folding
- markers)
-
- github.com/MarcWeber/UltiSnips:
- python, snipmate-snippets and UltiSnips-snippets
-
- github.com/SirVer/ultisnips:
- python, UltiSnips-snippets
-
- github.com/Shougo/neosnippet:
- viml, has a compatible mode allowing to reuse most snipmate snippets ?
-
- github.com/drmingdrmer/xptemplate:
- Totally different syntax, does not read snippets contained in this file,
- but it is also very powerful. It does not support vim-snippets (just
- listing it here for completness)
-
- This tries to be a more comprehensive list (which still is incomplete)
- http://vim-wiki.mawercer.de/wiki/topic/text-snippets-skeletons-templates.html
-
-UltiSnips engine has additional features such as "nested snippets".
-
-Which one to use? If you have python give MarcWeber/UltiSnips a try because its
-fast and supports all important features. You can prefer the UltiSnip versions
-of the snippets by setting the "always_use_first_snippet" option to 1.
+- [github.com/SirVer/ultisnips](https://github.com/SirVer/ultisnips):
+ python, supports all snippets in this repo.
+- [github.com/garbas/vim-snipmate](https://github.com/garbas/vim-snipmate):
+ VimL, snipmate-snippets, engine sometimes behaves strange. Supports
+ snippets/*
+- [github.com/Shougo/neosnippet](https://github.com/Shougo/neosnippet.vim):
+ VimL, supports snippets/* with some configuration.
+- [github.com/drmingdrmer/xptemplate](https://github.com/drmingdrmer/xptemplate):
+ Totally different syntax, does not read snippets contained in this file, but
+ it is also very powerful. It does not support vim-snippets (just listing it
+ here for completness)
+
+There tries to be a more comprehensive list (which still is incomplete) here:
+http://vim-wiki.mawercer.de/wiki/topic/text-snippets-skeletons-templates.html
+
+UltiSnips has additional features such as high speed, nesting snippets,
+expanding snippets in snippets and offers powerful transformations on text in
+snippets (like visual selections or placeholder texts).
+
+Which one to use? If you have python give
+[SirVer/ultisnips](https://github.com/SirVer/ultisnips) a try because its fast
+and has the most features.
If you have VimL only (vim without python support) your best option is using
-garbas/vim-snipmate and cope with the minor bugs found in the engine.
+[garbas/vim-snipmate](https://github.com/garbas/vim-snipmate) and cope with the
+minor bugs found in the engine.
Installation
-============
+------------
+
First be aware that there are many options, see "Snippet engines" above.
Second be aware than there are [tons of plugin managers](http://vim-wiki.mawercer.de/wiki/topic/vim%20plugin%20managment.html)
which is why Marc Weber thinks that it doesn't make sense to repeat the same
@@ -84,7 +79,8 @@ If you still have trouble getting this to work create a github ticket, ask on
irc or the mailinglist.
Policies / for contributors
-===========================
+---------------------------
+
Some snippets are useful for almost all languages, so let's try to have the same
triggers for them:
@@ -96,11 +92,7 @@ el : else ..
wh : while (cond) ...
```
-If you're not satisfied with these defaults, open a ticket that we implement
-aliasing. Then you can remap "else" to "el" or the like.
-
-
-Don't add stupid placeholder default texts like
+Don't add useless placeholder default texts like
```
if (${1:condition}){
${2:some code here}
@@ -127,7 +119,7 @@ Discuss at: https://github.com/honza/vim-snippets/issues/230
Related repositories
-====================
+--------------------
We also encourage people to maintain sets of snippets for particular use cases
so that all users can benefit from them. People can list their snippet repositories here:
@@ -138,15 +130,15 @@ so that all users can benefit from them. People can list their snippet reposito
Installation using VAM: "github:rbonvall/snipmate-snippets-bib"
-
Future - ideas - examples
-=========================
+-------------------------
+
[overview snippet engines](http://vim-wiki.mawercer.de/wiki/topic/text-snippets-skeletons-templates.html)
If you have ideas you can add them to that list of "snippet engine features by example".
Historical notes
-================
+----------------
[vim-snipmate][1] was originally started by [Michael Sanders][2] who has now
unfortunately abandoned the project. [Rok Garbas][3] is now maintaining a
@@ -170,14 +162,6 @@ let g:snipMate.scope_aliases = {}
let g:snipMate.scope_aliases['ruby'] = 'ruby,ruby-rails,ruby-1.9'
```
-or github.com/MarcWeber/UltiSnips this way:
-
-
-```vim
-let g:UltiSnips = {}
-
-let g:UltiSnips.snipmate_ft_filter = {
- \ 'default' : {'filetypes': ["FILETYPE"] },
\ 'ruby' : {'filetypes': ["ruby", "ruby-rails", "ruby-1.9"] },
```
@@ -192,16 +176,15 @@ ruby-library-version triplet. Sometimes postfixing a name such as
will do it then if syntax has changed.
+
Language maintainers
--------------------
No one can really be proficient in all programming languages. If you would like
to maintain snippets for a language, please get in touch.
-Notes: People are interested in snippets - and their interest may stop again
-at will. So its ok if people maintain a language only for a short period of
-time - or jump in and get things done - don't let the flow stop :)
-vim-snippets is not like the "linux kernel".
+Notes: People are interested in snippets - and their interest may wane again.
+This list is kept up-to-date on a best effort basis.
* Python - [honza](http://github.com/honza)
* Javascript - [honza](http://github.com/honza)
@@ -220,18 +203,13 @@ Until further work is done on `vim-snipmate`, please don't add folding markers
into snippets. `vim-snipmate` has some comments about how to patch all snippets
on the fly adding those.
-Because MarcWeber/UltiSnips [6] supports also snipmate-snippets there is no
-need to duplicate all snippets - only those snippets who use advanced UltiSnips
-features should be duplicated in UltiSnips (?)
+Because UltiSnips reads snipmate-snippets too there is no need to duplicate all
+snippets - only those snippets who use advanced UltiSnips features should be
+duplicated in UltiSnips.
Currently all snippets from UltiSnips have been put into UltiSnips - some work
on merging should be done (dropping duplicates etc)
-Authors
--------
-
-For a list of authors, please see the `AUTHORS` files.
-
License
-------
@@ -243,5 +221,4 @@ terms of the MIT license.
[2]: http://github.com/msanders
[3]: http://github.com/garbas
[4]: http://github.com/garbas/vim-snipmate
-[6]: http://github.com/MarcWeber/UltiSnips
[7]: http://github.com/SirVer/ultisnips