branch: externals/embark
commit 3cc955e27b2dbd4915a8cfadfa4a2fa7fa061ba6
Author: Omar Antolín <omar.anto...@gmail.com>
Commit: Omar Antolín <omar.anto...@gmail.com>
Improve target finder documentation (fix #601)
---
README.org | 17 ++++++++++-------
embark.el | 11 ++++++-----
embark.texi | 19 +++++++++++--------
3 files changed, 27 insertions(+), 20 deletions(-)
diff --git a/README.org b/README.org
index dec9fb39cc..9c87a4e0bf 100644
--- a/README.org
+++ b/README.org
@@ -790,17 +790,20 @@ to do is teach Embark that =wikipedia:Garry_Kasparov=
stands for the URL
You can be as fancy as you want with the recognized syntax. Here, to
keep the example simple, I'll assume the link matches the regexp
=wikipedia:[[:alnum:]_]+=. We will write a function that looks for a
-match surrounding point, and returns an improper list of the form
-='(url actual-url-of-the-page beg . end)= where =beg= and =end= are the
-buffer positions where the target starts and ends, and are used by
-Embark to highlight the target (if you have =embark-highlight-indicator=
-included in the list =embark-indicators=).
+match surrounding point, and returns a dotted list of the form ='(url
+actual-url-of-the-page start . end)= where =start= and =end= are the buffer
+positions bounding the target, and are used by Embark to highlight it
+if you have =embark-highlight-indicator= included in the list
+=embark-indicators=. (There are a couple of other options for the return
+value of a target finder: the bounding positions are optional and a
+single target finder is allowed to return multiple targets; see the
+documentation for =embark-target-finders= for details.)
#+begin_src emacs-lisp
(defun my-short-wikipedia-link ()
"Target a link at point of the form wikipedia:Page_Name."
(save-excursion
- (let* ((beg (progn (skip-chars-backward "[:alnum:]_:") (point)))
+ (let* ((start (progn (skip-chars-backward "[:alnum:]_:") (point)))
(end (progn (skip-chars-forward "[:alnum:]_:") (point)))
(str (buffer-substring-no-properties beg end)))
(save-match-data
@@ -808,7 +811,7 @@ included in the list =embark-indicators=).
`(url
,(format "https://en.wikipedia.org/wiki/%s";
(match-string 1 str))
- ,beg . ,end))))))
+ ,start . ,end))))))
(add-to-list 'embark-target-finders 'my-short-wikipedia-link)
#+end_src
diff --git a/embark.el b/embark.el
index 143da9e738..3258772581 100644
--- a/embark.el
+++ b/embark.el
@@ -183,12 +183,13 @@ or a list of such symbols."
"List of functions to determine the target in current context.
Each function should take no arguments and return either:
-1. a cons (type . target) where type is a symbol and target is a
- string,
+1. a cons (TYPE . TARGET) where TARGET is a string and TYPE is a
+ symbol (which is looked up in `embark-keymap-alist' to
+ determine which additional keybindings for actions to setup);
-2. a triple of the form (type target . bounds), where bounds is
- the (beg . end) bounds pair of the target at point for
- highlighting, or
+2. a dotted list of the form (TYPE TARGET START . END), where
+ START and END are the buffer positions bounding TARGET, used
+ for highlighting; or
3. a possibly empty list of targets, each of type 1 or 2."
:type 'hook)
diff --git a/embark.texi b/embark.texi
index 08c23f1e19..54ceed9ebe 100644
--- a/embark.texi
+++ b/embark.texi
@@ -937,6 +937,7 @@ Embark ask you for confirmation:
@item
You can write your own command that prompts for confirmation and
use that instead of @samp{tab-bar-close-tab-by-name} in the above keymap:
+@end enumerate
@lisp
(defun my-confirm-close-tab-by-name (tab)
(interactive "sTab to close: ")
@@ -949,7 +950,6 @@ independently of Embark. Using it from @samp{M-x} leaves
something to be
desired, though, since you don't get completion for the tab names.
You can fix this if you wish as described in the previous section.
@end enumerate
-@end enumerate
@node New target example in regular buffers - short Wikipedia links
@subsection New target example in regular buffers - short Wikipedia links
@@ -965,17 +965,20 @@ to do is teach Embark that
@samp{wikipedia:Garry_Kasparov} stands for the URL
You can be as fancy as you want with the recognized syntax. Here, to
keep the example simple, I'll assume the link matches the regexp
@samp{wikipedia:[[:alnum:]_]+}. We will write a function that looks for a
-match surrounding point, and returns an improper list of the form
-@samp{'(url actual-url-of-the-page beg . end)} where @samp{beg} and @samp{end}
are the
-buffer positions where the target starts and ends, and are used by
-Embark to highlight the target (if you have @samp{embark-highlight-indicator}
-included in the list @samp{embark-indicators}).
+match surrounding point, and returns a dotted list of the form @samp{'(url
+actual-url-of-the-page start . end)} where @samp{start} and @samp{end} are the
buffer
+positions bounding the target, and are used by Embark to highlight it
+if you have @samp{embark-highlight-indicator} included in the list
+@samp{embark-indicators}. (There are a couple of other options for the return
+value of a target finder: the bounding positions are optional and a
+single target finder is allowed to return multiple targets; see the
+documentation for @samp{embark-target-finders} for details.)
@lisp
(defun my-short-wikipedia-link ()
"Target a link at point of the form wikipedia:Page_Name."
(save-excursion
- (let* ((beg (progn (skip-chars-backward "[:alnum:]_:") (point)))
+ (let* ((start (progn (skip-chars-backward "[:alnum:]_:") (point)))
(end (progn (skip-chars-forward "[:alnum:]_:") (point)))
(str (buffer-substring-no-properties beg end)))
(save-match-data
@@ -983,7 +986,7 @@ included in the list @samp{embark-indicators}).
`(url
,(format "https://en.wikipedia.org/wiki/%s";
(match-string 1 str))
- ,beg . ,end))))))
+ ,start . ,end))))))
(add-to-list 'embark-target-finders 'my-short-wikipedia-link)
@end lisp
