[elpa] externals/eev cca8307 09/64: `find-here-links' (code and docs)

[Stefan Monnier]

branch: externals/eev
commit cca83077c36d503d0e38dc410b0c25e1b3190f8e
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    `find-here-links' (code and docs)
---
 VERSION       |   4 +-
 eev-blinks.el |  28 ++++++--
 eev-elinks.el | 199 ++++++++++++++++++++++++++++++++++++++++++++++------
 eev-intro.el  | 220 ++++++++++++++++++++++++++++++++++++++++------------------
 eev-mode.el   |  17 +++--
 eev-wrap.el   |  14 ++++
 6 files changed, 378 insertions(+), 104 deletions(-)

diff --git a/VERSION b/VERSION
index fcd53a2..3ccc3c2 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Thu Nov  7 14:56:18 GMT 2013
-Thu Nov  7 12:56:18 BRST 2013
+Sat Nov 16 05:01:13 GMT 2013
+Sat Nov 16 03:01:13 BRST 2013
diff --git a/eev-blinks.el b/eev-blinks.el
index 1b20a12..55c3c75 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -22,7 +22,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013sep12
+;; Version:    2013nov15
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -269,9 +269,25 @@ then go to the position specified by POS-SPEC-LIST.\n
   (interactive "kFind function on key: ")
   (apply 'find-wottb-call '(describe-key key) "*Help*" pos-spec-list))
 
-(defun find-efacedescr (face &rest pos-spec-list)
+(defun find-echardescr (&optional pos &rest pos-spec-list)
+  "Hyperlink to the result of running `describe-char' at POS."
+  (interactive)
+  (setq pos (or pos (point)))
+  (apply 'find-wottb-call '(describe-char pos) "*Help*" pos-spec-list))
+
+(defun find-etpat (&optional pos &rest pos-spec-list)
+  "Hyperlink to the result of running `describe-text-properties' at point.
+See `find-etpat0' and `find-etpat00' for lower-level tools for
+inspecting text proprties."
+  (interactive)
+  (setq pos (or pos (point)))
+  (apply 'find-wottb-call '(describe-text-properties pos)
+        "*Help*" pos-spec-list))
+
+(defun find-efacedescr (&optional face &rest pos-spec-list)
   "Hyperlink to the result of running `describe-face' on FACE."
-  (interactive (list (read-face-name "Describe face")))
+  ;; (interactive (list (read-face-name "Describe face")))
+  (interactive (list (face-at-point)))
   (apply 'find-wottb-call '(describe-face face) "*Help*" pos-spec-list))
 
 (defun find-efaces (&rest pos-spec-list)
@@ -717,14 +733,14 @@ Example of use: (find-einsert '((32 1000) 10 (8000 
12000)))"
   (apply 'find-eoutput-reuse "*einsert*"
         `(apply 'ee-insert ',what) rest))
 
-(defun find-etpat (&rest pos-spec-list)
-"Hyperlink to a pretty-version of the result of (text-properties-at (point))."
+(defun find-etpat0 (&rest pos-spec-list)
+"Hyperlink to a pretty version of the result of (text-properties-at (point))."
   (interactive)
   (let* ((ee-buffer-name
          (or ee-buffer-name "*(text-properties-at (point))*")))
     (apply 'find-epp (text-properties-at (point)) pos-spec-list)))
 
-(defun find-etpat0 ()
+(defun find-etpat00 ()
   "Show the result of (text-properties-at (point)) in the echo area."
   (interactive)
   (find-epp0 (text-properties-at (point))))
diff --git a/eev-elinks.el b/eev-elinks.el
index 603534d..bdf641e 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013nov07
+;; Version:    2013nov16
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -66,6 +66,7 @@
 ;; �.find-ekbmacro-links�      (to "find-ekbmacro-links")
 ;; �.find-pdflike-page-links�  (to "find-pdflike-page-links")
 ;; �.ee-hyperlink-prefix�      (to "ee-hyperlink-prefix")
+;; �.find-eface-links�         (to "find-eface-links")
 ;; �.find-color-links�         (to "find-color-links")
 
 ;; �.find-here-links�          (to "find-here-links")
@@ -626,10 +627,43 @@ evaluate f in the context of a big `let', and return the 
result."
   (if (stringp (car kill-ring))
     (ee-no-properties (car kill-ring))))
 
