[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] master f5457df 031/177: Go back to org manual
From: |
João Távora |
Subject: |
[elpa] master f5457df 031/177: Go back to org manual |
Date: |
Sat, 28 Mar 2015 15:40:37 +0000 |
branch: master
commit f5457dfa334b445e72d2c218dd7da971985c937d
Author: Noam Postavsky <address@hidden>
Commit: Noam Postavsky <address@hidden>
Go back to org manual
---
doc/manual.mdown | 257 ----------------------------------------------------
doc/manual.org | 266 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 266 insertions(+), 257 deletions(-)
diff --git a/doc/manual.mdown b/doc/manual.mdown
deleted file mode 100644
index b2ac779..0000000
--- a/doc/manual.mdown
+++ /dev/null
@@ -1,257 +0,0 @@
-Quick start
-===========
-
-*YASnippet* is a template system for Emacs. It allows you to type an
-abbreviation and automatically expand it into function templates. Bundled
-language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML,
-CSS and more. The snippet syntax is inspired from TextMate's syntax, you can
-even [import most TextMate snippets](#import-textmate)
-
-YASnippet is an original creation of [pluskid][pluskid] who also wrote its
predecessor
-[smart-snippet][smart-snippet].
-
-Watch a demo
-------------
-
-Do so on [youtube][youtube]
-
-Installation
-------------
-
-Clone this repository somewhere
-
- $ cd ~/.emacs.d/plugins
- $ git clone https://github.com/capitaomorte/yasnippet
-
-Add the following in your =.emacs= file:
-
- (add-to-list 'load-path
- "~/.emacs.d/plugins/yasnippet")
- (require 'yasnippet)
- (yas/global-mode 1)
-
-Add your own snippets to `~/.emacs.d/snippets` by placing files there or
-invoking `yas-new-snippet`.
-
-Import textmate snippets (rails example)
-----------------------------------------
-
-YASnippet lets you use TextMate bundles directly:
-
- $ cd ~/.emacs.d/plugins
- $ git clone https://github.com/capitaomorte/yasnippet
- $ cd yasnippet
- $ git submodule init
- $ git submodule update
- $ gem install plist trollop
- $ rake convert_bundles # will convert ruby, rails and html
bundles from drnic
-
-Then, in your `.emacs` file
-
-
- (add-to-list 'load-path
- "~/.emacs.d/plugins/yasnippet")
- (require 'yasnippet)
- (setq yas/snippet-dirs '("~/.emacs.d/snippets"
"~/.emacs.d/extras/imported"))
- (yas/global-mode 1)
-
-Open some rails file (model, app, etc) and start using the textmate
-snippets. Consider that this is a work-in-progress and many snippets/commands
-might not work. Patches welcome!
-
-Contributing snippets
----------------------
-
-Please *do not ask me* to add snippets to the default collection under
-`/snippets`. This collection is considered frozen. By customizing
-`yas-snippet-dirs` you can point yasnippet to good snippet collections out
-there.
-
-The `extras/textmate-import.rb` tool can import many actual Textmate snippets.
-I'm focusing on developing it and the accompanying `yas-setup.el` files that
-guide it with more difficult importations. The idea is to deprecate `/snippets=
-and replace it with =extras/imported`.
-
-Documentation, issues, etc
---------------------------
-
-Please refer to the comprehensive [documentation](docs) for full
-customization and support. If you think you've found a bug, please report it
-on [the GitHub issue tracker](issues). (please **do not** submit new
-issues to the old [googlecode tracker](googlecode-tracker))
-
-If you run into problems using YASnippet, or have snippets to contribute,
-post to the [yasnippet forum](forum). Thank you very much for using
-YASnippet!
-
-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 names.
-
- .
- |-- c-mode
- | `-- printf
- |-- java-mode
- | `-- println
- `-- text-mode
- |-- email
- `-- time
-
-The collections are loaded into *snippet tables* which the triggering
-mechanism (see [Expanding snippets](#expand-snippets)) looks up and
-(hopefully) cause the right snippet to be expanded for you.
-
-Setting up `yas-snippet-dirs`
------------------------------
-
-The emacs variable `yas-snippet-dirs` tells YASnippet
-which collections to consider. It's used when you activate
-`yas-global-mode` or call
-`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` localtion
-
-When you come across other snippet collections, do the following to try them
-out:
-
-;; 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's defaults try out ~/Downloads/interesting-snippets
-(setq yas/snippet-dirs (append yas/snippet-dirs
- '("~/Downloads/interesting-snippets")))
-
-Collections appearing earlier in the list shadow snippets with same names
-appearing in collections later in the list. `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.
-
- .
- |-- 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
-
-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 [the menu](snippet-menu) is organized much more cleanly:
-
-(TODO image)
-
-Another alternative way to achieve this is to place a `# group:` directive
-inside the snippet definition. See [Writing Snippets](#writing-snippets)
-
-
- $ tree ruby-mode/
- ruby-mode/
- |-- .yas-make-groups
- |-- collections
- | |-- each
- | `-- ...
- |-- control structure
- | |-- forin
- | `-- ...
- |-- definitions
- | `-- ...
- `-- general
- `-- ...
-
-
-Yet another way to create a nice snippet menu is to write into
-`.yas-make-groups` a menu definition. TODO
-
-TODO The `.yas-setup.el` file
------------------------------
-
-*** TODO
-
-TODO The `.yas-compiled-snippet.el` file
-----------------------------------------
-
-*** TODO
-
-The `.yas-skip` file
---------------------
-
-Expanding Snippets
-==================
-
-This section 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
-
-Triggering expansion
---------------------
-
-To make a snippet expand after the cursor:
-
-* Type an the snippet's *trigger key* then press the key defined in
- `yas-trigger-key`.
-
-* Use the snippet's *keybinding*.
-
-* Call [`yas-insert-snippet=](#yas-insert-snippet) (use `M-x
- yas-insert-snippet`= or its keybinding =C-c & C-s`).
-
-* By expanding directly from the "YASnippet" menu in the menu-bar
-
-* Using hippie-expand
-
-* Use m2m's excellent [auto-complete](http://github.com/m2m/autocomplete)
-
-Reference
-=========
-
- (yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
- `("Customization variables" . ,#'(lambda (sym)
- (and (boundp
sym)
- (get sym
'standard-value))))
- `("Useful functions" . ,#'fboundp)
- `("Useful variables" . ,#'boundp))
-
-[smart-snippet]: http://code.google.com/p/smart-snippet
-[pluskid]: http://pluskid.lifegoo.org
-[screencast]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
-[docs]: http://capitaomorte.github.com/yasnippet
-[issues]: https://github.com/capitaomorte/yasnippet/issues
-[googlecode-tracker]: http://code.google.com/p/yasnippet/issues/list
-[forum]: http://groups.google.com/group/smart-snippet
-
-
-
-<!--
- !-- Local Variables:
- !-- mode: markdown
- !-- fill-column: 80
- !-- coding: utf-8
- !-- End:
- !-- -->
diff --git a/doc/manual.org b/doc/manual.org
new file mode 100644
index 0000000..8c247c6
--- /dev/null
+++ b/doc/manual.org
@@ -0,0 +1,266 @@
+#+TITLE: Yet another snippet extension
+#+OPTIONS: toc:1
+#+STARTUP: showall
+
+#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheets/styles.css"
/>
+
+# External links
+#
+#+LINK: smart-snippet http://code.google.com/p/smart-snippet
+#+LINK: pluskid http://pluskid.lifegoo.org
+
+#+LINK: screencast http://www.youtube.com/watch?v=ZCGmZK4V7Sg
+#+LINK: docs http://capitaomorte.github.com/yasnippet
+#+LINK: issues https://github.com/capitaomorte/yasnippet/issues
+#+LINK: googlecode-tracker http://code.google.com/p/yasnippet/issues/list
+#+LINK: forum http://groups.google.com/group/smart-snippet
+
+
+* Quick start
+
+ *YASnippet* is a template system for Emacs. It allows you to type an
+ abbreviation and automatically expand it into function templates. Bundled
+ language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX,
HTML,
+ CSS and more. The snippet syntax is inspired from TextMate's syntax, you can
+ even [[#import-textmate][import most TextMate snippets]]
+
+ YASnippet is an original creation of [[pluskid]] who also wrote its
predecessor
+ [[smart-snippet]].
+
+** Watch a demo
+
+ [[youtube]]
+
+** Installation
+
+ Clone this repository somewhere
+
+ #+begin_example
+ $ cd ~/.emacs.d/plugins
+ $ git clone https://github.com/capitaomorte/yasnippet
+ #+end_example
+
+ Add the following in your =.emacs= file:
+
+ #+begin_src emacs-lisp :exports code
+ (add-to-list 'load-path
+ "~/.emacs.d/plugins/yasnippet")
+ (require 'yasnippet)
+ (yas/global-mode 1)
+ #+end_src
+
+ Add your own snippets to =~/.emacs.d/snippets= by placing files there or
+ invoking [[#yas-new-snippet][=yas-new-snippet=]].
+
+** Import textmate snippets (rails example)
+ :PROPERTIES:
+ :CUSTOM_ID: import-textmate
+ :END:
+
+ YASnippet lets you use TextMate bundles directly:
+
+ #+begin_example
+ $ cd ~/.emacs.d/plugins
+ $ git clone https://github.com/capitaomorte/yasnippet
+ $ cd yasnippet
+ $ git submodule init
+ $ git submodule update
+ $ gem install plist trollop
+ $ rake convert_bundles # will convert ruby, rails and html
bundles from drnic
+ #+end_example
+
+ Then, in your =.emacs= file
+
+ #+begin_example
+ (add-to-list 'load-path
+ "~/.emacs.d/plugins/yasnippet")
+ (require 'yasnippet)
+ (setq yas/snippet-dirs '("~/.emacs.d/snippets"
"~/.emacs.d/extras/imported"))
+ (yas/global-mode 1)
+ #+end_example
+
+ Open some rails file (model, app, etc) and start using the textmate
+ snippets. Consider that this is a work-in-progress and many
snippets/commands
+ might not work. Patches welcome!
+
+** Contributing snippets
+
+ Please *do not ask me* to add snippets to the default collection under
+ =/snippets=. This collection is considered frozen. By customizing
+ [[#yas-snippet-dirs][=yas-snippet-dirs=]] you can point yasnippet to good
+ snippet collections out there.
+
+ The =extras/textmate-import.rb= tool can import many actual Textmate
+ snippets. I'm focusing on developing it and the accompanying =yas-setup.el=
+ files that guide it with more difficult importations. The idea is to
deprecate
+ =/snippets= and replace it with =extras/imported=.
+
+** Documentation, issues, etc
+
+ Please refer to the comprehensive [[docs][documentation]] for full
+ customization and support. If you think you've found a bug, please report
it
+ on [[issues][the GitHub issue tracker]]. (please **do not** submit new
+ issues to the old [[googlecode-tracker][googlecode tracker]])
+
+ If you run into problems using YASnippet, or have snippets to contribute,
+ post to the [[forum][yasnippet forum]]. Thank you very much for using
+ YASnippet!
+
+* 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
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 [[#expand-snippets][Expanding snippets]]) looks up and
+ (hopefully) cause the right snippet to be expanded for you.
+
+** Setting up =yas-snippet-dirs=
+
+ The emacs variable [[#yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
+ which collections to consider. It's used when you activate
+ [[#yas-global-mode][=yas-global-mode=]] or call
+ [[#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=
localtion
+
+ 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's 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 shadow snippets with same names
+ appearing in collections later in the list.
[[#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 [[snippet-menu][the menu]] is organized much more cleanly:
+
+ (TODO image)
+
+ Another alternative way to achieve this is to place a =# group:= directive
+ inside the snippet definition. See [[#writing-snippets][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
+
+** TODO The =.yas-setup.el= file
+
+*** TODO
+
+** TODO The =.yas-compiled-snippet.el= file
+
+*** TODO
+
+** The =.yas-skip= file
+
+* Expanding Snippets
+
+ :PROPERTIES:
+ :CUSTOM_ID: expand-snippets
+ :END:
+
+ This section 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
+
+** Triggering expansion
+
+ To make a snippet expand after the cursor:
+
+ * Type an the snippet's *trigger key* then press the key defined in
+ [[#yas-trigger-key][=yas-trigger-key=]] (usually to "TAB").
+
+ * Use the snippet's *keybinding*.
+
+ * Call [[#yas-insert-snippet][=yas-insert-snippet=]] (use =M-x
+ yas-insert-snippet== or its keybinding =C-c & C-s=).
+
+ * By expanding directly from the "YASnippet" menu in the menu-bar
+
+ * Using hippie-expand
+
+ * Use m2m's excellent auto-complete
+
+* Reference
+#+BEGIN_SRC emacs-lisp :exports results :results value raw
+(yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
+ `("Customization variables" . ,#'(lambda (sym)
+ (and (boundp sym)
+ (get sym
'standard-value))))
+ `("Useful functions" . ,#'fboundp)
+ `("Useful variables" . ,#'boundp))
+#+END_SRC
+# Local Variables:
+# mode: org
+# fill-column: 80
+# coding: utf-8
+# End:
- [elpa] master 33dff9a 024/177: let C-c C-c save existing snippets too, (continued)
- [elpa] master 33dff9a 024/177: let C-c C-c save existing snippets too, João Távora, 2015/03/28
- [elpa] master d7b2b89 027/177: widen before deleting regions, João Távora, 2015/03/28
- [elpa] master 84b7e69 025/177: Merge pull request #423 from npostavs/load-snippet-ui, João Távora, 2015/03/28
- [elpa] master 43a484e 028/177: add: external test for issue #404, João Távora, 2015/03/28
- [elpa] master d5d6e45 026/177: Feature: de/activate-extra-mode, João Távora, 2015/03/28
- [elpa] master 6ee3d2e 029/177: Closes #404: merge remote-tracking branch 'npostavs/widen', João Távora, 2015/03/28
- [elpa] master a4a7e5e 032/177: fix typo: .yas.parents -> .yas-parents, João Távora, 2015/03/28
- [elpa] master fdd550a 035/177: Fix screencast link., João Távora, 2015/03/28
- [elpa] master bc4cfbb 033/177: yas/ -> yas-, João Távora, 2015/03/28
- [elpa] master b20f0a4 034/177: fix exporting of doc strings for org manual, João Távora, 2015/03/28
- [elpa] master f5457df 031/177: Go back to org manual,
João Távora <=
- [elpa] master 0f67c07 030/177: Merge pull request #424 from ljos/de/activate-extra-mode, João Távora, 2015/03/28
- [elpa] master 8e8320f 036/177: remove reference to yas-trigger-key, João Távora, 2015/03/28
- [elpa] master 042837d 038/177: Migrate to snippets maintained by the TextMate community, João Távora, 2015/03/28
- [elpa] master 81e26b4 039/177: Merge pull request #431 from ignisf/update-snippet-submodules, João Távora, 2015/03/28
- [elpa] master c7c6516 040/177: don't use link abbreviations, João Távora, 2015/03/28
- [elpa] master d451fef 041/177: rename manual.org to index.org, João Távora, 2015/03/28
- [elpa] master 5acc976 043/177: split symbol reference into separate file, João Távora, 2015/03/28
- [elpa] master fd8423c 045/177: fix links, João Távora, 2015/03/28
- [elpa] master 7b82424 046/177: move index.org subsection into snippet-expansion.org, João Távora, 2015/03/28
- [elpa] master 3002594 037/177: Merge pull request #430 from npostavs/org-doc, João Távora, 2015/03/28