[elpa] externals/eev 5dbba21 40/64: Added `find-eunicodeucs'; added lots of documentation.

[Stefan Monnier]

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

    Added `find-eunicodeucs'; added lots of documentation.
---
 ChangeLog      |  15 ++
 VERSION        |   4 +-
 eev-blinks.el  | 101 +++++++++----
 eev-code.el    |  16 +-
 eev-codings.el |  50 ++++++-
 eev-elinks.el  |   4 +-
 eev-intro.el   | 449 ++++++++++++++++++++++++++++++++++-----------------------
 eev-mode.el    |   3 +-
 eev-wrap.el    |  22 ++-
 9 files changed, 442 insertions(+), 222 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fe6febb..08a6057 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2019-02-23  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-links-intro): rewrote some sections.
+       (find-links-conv-intro): new function.
+
+       * eev-wrap.el: added comments about `ee-template0' and
+       `ee-template00'.
+
+       * eev-blinks.el (ee-unicode-data-file): new variable.
+       (find-eunicode): new function.
+       (find-eunicodeucs): new function.
+
+       * eev-mode.el (eev-mode-map-set): new binding: `M-h M-n'
+       (`find-eunicodeucs').
+
 2019-02-22  Eduardo Ochs  <address@hidden>
 
        * eev-intro.el (find-escripts-intro): added some text.
diff --git a/VERSION b/VERSION
index 684e14a..33f90e1 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Fri Feb 22 23:06:03 GMT 2019
-Fri Feb 22 20:06:03 -03 2019
+Sun Feb 24 17:13:22 GMT 2019
+Sun Feb 24 14:13:22 -03 2019
diff --git a/eev-blinks.el b/eev-blinks.el
index 0869af3..9111b29 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -23,7 +23,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb13
+;; Version:    2019feb23
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -56,6 +56,8 @@
 ;; �.find-Package�             (to "find-Package")
 ;; �.find-epp�                 (to "find-epp")
 ;; �.find-einternals�          (to "find-einternals")
+;; �.find-einsert�             (to "find-einsert")
+;; �.find-eunicode�            (to "find-eunicode")
 ;; �.find-eejumps�             (to "find-eejumps")
 
 
@@ -339,28 +341,28 @@ then go to the position specified by POS-SPEC-LIST.\n
 ;;   (find-efaces              "default")
 ;;   (find-efacedescr 'default "Foreground:")
 
-(defun find-efaces (&rest pos-spec-list)
-  "Hyperlink to the result of running `list-faces-display'."
+(defun find-echardescr (&optional pos &rest pos-spec-list)
+  "Hyperlink to the result of running `describe-char' at POS."
   (interactive)
-  (apply 'find-wottb-call '(list-faces-display) "*Faces*" pos-spec-list))
+  (setq pos (or pos (point)))
+  (apply 'find-wottb-call '(describe-char pos) "*Help*" pos-spec-list))
 
 (defun find-ecolors (&rest pos-spec-list)
   "Hyperlink to the result of running `list-colors-display'."
   (interactive)
   (apply 'find-wottb-call '(list-colors-display) "*Colors*" 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-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 (face-at-point)))
   (apply 'find-wottb-call '(describe-face face) "*Help*" pos-spec-list))
 
