[elpa] externals/tempel 82d3a4f9d1 4/4: Expand documentation

[ELPA Syncer]

branch: externals/tempel
commit 82d3a4f9d1359807198fe2c27e172f9ad8891f16
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    Expand documentation
---
 README.org | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/README.org b/README.org
index 468e67df25..71ba3c314d 100644
--- a/README.org
+++ b/README.org
@@ -86,8 +86,8 @@ and has to be installed manually with ~package-install-file~.
 
 * Template file format
 
-The template file format is a Lisp file =templates= which is stored by default 
in
-the ~user-emacs-directory~ (=~/.config/emacs/templates=). The templates are 
defined
+The templates are defined in a Lisp file =templates= which is stored by 
default in
+the ~user-emacs-directory~ (=~/.config/emacs/templates=). The templates are 
written
 as Lisp expressions in the concise form of the Emacs Tempo syntax. The first
 element of the list is the name of the template. Behind the name, the Tempo
 syntax elements follow.
@@ -168,6 +168,32 @@ Furthermore Tempel supports syntax extensions:
 
 Use caution with templates which execute arbitrary code!
 
+* Adding template sources
+
+Tempel offers a flexible mechanism for providing the templates which are
+applicable to the current context. The variable ~tempel-template-sources~
+specifies a list of sources or a single source. A source can either be a
+function, which should return a list of applicable templates, or a variable 
name
+symbol of a variable which holds a list of templates, which apply to the 
current
+context. By default Tempel install the sources ~tempel--file-templates~ and the
+variable ~tempel-local-templates~.
+
+* Binding important to a key
+
+Important kemplates can be bound to a key with the small utility macro
+~tempel-key~ which accepts three arguments, a key, a template or name and
+optionally a map.
+
+#+begin_src emacs-lisp
+  (tempel-key "C-c t f" fun emacs-lisp-mode-map)
+  (tempel-key "C-c t d" (format-time-string "%Y-%m-%d"))
+#+end_src
+
+Internally ~tempel-key~ uses ~tempel-insert~ to trigger the insertion. 
Depending on
+the style of your user configuration you may want to write your own helper
+macros, which allow you to conveniently bind templates via 
[[https://github.com/jwiegley/use-package][use-package]], 
[[https://github.com/noctuid/general][general]]
+or similar keybinding packages.
+
 * Contributions
 
 Since this package is part of 
[[http://elpa.gnu.org/packages/marginalia.html][GNU ELPA]] contributions 
require a copyright