+(defun ee-region ()
+  (if (region-active-p)
+      (buffer-substring-no-properties (point) (mark))))
+
+(defun ee-region-or-last-kill ()
+  (or (ee-region) (ee-last-kill)))
+
 ;; (find-find-links-links "\\M-p" "pdflike-page" "page bufname offset")
 
 (define-key eev-mode-map "\M-h\M-p" 'find-pdflike-page-links)
 
+(defun ee-pdflike-page-links (&optional page bufname offset)
+  (setq page    (or page (ee-current-page)))
+  (setq bufname (or bufname (buffer-name)))
+  (setq offset  (or offset ee-page-offset))
+  (let* ((c          ee-page-c)
+        (fname      ee-page-fname)
+        (find-cpage (ee-intern "find-%spage" c))
+        (find-ctext (ee-intern "find-%stext" c))
+        (kill       (or (ee-region-or-last-kill) ""))
+        (page-      (- page offset))
+        )
+    `((,find-cpage ,page)
+      (,find-ctext ,page)
+      (,find-cpage (+ ,offset ,page-))
+      (,find-ctext (+ ,offset ,page-))
+      ""
+      (,find-cpage ,page ,kill)
+      (,find-ctext ,page ,kill)
+      (,find-cpage (+ ,offset ,page-) ,kill)
+      (,find-ctext (+ ,offset ,page-) ,kill)
+      ""
+      (code-pdf ,c ,fname)
+      (code-pdf-text ,c ,fname ,offset)
+      ,(ee-HS bufname)
+      )))
+
 (defun find-pdflike-page-links (&optional page bufname offset &rest rest)
 "Visit a temporary buffer containing hyperlinks to a pdf-like document.
 See: (find-pdf-like-intro)
@@ -645,7 +679,8 @@ See: (find-pdf-like-intro)
         (kill       (or (ee-last-kill) ""))
         (page-      (- page offset))
         )
-    (apply 'find-elinks `(
+    ;;
+    '(apply 'find-elinks `(
       (find-pdflike-page-links ,page ,bufname ,offset ,@rest)
       (find-efunction 'find-pdflike-page-links)
       ""
@@ -662,7 +697,15 @@ See: (find-pdf-like-intro)
       (code-pdf ,c ,fname)
       (code-pdf-text ,c ,fname ,offset)
       ,(ee-HS bufname)
-    ) rest)))
+    ) rest)
+    ;;
+    (apply 'find-elinks `(
+      (find-pdflike-page-links ,page ,bufname ,offset ,@rest)
+      (find-efunction 'find-pdflike-page-links)
+      ""
+      ,@(ee-pdflike-page-links page bufname offset)
+      ) rest)
+    ))
 
 ;; (find-pdflike-page-links)
 ;; (find-angg ".emacs.papers" "kopkadaly")
@@ -705,6 +748,49 @@ See the comments in the source code."
 
 
 
+
+;;;   __ _           _             __                      _ _       _        
+;;;  / _(_)_ __   __| |       ___ / _| __ _  ___ ___      | (_)_ __ | | _____ 
+;;; | |_| | '_ \ / _` |_____ / _ \ |_ / _` |/ __/ _ \_____| | | '_ \| |/ / __|
+;;; |  _| | | | | (_| |_____|  __/  _| (_| | (_|  __/_____| | | | | |   <\__ \
+;;; |_| |_|_| |_|\__,_|      \___|_|  \__,_|\___\___|     |_|_|_| |_|_|\_\___/
+;;;                                                                           
+;; See: (find-links-intro)
+;;      (find-templates-intro)
+
+;; �find-eface-links� (to ".find-eface-links")
+;; (find-find-links-links "\\M-s" "eface" "face-symbol")
+;; A test: (find-eface-links 'bold)
+(define-key eev-mode-map "\M-h\M-s" 'find-eface-links)
+
+(defun find-eface-links (face-symbol &rest pos-spec-list)
+"Visit a temporary buffer containing hyperlinks about FACE-SYMBOL."
+  (interactive (list (or (face-at-point) 'default)))
+  ;; (setq face-symbol (or face-symbol "{face-symbol}"))
+  ;; (setq face-symbol (or face-symbol (face-at-point)))
+  (apply 'find-elinks
+   `((find-eface-links ',face-symbol ,@pos-spec-list)
+     ;; Convention: the first sexp always regenerates the buffer.
+     (find-efunction 'find-eface-links)
+     ""
+     (find-efacedescr ',face-symbol)
+     (find-eface ',face-symbol)
+     (customize-face ',face-symbol)
+     (set-face-foreground ',face-symbol ,(face-foreground face-symbol))
+     (set-face-background ',face-symbol ,(face-background face-symbol))
+     (face-id ',face-symbol)
+     (find-epp (mapcar (lambda (face) (cons (face-id face) face)) (face-list)))
+     (find-ecolors)
+     (find-efaces)
+     )
+   pos-spec-list))
+
+;; Test: (find-eface-links 'eepitch-star-face)
+;; (find-eevfile "eev.el" "\\M-h\\M-s")
+
+
+
+
 ;;;   __ _           _                     _                _ _       _        
 ;;;  / _(_)_ __   __| |      ___  ___ ___ | | ___  _ __    | (_)_ __ | | _____ 
 ;;; | |_| | '_ \ / _` |____ / _ \/ __/ _ \| |/ _ \| '__|___| | | '_ \| |/ / __|
@@ -770,37 +856,103 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 
 (define-key eev-mode-map "\M-h\M-h" 'find-here-links)
 
-(defun ee-buffer-re   (re)  (string-match re (buffer-name)))
-(defun ee-buffer-eq   (str) (string= str (buffer-name)))
+;; Tools
+;; (defun ee-buffer-re (re)  (string-match re (buffer-name)))
+(defun ee-buffer-re (re)
+  (if (string-match re (buffer-name))
+      (match-string 1 (buffer-name))))
+(defun ee-buffer-eq (str) (string= str (buffer-name)))
+
+(defun ee-buffer-help0    () (ee-buffer-eq "*Help*"))
+(defun ee-buffer-help-re0 (re n)
+  (if (ee-buffer-help0)
+      (save-excursion
+       (goto-char (point-min))
+       (if (looking-at re) (match-string n)))))
 
+(defun ee-buffer-help (re n) (intern (or (ee-buffer-help-re0 re n) "nil")))
+
+;; By major mode
 (defun ee-grep-bufferp     () (eq major-mode 'grep-mode))
 (defun ee-man-bufferp      () (eq major-mode 'Man-mode))
 (defun ee-rcirc-bufferp    () (eq major-mode 'rcirc-mode))
 (defun ee-info-bufferp     () (eq major-mode 'Info-mode))
 (defun ee-dired-bufferp    () (eq major-mode 'dired-mode))
 (defun ee-wdired-bufferp   () (eq major-mode 'wdired-mode))
-(defun ee-file-bufferp     () buffer-file-name)
+(defun ee-w3m-bufferp      () (eq major-mode 'w3m-mode))
+
+;; By buffer name
 (defun ee-intro-bufferp    () (ee-buffer-re "^\\*(find-\\(.*\\)-intro)\\*$"))
 (defun ee-freenode-bufferp () (ee-buffer-re "^\\(.*\\).freenode\\.net"))
-
 (defun ee-ecolors-bufferp  () (ee-buffer-eq "*Colors*"))
 (defun ee-efaces-bufferp   () (ee-buffer-eq "*Faces*"))
+(defun ee-pdftext-bufferp  () (ee-buffer-re "^pdftotext"))
+
+;; By buffer name (when it is "*Help*")
+(defvar ee-efunctiondescr-re "^\\([^ \t\n]+\\) is a[^\t\n]*function")
+(defun  ee-efunctiondescr-bufferp () (ee-buffer-help ee-efunctiondescr-re 1))
+(defun  ee-find-efunctiondescr-links ()
+  (let ((f (ee-efunctiondescr-bufferp)))
+    `((find-efunction-links ',f)
+      (find-efunctiondescr ',f))))
+
+(defvar ee-evardescr-re "^\\([^ \t\n]+\\) is a variable")
+(defun  ee-evardescr-bufferp () (ee-buffer-help ee-evardescr-re 1))
+(defun  ee-find-evardescr-links ()
+  (let ((v (ee-evardescr-bufferp)))
+    `((find-evariable-links ',v)
+      (find-evardescr ',v))))
+
+(defvar ee-efacedescr-re "^Face: \\([^ \t\n]+\\)")
+(defun  ee-efacedescr-bufferp () (ee-buffer-help ee-efacedescr-re 1))
+(defun  ee-find-efacedescr-links ()
+  (let ((f (ee-efacedescr-bufferp)))
+    `((find-eface-links ',f)
+      (find-efacedescr ',f))))
+
+;; By buffer name (when the mode is man)
+(defvar ee-man-re "^\\*Man \\(.*\\)\\*$")
+(defun  ee-find-man-links () 
+  (let ((mp (ee-buffer-re ee-man-re)))
+    `((find-man ,mp))))
+
+;; Other cases
+(defun ee-file-bufferp     () buffer-file-name)
+
+
+
+(defun ee-find-efaces-links  () `((find-efaces)))
+(defun ee-find-ecolors-links () `((find-ecolors)))
+(defun ee-find-pdftext-links () (ee-pdflike-page-links))
 
-(defun ee-find-man-links (&optional mp) 
-  (setq mp (or mp (replace-regexp-in-string
-                  "^\\*Man \\(.*\\)\\*$" "\\1" (buffer-name))))
-  `((find-man ,mp)))
+;; to to:
+;; ee-find-w3m-links
+;; ee-find-ecolor-links
+;; 
 
 (defun ee-find-here-links ()
-  (cond ((ee-info-bufferp)     (cons "" (ee-find-info-links)))     ; M-h M-i
-       ((ee-intro-bufferp)    (cons "" (ee-find-intro-links)))    ; M-h M-i
+  (cond ;; by major mode
+       ((ee-info-bufferp)     (cons "" (ee-find-info-links)))     ; M-h M-i
        ((ee-man-bufferp)      (cons "" (ee-find-man-links)))      ; ?
        ((ee-grep-bufferp)     (cons "" (ee-find-grep-links)))     ; M-h M-g
-       ((ee-freenode-bufferp) (cons "" (ee-find-freenode-links))) ; ?
+       ((ee-w3m-bufferp)      (cons "" (ee-find-w3m-links)))      ; M-h M-w
        ((ee-dired-bufferp)    (cons "" (ee-find-file-links)))     ; M-h f
        ((ee-wdired-bufferp)   (cons "" (ee-find-file-links)))     ; M-h f
+       ;; by buffer name
+       ((ee-intro-bufferp)    (cons "" (ee-find-intro-links)))    ; M-h M-i
+       ((ee-freenode-bufferp) (cons "" (ee-find-freenode-links))) ; ?
+       ((ee-ecolors-bufferp)  (cons "" (ee-find-ecolors-links)))  ; ?
+       ((ee-efaces-bufferp)   (cons "" (ee-find-efaces-links)))   ; ?
+       ((ee-pdftext-bufferp)  (cons "" (ee-find-pdftext-links)))  ; ?
+       ;; by buffer name, when it is "*Help*"
+       ((ee-efunctiondescr-bufferp) (cons "" (ee-find-efunctiondescr-links)))
+       ((ee-efacedescr-bufferp)     (cons "" (ee-find-efacedescr-links)))
+       ((ee-evardescr-bufferp)      (cons "" (ee-find-evardescr-links)))
+       ;; other cases
        ((ee-file-bufferp)     (cons "" (ee-find-file-links)))     ; M-h f
-       (t (list "hello" "you"))))
+       (t (list "" "Not implemented!" "See:"
+                '(find-efunction 'ee-find-here-links)))
+       ))
 
 (defun find-here-links-test (sexp)
 "See: (find-links-intro \"`find-here-links'\")"
@@ -810,19 +962,22 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 ;; (progn (find-man "1 cat") (buffer-name))
 ;; (find-eevfile "eev-rcirc.el")
 
+(defun ee-find-here-links0 ()
+  `(,(ee-H "See: ")
+    (find-links-intro "`find-here-links'")
+    (find-efunctiondescr 'eev-mode "M-h M-h")
+    ))
+
 ;; (find-find-links-links "\\M-h" "here" "")
 ;;
 (defun find-here-links (&rest pos-spec-list)
 "Visit a temporary buffer containing hyperlinks pointing to here."
   (interactive)
   (apply 'find-elinks
-   `(;; (find-here-links  ,@pos-spec-list)
-     ;; Convention: the first sexp always regenerates the buffer.
-     ;; (find-efunction 'find-here-links)
-     ,(ee-H "See: ")
-     (find-links-intro "`find-here-links'")
-     (find-efunctiondescr 'eev-mode "M-h M-h")
-     ;; ""
+   `(;; The first line of a find-here-links buffer DOES NOT
+     ;; regenerates the buffer - instead the first lines point to
+     ;; help pages.
+     ,@(ee-find-here-links0)
      ,@(ee-find-here-links)
      )
    pos-spec-list))
diff --git a/eev-intro.el b/eev-intro.el
index 3a7c6ee..0ea16b6 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013sep30
+;; Version:    2013nov15
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -36,6 +36,14 @@
 ;;   (find-eepitch-intro)
 ;;   (find-wrap-intro)
 ;;   (find-code-c-d-intro)
+;;
+;; Note (2013nov12):
+;; I am using this code to edit these intros:
+;;
+;; (defun ee-sexp-at (str) (save-excursion (search-forward str) 
(ee-last-sexp)))
+;; (defun ee-intro-here () (eval (read (ee-sexp-at "rest)))"))))
+;; (defun d0 () (funcall (ee-intro-here) (ee-last-kill)))
+;; (defun d () (interactive) (find-2b nil '(d0)))
 
 
 
@@ -1226,79 +1234,151 @@ be expanded later:
 
 `find-here-links'
 =================
-The most important M-h command is `M-h M-h' (`find-here-links'),
-which analyzes the major mode and the buffer name of the current
-buffer and runs the most adequade of several `find-*-links'
-commands. For example, if you type `M-h M-h' now you should get
-a buffer like this:
-   __________________________________________________________
-  |# See:                                                    |
-  |# (find-links-intro \"`find-here-links'\")                  |
-  |                                                          |
-  |# (find-links-intro)                                      |
-  |                                                          |
-  | -:**-  *Elisp hyperlinks*   All L1     (Fundamental eev) |
-  |__________________________________________________________|
-
-where `(find-links-intro)' is a hyperlink to this intro.
-
-  [NOTE: `find-here-links' is a new feature, and its buffers do
-  not yet follow all the conventions of elisp hyperlinks
-  buffers... some minor details will probably change soon to
-  reduce the risk of confusion]
-
-Normally we use `M-h M-h' like this. We are putting our
-\(executable, but messy) notes into something that we will refer
-to as an \"e-script buffer\"; we find a piece of interesting
-information at another buffer, and we want to put a link to that
-into our e-script buffer. The link that we will produce is a
-sexp, which goes to a \"target\" when executed. This is a bit
-confusing, to let's demonstrate it sort of backwards...
-
-The debugging function `find-here-links-test' receives a sexp and
-creates a window setting like this:
-   ___________________________________
-  |          |                        |
-  |          |     target of SEXP     |
-  |          |________________________|
-  |   here   |                        |
-  |          |   result of running    |
-  |          |  `find-here-links' on  |
-  |          |   the target of SEXP   |
-  |__________|________________________|
-
-Try it by running the `find-here-links-test' sexps below. Note
-that they will keep the cursor at the \"here\" window - i.e.,
-here at (find-links-intro) - so you can just move up and down
-between the tests and execute the other tests with `M-e'.
+The most important of the commands that generates buffers with elisp
+hyperlinks - \"M-h commands\", in the terminology explained above - is
+`find-here-links', which integrates most of the functionalities of
+several more basic M-h commands. We will explain first what it _does_,
+then its _usage_.
+
+`find-here-links' is bound to `M-h M-h' to make it very easy to
+invoke. If you are reading this then \"here\" means the buffer
+\"*(find-links-intro)*\", in a certain position. Try to type `M-h M-h';
+you will get a buffer like this,
+
+   ____________________________________________________________
+  |# See:                                                      |
+  |# (find-links-intro \"`find-here-links'\")                    |
+  |# (find-efunctiondescr 'eev-mode \"M-h M-h\")                 |
+  |                                                            |
+  |# (find-links-intro)                                        |
+  |                                                            |
+  |                                                            |
+  |--:**-  *Elisp hyperlinks*   All L1     (Fundamental eev)  -|
+  |____________________________________________________________|
+
+which contains a 3-line header with help links, that we will explain
+soon, and then a link to \"here\", i.e., to the buffer
+\"*(find-links-intro)*\". Note that the link
+
+  (find-links-intro)
+
+can be \"refined\" to, for example,
+
+  (find-links-intro \"which contains a 3-line header\")
+
+using the tricks described in these sections:
+
+  (find-eval-intro \"Refining hyperlinks\")
+  (find-eval-intro \"Producing and refining hyperlinks\")
+  (find-eval-intro \"Producing and refining hyperlinks\" \"`M-h M-2'\")
+  (find-eval-intro \"Producing and refining hyperlinks\" \"`M-h2hy'\")
+
+but `find-here-links' by itself only produces \"unrefined\" links - so
+when we say that `find-here-links' produces links to \"here\" we mean
+just \"to the current buffer\", not \"to the a certain position in the
+current buffer\".
+
+`find-here-links' works for several kinds of \"here\"s - it works for
+intros like this one, for Info pages, for manpages, for files and
+directories, for descriptions of Emacs functions and variables, and
+for a few other cases. Try the sexps below:
 
   (find-here-links-test '(find-eval-intro))
   (find-here-links-test '(find-node \"(dir)Top\"))
+  (find-here-links-test '(find-enode \"Lisp Eval\"))
+  (find-here-links-test '(find-fline \"~/\"))
   (find-here-links-test '(find-eevfile \"eepitch.el\"))
-  (find-here-links-test '(find-efunction 'find-here-links))
+  (find-here-links-test '(find-efunction 'ee-eval-last-sexp))
+
+  (find-here-links-test '(find-efunctiondescr 'ee-eval-last-sexp))
+  (find-here-links-test '(find-evardescr      'ee-hyperlink-prefix))
+  (find-here-links-test '(find-efacedescr     'eepitch-star-face))
+
+  (find-here-links-test '(find-ecolors \"\\nred\"))
+  (find-here-links-test '(find-efaces  \"eepitch-star-face\"))
+
   (find-here-links-test '(find-man \"1 cat\"))
-  (find-here-links-test '(find-fline \"~/\"))
+   [^ oops, this test doesn't work on multi-window settings...]
+
+Each one of them tests a different case of `find-here-links',
+creating a window setup like this:
 
-Now let's see the typical, real-life usage case. We don't start
-with the sexp that points to a target - we stumble at something
-interesting, and then we want to _produce_ a sexp that points to
-that, and then save it to our notes. When we are at \"interesting
-place\" we type `M-h M-h'; we get a find-here-links buffer, and
-we choose the sexp that looks more adequate between the ones that
-point to \"interesting place\". We edit that sexp - refining it
-if needed - and copy it to our e-script. If we want to go back to
-\"interesting place\" we can do that either with the right
-sequence of `M-K's or by executing the sexp.
+   ______________________________________ 
+  |               |                      |
+  |               |      target of       |
+  |               |        sexp          |
+  |     this      |______________________|
+  |     intro     |                      |
+  |               |  result of running   |
+  |               |  find-here-links on  |
+  |               |   [target of sexp]   |
+  |_______________|______________________|
 
-  [Note that `M-1 M-j' jumps to ~/TODO... EXPLAIN THIS]
+The cursor is kept at the left window (\"this intro\"), so you
+can compare the different cases using just <up>, <down>, and M-e.
 
 
 
 
+`find-here-links': usage patterns
+=================================
+Typically what happens is this. We are putting our notes - eepitch
+blocks, hyperlinks, etc - in a certain file; let's refer to it as the
+\"e-script\". Then we start to navigate for information, and we find
+something interesting. We want to add a link pointing to that
+\"something interesting\" to our e-script notes - but for that we need
+to produce that sexp hyperlink, and ideally we would like to do that
+in a way that does not disturb much our attention. Consider this
+diagram [note: it DOES NOT imply that the Emacs frame is split into three
+windows - typically we will switch between buffers in a single window]:
+
+   ______________________________________ 
+  |               |                      |
+  |               |      something       |
+  |              ==>    interesting      |
+  |   e-script    |_________||___________|
+  |               |         \\/           |
+  |               |  result of running   |
+  |              <== find-here-links on  |
+  |               |   [sthing intrstng]  |
+  |_______________|______________________|
+
+and this series of steps:
+
+  0. We start navigating from the e-script buffer, and when we
+  1. find something interesting [in another buffer], we
+  2. run `find-here-links' at the \"something interesting\" buffer,
+  3. identify among the sexps in the find-here-links buffer one that
+     points to that \"something interesting\",
+  4. copy that sexp to the kill-ring,
+  5. go back to the e-script buffer,
+  6. insert that sexp into the e-script buffer,
+  7. execute that sexp to go back to the \"something interesting\",
+  8. continue navigating & doing stuff.
+
+At (8) we are essentially back to (1), but we have added to our
+e-script buffer a link to \"something interesting\". 
+
+Note that to add refining we need to add a step before (2) and
+another one after (3):
+
+  1.9. select a string to search for and copy it to the kill-ring,
+  3.1. refine that sexp using the \"string to search for\" (with M-h2hy)
+
+\[TO DO: explain the keys that I normally use to perform all
+this; explain why I am not the right person to optimize these
+steps - because I can type these key sequences without thinking,
+and step (3) sometimes gives several sexps for us to choose from]
+
+
 
 
 Basic and non-basic hyperlinks
 ==============================
+How can we learn to recognize what each hyperlink sexp does? And
+which ones are safe(r), and which ones are not? How do we
+classify all hyperlink sexps?
+
 We can start by dividing the hyperlink functions into a fixed set
 of \"basic\" ones and an unbounded set of \"non-basic\" ones. In
 the buffer generated by
@@ -5032,7 +5112,7 @@ returns nil. But just as
 ;; �find-emacs-intro� (to ".find-emacs-intro")
 ;; (find-intro-links "emacs")
 
-(defun find-emacs-intro (&rest pos-spec-list) (interactive)
+(defun find-emacs-intro (&rest rest) (interactive)
   (let ((ee-buffer-name "*(find-emacs-intro)*"))
     (apply 'find-estring "\
 \(Re)generate: (find-emacs-intro)
@@ -5055,6 +5135,7 @@ The most basic keys of eev are:
         `M-2j' takes you to this help page.
         `M-5j' takes you to: (find-eev-intro)
          See: (find-eejump-intro \"Families\")
+  M-h M-h - hyperlinks to here, plus help
 
 The mnemonics are:
   M-e   - evaluate/execute
@@ -5155,9 +5236,20 @@ or by using the menu bar (the relevant options are under
 Undoing
 =======
 C-/    -- undo    (find-enode \"Basic Undo\")
+C-_    -- undo    (find-enode \"Basic Undo\")
                   (find-enode \"Undo\")
 
 
+Windows
+=======
+See: (find-enode \"Frames\")
+     (find-enode \"Windows\")
+C-x o   -- other-window                      (find-enode \"Other Window\")
+C-x 0   -- delete-window                     (find-enode \"Change Window\")
+C-x 1   -- delete-other-windows (\"1 window\") (find-enode \"Change Window\")
+C-x 2   -- split-window-vertically (Abv/Blw) (find-enode \"Split Window\")
+C-x 3   -- split-window-horizontally   (L|R) (find-enode \"Split Window\")
+
 
 
 Other keys / reference
@@ -5168,12 +5260,6 @@ TAB     -- for completion:              (find-enode 
\"Completion\")
            for indentation:             (find-enode \"Indentation\")
            in programming modes:        (find-enode \"Basic Indent\")
 
-C-x o   -- other-window                      (find-enode \"Other Window\")
-C-x 0   -- delete-window                     (find-enode \"Change Window\")
-C-x 1   -- delete-other-windows (\"1 window\") (find-enode \"Change Window\")
-C-x 2   -- split-window-vertically (Abv/Blw) (find-enode \"Split Window\")
-C-x 3   -- split-window-horizontally   (L|R) (find-enode \"Split Window\")
-
                                         (find-enode \"Dired\")
 C-x C-f -- find-file                    (find-enode \"Visiting\")
 C-x C-s -- save-buffer                  (find-enode \"Saving\")
@@ -5197,7 +5283,7 @@ M-%     -- query-replace                (find-enode 
\"Replace\")
 C-x (   -- start-kbd-macro              (find-enode \"Keyboard Macros\")
 C-x )   -- end-kbd-macro                (find-enode \"Keyboard Macros\")
 C-x e   -- call-last-kbd-macro          (find-enode \"Keyboard Macros\")
-" pos-spec-list)))
+" rest)))
 
 ;; (find-emacs-intro)
 ;; (find-TH "emacs" "short-emacs-tutorial")
diff --git a/eev-mode.el b/eev-mode.el
index c8cc397..f2d24b4 100644
--- a/eev-mode.el
+++ b/eev-mode.el
@@ -1,6 +1,6 @@
 ;;; eev-mode.el -- a minor mode with keybindings for using eev conveniently.
 
-;; Copyright (C) 2012 Free Software Foundation, Inc.
+;; Copyright (C) 2012,2013 Free Software Foundation, Inc.
 ;;
 ;; This file is (not yet?) part of GNU eev.
 ;;
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013feb16
+;; Version:    2013nov15
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-mode.el>
@@ -90,17 +90,20 @@ See: (find-eval-intro \"`M-k'\")"
   (define-key eev-mode-map "\M-h\M-f" 'find-efunction-links) 
   (define-key eev-mode-map "\M-h\M-i" 'find-einfo-links)     
   (define-key eev-mode-map "\M-h\M-k" 'find-ekey-links)      
-  (define-key eev-mode-map "\M-h\M-m" 'find-manpage-links)   
   (define-key eev-mode-map "\M-h\M-p" 'find-pdflike-page-links)
   (define-key eev-mode-map "\M-h\M-v" 'find-evariable-links) 
   (define-key eev-mode-map "\M-hf"    'find-file-links)      
-  (define-key eev-mode-map "\M-hm"    'find-last-manpage-links)
   (define-key eev-mode-map "\M-hM"    'find-ekbmacro-links)
-  ;; Information about text properties, faces, and chars: 
-  (define-key eev-mode-map "\M-h\M-s" 'find-efacedescr)
-  (define-key eev-mode-map "\M-h\M-c" 'describe-char)
+  ;; (define-key eev-mode-map "\M-h\M-m" 'find-manpage-links)   
+  ;; (define-key eev-mode-map "\M-hm"    'find-last-manpage-links)
+  ;;
+  ;; Information about text properties, faces, and chars:
+  ;; (define-key eev-mode-map "\M-h\M-s" 'find-efacedescr)
+  (define-key eev-mode-map "\M-h\M-c" 'find-echardescr)
+  (define-key eev-mode-map "\M-h\M-s" 'find-eface-links)
   (define-key eev-mode-map "\M-h\M-t" 'find-etpat)
   (define-key eev-mode-map "\M-ht"    'find-etpat0)
+  ;;
   ;; Extras:
   (define-key eev-mode-map "\M-hg"    'find-git-links-1)
   ;;
diff --git a/eev-wrap.el b/eev-wrap.el
index acdda2e..d915b8e 100644
--- a/eev-wrap.el
+++ b/eev-wrap.el
@@ -384,7 +384,21 @@ cd     {dir}"))
 \(code-audio \"{stem}\" \"{fname}\")
 \(code-video \"{stem}\" \"{fname}\")
 ;; \(find-{stem})
+"))
+
+;; 2013nov15:
+(defun ee-wrap-audiovideo (stem fname)
+  "An internal function used by `eewrap-audiovideo'."
+  (ee-template0 "\
+;; (find-fline {(ee-S (file-name-directory fname))})
+;; (find-audio \"{fname}\")})
+;; (find-video \"{fname}\")})
+\(code-audio \"{stem}\" \"{fname}\")
+\(code-video \"{stem}\" \"{fname}\")
+;; \(find-{stem})
 ;; \(find-{stem} \"0:00\")
+;; \(find-{stem} t)
+;; \(eev-avadj-mode 1)
 "))