+(defun find-efaces (&rest pos-spec-list)
+  "Hyperlink to the result of running `list-faces-display'."
+  (interactive)
+  (apply 'find-wottb-call '(list-faces-display) "*Faces*" 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
@@ -775,7 +777,6 @@ explicitly. Try this: (progn (message \"foo\") \"bar\")"
 ;; �find-einternals�  (to ".find-einternals")
 ;; Hyperlinks to other things internal to Emacs
 ;; Tests:
-;;   (find-einsert '((32 255) 10 (8592 9167)))
 ;;   (find-etpat)
 ;;   (find-etpat0)
 
@@ -801,25 +802,6 @@ Example: (find-eminorkeymapdescr 'eev-mode)"
 Example: (find-ekeymapdescr (ee-minor-mode-keymap 'eev-mode))"
   (cdr (assq mode-symbol minor-mode-map-alist)))
 
-;; Test: (ee-insert "\n;; " '(?a ?z) 32 "Foo")
-(defun ee-insert (&rest rest)
-  "Insert characters, strings, or ranges of characters.
-Example: (ee-insert '(?a ?z) 10 \"Foo!\")"
-  (while rest
-    (let ((o (car rest)))
-      (cond ((stringp o) (insert o))
-           ((numberp o) (if (char-valid-p o) (insert o)))
-           ((consp o) (mapc 'ee-insert (apply 'number-sequence o)))
-           (t (error "Not string/int/pair: %S" o))))
-    (setq rest (cdr rest))))
-
-;; Test: (find-einsert '((32 1000) 10 (8000 12000)))
-(defun find-einsert (what &rest rest)
-"See `ee-insert'.
-Example of use: (find-einsert '((32 1000) 10 (8000 12000)))"
-  (apply 'find-eoutput-reuse "*einsert*"
-        `(apply 'ee-insert ',what) rest))
-
 ;; Broken? See: (find-efile "international/ccl.el")
 (defun find-eccldump (ccl-code &rest pos-spec-list)
   "Hyperlink to the result of running `ccl-dump' on CCL-CODE.
@@ -845,6 +827,65 @@ Examples: (find-echarsetchars 'mule-unicode-0100-24ff 
\"733x\")
 
 
 
+;;;   __ _           _            _                     _   
+;;;  / _(_)_ __   __| |       ___(_)_ __  ___  ___ _ __| |_ 
+;;; | |_| | '_ \ / _` |_____ / _ \ | '_ \/ __|/ _ \ '__| __|
+;;; |  _| | | | | (_| |_____|  __/ | | | \__ \  __/ |  | |_ 
+;;; |_| |_|_| |_|\__,_|      \___|_|_| |_|___/\___|_|   \__|
+;;;                                                         
+;; �find-einsert� (to ".find-einsert")
+
+;; Test: (ee-insert "\n;; " '(?a ?z) 32 "Foo")
+(defun ee-insert (&rest rest)
+  "Insert characters, strings, or ranges of characters.
+Example: (ee-insert '(?a ?z) 10 \"Foo!\")"
+  (while rest
+    (let ((o (car rest)))
+      (cond ((stringp o) (insert o))
+           ((numberp o) (if (char-valid-p o) (insert o)))
+           ((consp o) (mapc 'ee-insert (apply 'number-sequence o)))
+           (t (error "Not string/int/pair: %S" o))))
+    (setq rest (cdr rest))))
+
+;; Tests: (find-einsert '((32 1000) 10 (8000 12000)))
+;;        (find-einsert '("Greek:\n" (913 969) 10 "Bold:\n" (120276 120327)))
+(defun find-einsert (what &rest rest)
+"Show characters, strings, and ranges of characters in a temporary buffer.
+Example of use: (find-einsert '((32 1000) 10 (8000 12000)))"
+  (apply 'find-eoutput-reuse "*einsert*"
+        `(apply 'ee-insert ',what) rest))
+
+
+
+;;;   __ _           _                        _               _      
+;;;  / _(_)_ __   __| |       ___ _   _ _ __ (_) ___ ___   __| | ___ 
+;;; | |_| | '_ \ / _` |_____ / _ \ | | | '_ \| |/ __/ _ \ / _` |/ _ \
+;;; |  _| | | | | (_| |_____|  __/ |_| | | | | | (_| (_) | (_| |  __/
+;;; |_| |_|_| |_|\__,_|      \___|\__,_|_| |_|_|\___\___/ \__,_|\___|
+;;;                                                                  
+;; �find-eunicode� (to ".find-eunicode")
+
+(defvar ee-unicode-data-file
+  "/usr/share/unicode/UnicodeData.txt"
+  "The table of unicode characters used by `find-eunicodeucs'.
+Hint: install the Debian package \"unicode-data\".")
+
+;; Test: (find-eunicode "203D;INTERROBANG")
+(defun find-eunicode (&rest pos-spec-list)
+  "Find POS-SPEC-LIST in the file UnicodeData.txt."
+  (apply 'find-fline ee-unicode-data-file pos-spec-list))
+
+;; Test: run the `eek' sexp below.
+;;   (find-einsert '("Greek:\n" (913 969) 10 "Bold:\n" (120276 120327)) 4)
+;;   (eek "<up> M-e  C-x 1  C-x 3  C-x o  M-h M-n")
+(defun find-eunicodeucs (c &rest pos-spec-list)
+  "Find the entry about the character at point in the file UnicodeData.txt."
+  (interactive (list (char-after (point))))
+  (apply 'find-eunicode (format "\n%04X" (encode-char c 'ucs)) pos-spec-list))
+
+
+
+
 
 ;;;   __ _           _                  _                           
 ;;;  / _(_)_ __   __| |       ___  ___ (_)_   _ _ __ ___  _ __  ___ 
diff --git a/eev-code.el b/eev-code.el
index 10a7b63..1325d61 100644
--- a/eev-code.el
+++ b/eev-code.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb13
+;; Version:    2019feb24
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-code.el>
@@ -32,6 +32,18 @@
 
 ;;; Commentary:
 
+;; This file defines `code-c-d', that is used to mass-produce
+;; short(er) hyperlinks, as explained here:
+;;
+;;   (find-eev-quick-intro "9. Shorter hyperlinks")
+;;   (find-eev-quick-intro "9.1. `code-c-d'")
+;;
+;; and it also defines `find-code-c-d', that is a debugging function
+;; that can be considered as a hyperlink to templated text. Try:
+;;
+;;   (find-code-c-d "CODE" "/DIR/" :info "INFO")
+
+
 
 
 
@@ -42,7 +54,7 @@
 ;;              (find-elnode "Constant Variables")
 ;; The name "tail call" is misleading - this is recursive,
 ;; but not a tail call in the usual sense.
-;;
+
 (defun ee-tail-call (fmt rest)
   "An internal function used to support keyword-argument pairs."
   (cond ((null rest) "")
diff --git a/eev-codings.el b/eev-codings.el
index ee13a5c..468a905 100644
--- a/eev-codings.el
+++ b/eev-codings.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2018mai16
+;; Version:    2019feb24
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-coding.el>
@@ -38,6 +38,24 @@
 ;; trick unneccessary - `ee-format-as-anchor' now uses `ee-tolatin1'
 ;; to produce a search string that works both unibyte, on UTF-8, on
 ;; latin-1 files and some (most?) other encodings.
+;;
+;; NOTE: `ee-tolatin1' a hack! Conversion to latin-1 seems to work in
+;; most cases, but I don't understand very well the reasons why... I
+;; have some notes about all this in these e-script blocks in my notes
+;; about Emacs:
+;;
+;;   (find-es "emacs" "unibyte-2019")
+;;   (find-es "emacs" "unibyte-2019-search")
+;;   (find-es "emacs" "creating-utf8-files")
+;;   (find-es "emacs" "ee-re-to")
+;;   http://angg.twu.net/e/emacs.e.html#unibyte-2019
+;;   http://angg.twu.net/e/emacs.e.html#unibyte-2019-search
+;;   http://angg.twu.net/e/emacs.e.html#creating-utf8-files
+;;   http://angg.twu.net/e/emacs.e.html#ee-re-to
+
+;; «.ee-tolatin1»      (to "ee-tolatin1")
+;; «.ee-tolatin1-re»   (to "ee-tolatin1-re")
+
 
 
 
@@ -47,6 +65,7 @@
 ;;; |  __/  __/_____| || (_) | | (_| | |_| | | | | |
 ;;;  \___|\___|      \__\___/|_|\__,_|\__|_|_| |_|_|
 ;;;                                                 
+;; «ee-tolatin1» (to ".ee-tolatin1")
 ;; Original comment:
 ;;
 ;; 2017jul29: this is a low-level hack to allow anchors like "«tag»"
@@ -67,6 +86,35 @@ This function is used by `ee-format-as-anchor'."
 
 
 
+
+;;;                  _        _       _   _       _                
+;;;   ___  ___      | |_ ___ | | __ _| |_(_)_ __ / |      _ __ ___ 
+;;;  / _ \/ _ \_____| __/ _ \| |/ _` | __| | '_ \| |_____| '__/ _ \
+;;; |  __/  __/_____| || (_) | | (_| | |_| | | | | |_____| | |  __/
+;;;  \___|\___|      \__\___/|_|\__,_|\__|_|_| |_|_|     |_|  \___|
+;;;                                                                
+;; «ee-tolatin1-re» (to ".ee-tolatin1-re")
+;; 2019feb24: this is a hack!
+;; Test code: (find-es "emacs" "unibyte-2019-search")
+
+(defun ee-tolatin1-re (re)
+  "Make the regexp RE compatible with the current buffer.
+This is similar to `ee-tolatin1', but for regexps that contain
+the \"«»\"s used to delimit anchors. For example,
+
+  (ee-tolatin1-re \"\\253\\([!-~]\\)\\273\")
+
+should return a regexp for anchors that works in the current
+buffer. This is a hack and a work in progress!!! See the code for
+comments."
+    (let ((bfcs buffer-file-coding-system))
+      (cond ((eq bfcs 'iso-latin-1-unix) (ee-tolatin1 re))
+            ((eq bfcs 'raw-text-unix)    re)
+            ((eq bfcs 'utf-8-unix)       (ee-tolatin1 re))
+            (t                           re))))
+
+
+
 (provide 'eev-codings)
 
 
diff --git a/eev-elinks.el b/eev-elinks.el
index 301b082..cd9553a 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -154,8 +154,8 @@ This function is not very smart - it doesn't understand 
section names."
 ;;
 ;;    (find-elinks '((a sexp) "a string"))
 ;;
-;; In simple examples like this one each element in LIST becomes a
-;; line in the output string: sexps are prefixed by
+;; In simple examples like the one above each element in LIST becomes
+;; a line in the output string: sexps are prefixed by
 ;; `ee-hyperlink-prefix', and each string becomes a line. Try:
 ;;
 ;;    (find-elinks '((a sexp) (another) "" (sexp) "a string" "another"))
diff --git a/eev-intro.el b/eev-intro.el
index 8ad4fb0..4964772 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb22
+;; Version:    2019feb23
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -65,6 +65,7 @@
 ;; �.find-eev-intro�           (to "find-eev-intro")
 ;;
 ;; �.find-eval-intro�          (to "find-eval-intro")
+;; �.find-links-conv-intro�    (to "find-links-conv-intro")
 ;; �.find-links-intro�         (to "find-links-intro")
 ;; �.find-eepitch-intro�       (to "find-eepitch-intro")
 ;; �.find-wrap-intro�          (to "find-wrap-intro")
@@ -1733,24 +1734,25 @@ recommended reading order:
    3. (find-eev-intro)
    4. (find-eval-intro)
    5. (find-links-intro)
-   6. (find-eepitch-intro)
-   7. (find-wrap-intro)
-   8. (find-eejump-intro)
-   9. (find-anchors-intro)
-  10. (find-code-c-d-intro)
-  11. (find-pdf-like-intro)
-  12. (find-brxxx-intro)
-  13. (find-psne-intro)
-
-  14. (find-audiovideo-intro)
-  15. (find-multiwindow-intro)
-  16. (find-rcirc-intro)
-  17. (find-templates-intro)
-  18. (find-prepared-intro)
-  19. (find-bounded-intro)
-  20. (find-channels-intro)
-  21. (find-videos-intro)
-  22. (find-escripts-intro)
+   6. (find-links-conv-intro)
+   7. (find-eepitch-intro)
+   8. (find-wrap-intro)
+   9. (find-eejump-intro)
+  10. (find-anchors-intro)
+  11. (find-code-c-d-intro)
+  12. (find-pdf-like-intro)
+  13. (find-brxxx-intro)
+  14. (find-psne-intro)
+
+  15. (find-audiovideo-intro)
+  16. (find-multiwindow-intro)
+  17. (find-rcirc-intro)
+  18. (find-templates-intro)
+  19. (find-prepared-intro)
+  20. (find-bounded-intro)
+  21. (find-channels-intro)
+  22. (find-videos-intro)
+  23. (find-escripts-intro)
 
 Items 0, 3, 4, 5, 6, 9, 10, 11 should give you a good grasp of the
 main ideas - namely, that _elisp hyperlinks and interactive scripts
@@ -2191,20 +2193,20 @@ hyperlinks in scripts]
 
 
 
-;;;  _ _       _        
-;;; | (_)_ __ | | _____ 
-;;; | | | '_ \| |/ / __|
-;;; | | | | | |   <\__ \
-;;; |_|_|_| |_|_|\_\___/
-;;;                     
-;; (find-intro-links "links")
-;; �find-links-intro�  (to ".find-links-intro")
+;;;  _ _       _                                             _   _             
    
+;;; | (_)_ __ | | _____        ___ ___  _ ____   _____ _ __ | |_(_) ___  _ __  
___ 
+;;; | | | '_ \| |/ / __|_____ / __/ _ \| '_ \ \ / / _ \ '_ \| __| |/ _ \| '_ 
\/ __|
+;;; | | | | | |   <\__ \_____| (_| (_) | | | \ V /  __/ | | | |_| | (_) | | | 
\__ \
+;;; |_|_|_| |_|_|\_\___/      \___\___/|_| |_|\_/ \___|_| |_|\__|_|\___/|_| 
|_|___/
+;;;                                                                            
    
+;; �find-links-conv-intro� (to ".find-links-conv-intro")
+;; (find-intro-links "links-conv")
 
-(defun find-links-intro (&rest rest) (interactive)
-  (let ((ee-buffer-name "*(find-links-intro)*"))
-    (apply 'find-eintro "\
-\(Re)generate: (find-links-intro)
-Source code:  (find-eev \"eev-intro.el\" \"find-links-intro\")
+(defun find-links-conv-intro (&rest pos-spec-list) (interactive)
+  (let ((ee-buffer-name "*(find-links-conv-intro)*"))
+    (apply 'find-estring "\
+\(Re)generate: (find-links-conv-intro)
+Source code:  (find-efunction 'find-links-conv-intro)
 More intros:  (find-eev-quick-intro)
               (find-eval-intro)
               (find-eepitch-intro)
@@ -2213,9 +2215,10 @@ Is is meant as both a tutorial and a sandbox.
 
 
 
-Note: this intro needs to be rewritten!
-Ideally it should _complement_ the material in:
-  (find-eev-quick-intro \"3. Elisp hyperlinks\")
+This intro explains some conventions on the names and behaviors
+of the hyperlink functions of eev.
+
+
 
 
 
@@ -2267,7 +2270,130 @@ kinds of hyperlinks.
 
 
 
-2. Elisp hyperlinks: some conventions
+2. Learning to read 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
+
+  (find-efunction-links 'find-file)
+
+these hyperlinks
+
+  (find-efunctiondescr 'find-file)
+  (find-efunction 'find-file)
+  (find-efunctionpp 'find-file)
+  (find-efunctiond 'find-file)
+  (find-estring (documentation 'find-file))
+  (find-estring (documentation 'find-file t))
+  (find-fline (symbol-file 'find-file 'defun))
+
+calls \"basic\" eev hyperlink functions, that are just interfaces
+to Emacs function slightly tweaked into functions that follow
+eev's conventions - they are refinable, use the current window,
+etc. But these two,
+
+  (find-enode \"Command Index\" \"* find-file:\")
+  (find-elnode \"Index\" \"* find-file:\")
+
+are generated by calls to `code-c-d', as explained here:
+
+  (find-eev-quick-intro \"9.1. `code-c-d'\")
+  (find-eev-quick-intro \"9.1. `code-c-d'\" \"find-code-c-d\")
+
+Check:
+
+  (find-code-c-d \"e\"  ee-emacs-lisp-directory :info \"emacs\")
+  (find-code-c-d \"el\" ee-emacs-lisp-directory :info \"elisp\")
+
+The `code-*' functions define hyperlink functions whose names are
+of the form `find-{stem}{suffix}', and each of these `code-*'
+function has an associated `find-code-*' function that just
+displays what the corresponding `code-*' would execute. So one
+way to get acquainted to the most common of these suffixes is to
+follow these hyperlinks:
+
+  (find-code-c-d      \"CODE\" \"/DIR/\" :info \"INFO\")
+  (find-code-pdf-page \"CODE\" \"FILE.pdf\")
+  (find-code-pdf-text \"CODE\" \"FILE.pdf\")
+  (find-code-audio    \"CODE\" \"FILE\")
+  (find-code-video    \"CODE\" \"FILE\")
+
+From these only the functions whose suffixes end with \"sh\" or
+\"sh0\" and inherently dangerous; the others are usually safe if
+no hacks had been done.
+
+Some hyperlinks functions - for example the ones created by
+`code-pdf-page', `code-audio', etc - invoke external programs,
+and _may_ behave in bad ways when given unsafe arguments; these
+functions are implemented using the low-level functions
+`find-bgprocess' and `find-callprocess', which of course are
+unsafe too.
+
+Also, the functions `find-*-links', `find-*-intro' and
+`find-code-*' simply create temporary buffers, and are thus very
+safe - but, as always, think carefully before executing any code
+that they generate.
+
+
+
+
+3. Classification
+=================
+Here's one way to classify the hyperlink functions defined by
+eev. It's far from perfect, but that's how they are divided in
+the source files.
+
+We start from some observations:
+
+  a) The functions `code-c-d', `code-pdf-page' and
+     `code-pdf-text' define new hyperlink functions; we called
+     these new hyperlink functions \"short(er) hyperlinks\".
+
+  b) Functions like `find-efunction-links' create temporary
+     buffers with hyperlinks using `find-elinks', that is
+     described here:
+
+       (find-eev \"eev-elinks.el\" \"find-elinks\")
+
+  c) Functions like `find-latex-links' create temporary buffers
+     with hyperlinks plus templated text; they use `find-elinks'
+     and `ee-template0', that is described here:
+
+       (find-eev \"eev-wrap.el\" \"ee-template0\")
+
+  d) Functions like `find-sh' and `find-pdf-page' call external
+     processes.
+
+  e) `code-c-d' has a debugging function associated to it:
+     `find-code-c-d', that shows the \"templated code\" that the
+     corresponding `code-c-d' would execute. `code-pdf-page' has
+     `find-code-pdf-page' as its associated debugging function,
+     and so on.
+
+  f) If we call the hyperlinks in the items above \"non-basic\"
+     then we get - by exclusion! - a notion of what are \"basic
+     hyperlinks\".
+
+Here is the classification, with the class or idea at the left
+and a hyperlink to the source file at the right:
+
+  Basic hyperlinks:                 (find-eev \"eev-blinks.el\")
+  External processes:               (find-eev \"eev-plinks.el\")
+  `find-elinks':                    (find-eev \"eev-elinks.el\")
+  `find-elinks'+`ee-template0':     (find-eev \"eev-tlinks.el\")
+  `code-c-d' and `find-code-c-d':   (find-eev \"eev-code.el\")
+  `code-pdf*' and `find-code-pdf*': (find-eev \"eev-pdflike.el\")
+
+
+
+
+
+4. Elisp hyperlinks: some conventions
 =====================================
 One of the main ideas of eev is that elisp hyperlinks can be
 \"followed\" with `M-e', and we can _usually_ \"go back\" with `M-k'.
@@ -2312,8 +2438,8 @@ They:
 
 
 
-3. Elisp hyperlinks buffers
-===========================
+4.1. Conventions on hyperlinks buffers
+--------------------------------------
 Emacs has several help commands, whose bindings start with `C-h',
 that display their information in (temporary) \"help buffers\" -
 and in many cases these help buffers have hyperlinks, that can be
@@ -2389,8 +2515,8 @@ level of complexity.
 
 
 
-4. Templated text
-=================
+4.2. Conventions on templated text
+----------------------------------
 Some functions, like `find-latex-links', generate buffers that
 are composed of a series of elisp hyperlinks, as in the previous
 section, followed by some \"templated text\". Try to execute the
@@ -2455,36 +2581,8 @@ hyperlinks*\" buffer from a template that depends on an 
argument
 
 
 
-
-5. Functions for templated text
-===============================
-The function that is used to generate templated text from a
-string is called `ee-template0'. The function that generates a
-templated text from a list of sexps and strings is called
-`ee-links-to-string'. The function that generates an \"*Elisp
-hyperlinks*\" buffer from a list of sexps and strings is called
-`find-elinks'. They are explained, with examples, in the source
-code, at:
-
-  (find-eev \"eev-wrap.el\" \"ee-template0\")
-  (find-eev \"eev-elinks.el\" \"find-elinks\")
-  (find-eev \"eev-elinks.el\" \"find-elinks\" \"ee-links-to-string\")
-
-Some functions like `find-latex-links' generate buffers with
-elisp hyperlinks at the top, some templated text meant to be
-saved to a file at the bottom, and with a call to `ee-copy-rest'
-separating the top part from the bottom part. The `ee-copy-rest'
-is explained in detail here:
-
-  (find-eev \"eev-tlinks.el\" \"ee-copy-rest\")
-
-
-
-
-
-
-6. Elisp hyperlinks buffers conventions
-=======================================
+4.3. Elisp hyperlinks buffers vs. Help buffers
+----------------------------------------------
 Let's refer to Emacs's help buffers as \"C-h buffers\" and to
 eev's elisp hyperlink buffers as \"M-h buffers\". Here is a quick
 list of the main differences and conventions; some of them will
@@ -2541,8 +2639,74 @@ be expanded later:
      string in `ee-hyperlink-prefix'.
 
 
+" pos-spec-list)))
+
+;; (find-links-conv-intro)
+
+
+
 
-7. `find-here-links'
+
+
+;;;  _ _       _        
+;;; | (_)_ __ | | _____ 
+;;; | | | '_ \| |/ / __|
+;;; | | | | | |   <\__ \
+;;; |_|_|_| |_|_|\_\___/
+;;;                     
+;; (find-intro-links "links")
+;; �find-links-intro�  (to ".find-links-intro")
+
+(defun find-links-intro (&rest rest) (interactive)
+  (let ((ee-buffer-name "*(find-links-intro)*"))
+    (apply 'find-eintro "\
+\(Re)generate: (find-links-intro)
+Source code:  (find-eev \"eev-intro.el\" \"find-links-intro\")
+More intros:  (find-eev-quick-intro)
+              (find-eval-intro)
+              (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
+
+
+
+Note: this intro is being rewritten!
+Ideally it should _complement_ the material in:
+  (find-eev-quick-intro \"3. Elisp hyperlinks\")
+
+
+
+
+
+
+
+
+5. Functions for templated text
+===============================
+The function that is used to generate templated text from a
+string is called `ee-template0'. The function that generates a
+templated text from a list of sexps and strings is called
+`ee-links-to-string'. The function that generates an \"*Elisp
+hyperlinks*\" buffer from a list of sexps and strings is called
+`find-elinks'. They are explained, with examples, in the source
+code, at:
+
+  (find-eev \"eev-wrap.el\" \"ee-template0\")
+  (find-eev \"eev-elinks.el\" \"find-elinks\")
+  (find-eev \"eev-elinks.el\" \"find-elinks\" \"ee-links-to-string\")
+
+Some functions like `find-latex-links' generate buffers with
+elisp hyperlinks at the top, some templated text meant to be
+saved to a file at the bottom, and with a call to `ee-copy-rest'
+separating the top part from the bottom part. The `ee-copy-rest'
+is explained in detail here:
+
+  (find-eev \"eev-tlinks.el\" \"ee-copy-rest\")
+
+
+
+
+8. `find-here-links'
 ====================
 The most important of the commands that generates buffers with elisp
 hyperlinks - \"M-h commands\", in the terminology explained above - is
@@ -2631,7 +2795,7 @@ can compare the different cases using just <up>, <down>, 
and M-e.
 
 
 
-6. `find-here-links': usage patterns
+9. `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
@@ -2684,78 +2848,8 @@ and step (3) sometimes gives several sexps for us to 
choose from]
 
 
 
-7. 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
-
-  (find-efunction-links 'find-file)
-
-these hyperlinks
-
-  (find-efunctiondescr 'find-file)
-  (find-efunction 'find-file)
-  (find-efunctionpp 'find-file)
-  (find-efunctiond 'find-file)
-  (find-estring (documentation 'find-file))
-  (find-estring (documentation 'find-file t))
-  (find-fline (symbol-file 'find-file 'defun))
-
-calls \"basic\" eev hyperlink functions, that are just interfaces
-to Emacs function slightly tweaked into functions that follow
-eev's conventions - they are refinable, use the current window,
-etc. But these two,
-
-  (find-enode \"Command Index\" \"* find-file:\")
-  (find-elnode \"Index\" \"* find-file:\")
-
-are generated by calls to `code-c-d' or similar functions, that
-generate some elisp code as text, from templates, and evaluate
-that code, as explained here:
-
-  (find-code-c-d-intro)
-  (find-pdf-like-intro)
-  (find-audiovideo-intro)
-
-The `code-*' functions define hyperlink functions whose names are
-of the form `find-{stem}{suffix}', and each of these `code-*'
-function has an associated `find-code-*' function that just
-displays what the corresponding `code-*' would execute. So one
-way to get acquainted to the most common of these suffixes is to
-follow these hyperlinks:
-
-  (find-code-c-d      \"CODE\" \"/DIR/\" :info \"INFO\")
-  (find-code-pdf      \"CODE\" \"FILE.pdf\")
-  (find-code-pdf-text \"CODE\" \"FILE.pdf\")
-  (find-code-audio    \"CODE\" \"FILE\")
-  (find-code-video    \"CODE\" \"FILE\")
-
-From these only the functions whose suffixes end with \"sh\" or
-\"sh0\" and inherently dangerous; the others are usually safe if
-no hacks had been done.
-
-Some hyperlinks functions - for example the ones created by
-`code-pdf', `code-audio', etc - invoke external programs, and
-_may_ behave in bad ways when given unsafe arguments; these
-functions are implemented using the low-level functions
-`find-bgprocess' and `find-callprocess', which of course are
-unsafe too.
-
-Also, the functions `find-*-links', `find-*-intro' and
-`find-code-*' simply create temporary buffers, and are thus very
-safe - but, as always, think carefully before executing any code
-that they generate.
-
-
-
-
-8. ee-hyperlink-prefix
-======================
+11. ee-hyperlink-prefix
+=======================
 `ee-hyperlink-prefix' is both a variable and a function that
 helps us set that variable; it started to an experiment on how to
 create an alternative to `M-x customize' and ended up becoming
@@ -2793,8 +2887,8 @@ Try this, with `M-2 M-e' on each line:
 
 
 
-9. The first line regenerates the buffer
-========================================
+12. The first line regenerates the buffer
+=========================================
 \[To do: explain this convention with examples; explain the
 conventions for the \"variants of the first line\"\]
 
@@ -2807,7 +2901,7 @@ conventions for the \"variants of the first line\"\]
 
 
 
-10. Pointing to where we are now
+13. Pointing to where we are now
 ================================
 Several of the `M-h' commands are mainly meant to help us
 generate hyperlinks to \"where we are now\": to the current file,
@@ -2850,9 +2944,8 @@ buffer, and so on. They don't try to be very smart -
 
 
 
-11. The rest of the buffer
+14. The rest of the buffer
 ==========================
-
 Several elisp hyperlinks buffers are composed of two parts: a
 series of links at the top, and then a template-generated text
 that is mean to be copied to somewhere else. The canonical
@@ -7437,29 +7530,27 @@ Is is meant as both a tutorial and a sandbox.
 
 
 
-See: (find-eev \"eev.el\")
-     http://angg.twu.net/eev.html
-     http://angg.twu.net/eev-article.html
-     http://angg.twu.net/emacs.html#what-is-eev
-     https://www.gnu.org/brave-gnu-world/issue-13.html
-     http://angg.twu.net/eev-manifesto.html
-
 Eev's central idea is that you can keep \"executable logs\" of
 what you do, in a format that is reasonably readable and that is
 easy to \"play back\" later, step by step and in any order. We
-call these executable logs \"e-scripts\", and this is an
-introduction to some of the most usual formats for e-scripts.
+call these executable logs \"e-scripts\".
+
+This tutorial is an introduction to some of the most usual
+formats for e-scripts:
 
+  1) files with e-script blocks,
+  2) files with elisp hyperlinks,
+  3) source files with eepitch blocks in multi-line comments.
 
-We start with a section on
-how to \"read\" existing e-scripts, and then we give some hints
-to help you start \"writing\" your own e-scripts, first in a
-single file and then on several files.
+
+We start with a section on how to \"read\" existing e-scripts,
+and then we give some hints to help you start \"writing\" your
+own e-scripts, first in a single file and then on several files.
 
 A typical e-script - like the ones in http://angg.twu.net/e/ - is
 made of an index followed by a series of \"e-script blocks\".
 Here is a miniature example, with an index with two entries
-followed by two e-script blocks:
+followed by two e-script blocks (...)
 
 
 
@@ -7479,18 +7570,18 @@ few days after that I wrote a function - that I could 
invoke as
 \"~/ee.sh\", and I had an alias `ee' in my shell that would
 execute the contents of that file in verbose mode, i.e., showing
 each line before executing it. \"Eev\" meant
-\"Emacs-execute-verbosely\", but `M-x eev' only saved some
+\"Emacs-execute-verbosely\", but `M-x eev' only saved a block of
 commands into \"~/ee.sh\"; to execute them I had to switch to a
-terminal and type \"eev\". If the function `eev' was called with
-a string argument instead of being called interactively it would
+terminal and type \"ee\". If the function `eev' was called with a
+string argument instead of being called interactively it would
 write that string to \"~/ee.sh\"; a sexp like
 
   (eev \"man tar\")
 
 was a very primitive hyperlink to the manpage for \"tar\". I
 wrote extensions to these ideas gradually, and for YEARS I was
-absolutery sure that Emacs was meant to be used exactly in that
-way, and that everybody used elisp code as hyperlinks. At some
+absolutely sure that Emacs was meant to be used exactly in that
+way, and that EVERYBODY used elisp code as hyperlinks. At some
 point in 1999 I sent a message to a mailing list about Emacs, and
 I casually apologized for using my own functions - with weird
 names - for elisp hyperlinks and for saving code to be sent to a
@@ -7505,7 +7596,8 @@ document my code so that it could be included in Emacs.
 
 Eev is not yet an official part of Emacs (long story!) and
 eepitch practically replaced `M-x eev' as a way to execute shell
-commands.
+commands. See: (find-prepared-intro)
+
 
 
 
@@ -7547,10 +7639,6 @@ something that I was trying to understand, or trying to 
do.
 
 
 
-
-
-
-
 mark these commands and
 execute them with M-x eev; and if we have the habit of using eev
 and we are writing code in, say, C or Lua we will often put elisp
@@ -7562,15 +7650,12 @@ where these comment blocks are delimited by --(( and
 --))s, we can have a block like
 
 
-
-
-
-
-
-
-
-
-I knew a bit of Lisp, and after just a few hours
+See: (find-eev \"eev.el\")
+     http://angg.twu.net/eev.html
+     http://angg.twu.net/eev-article.html
+     http://angg.twu.net/emacs.html#what-is-eev
+     https://www.gnu.org/brave-gnu-world/issue-13.html
+     http://angg.twu.net/eev-manifesto.html
 
 
 
diff --git a/eev-mode.el b/eev-mode.el
index a7338fc..e554de0 100644
--- a/eev-mode.el
+++ b/eev-mode.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb13
+;; Version:    2019feb23
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-mode.el>
@@ -107,6 +107,7 @@ and: (find-eval-intro \"`M-k'\")"
   (define-key eev-mode-map "\M-h\M-h" 'find-here-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-n" 'find-eunicodeucs)
   (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)      
diff --git a/eev-wrap.el b/eev-wrap.el
index 00e3d79..1e6b7c6 100644
--- a/eev-wrap.el
+++ b/eev-wrap.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019feb09
+;; Version:    2019feb24
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-wrap.el>
@@ -100,13 +100,31 @@ The name of this function comes from the \"S\" in 
`(format \"%S\" <obj>)'."
 ;;;                                   |_|                          
 ;;
 ;; �ee-template0� (to ".ee-template0")
-;; Tests:
+;; The functions `ee-template00' and `ee-template0' are used by
+;; several functions of the `eewrap-*' family and also by functions
+;; like `find-latex-links', that create a temporary buffer with elisp
+;; hyperlinks followed by a "templated string". In low-level terms,
+;;
+;;   (ee-template00 STR)
+;;
+;; replace substrings enclosed by `{}'s in STR by the result of
+;; evaluating them; in particular, it replaces each `{VAR}' in STR by
+;; the contents of the variable VAR. Here are some examples/tests:
+;;
 ;;   (ee-template00 "a{(+ 2 3)}b")
 ;;     -->  "a5b"
 ;; 
 ;;   (let ((hi "Here: ") (a 22) (b 33)) (ee-template00 "{hi}{a}+{b}={(+ a 
b)}"))
+;;       -->  "Here: 22+33=55"
+;;
+;;   (defun foo (a b) (ee-template00 "{a}+{b}={(+ a b)}"))
+;;   (foo 22 33)
 ;;       -->  "22+33=55"
 ;;
+;; `ee-template0' is like `ee-template00' but it adds a trick that
+;; makes each "{<}" and each "{>}" in STR be replaced by "{" and "}"
+;; respectively. For example:
+;;
 ;;   (ee-template0 "{<} a{(+ 2 3)} {>}")
 ;;       -->  "{ a5 }"