[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/eev 5dbba21 40/64: Added `find-eunicodeucs'; added lots
From: |
Stefan Monnier |
Subject: |
[elpa] externals/eev 5dbba21 40/64: Added `find-eunicodeucs'; added lots of documentation. |
Date: |
Sun, 7 Apr 2019 16:59:09 -0400 (EDT) |
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 }"
- [elpa] externals/eev fb9f4c6 64/64: Added an explanation of why eev is not in ELPA yet., (continued)
- [elpa] externals/eev fb9f4c6 64/64: Added an explanation of why eev is not in ELPA yet., Stefan Monnier, 2019/04/07
- [elpa] externals/eev b0f124e 48/64: Added material to `find-escripts-intro' and `find-eev-quick-intro'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 9d39df9 36/64: Several clean-ups in eev-elinks.el and eev-tlinks.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 39a2cea 60/64: New file: eev-template0.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev c77ca3b 27/64: Rewrote eev-pdflike.el, added sections about it to (find-eev-quick-intro)., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 7162184 51/64: Added `find-texworkspdf-page'., Stefan Monnier, 2019/04/07
- [elpa] externals/eev b9baae6 17/64: First commit after an HD crash; lots of changes, Stefan Monnier, 2019/04/07
- [elpa] externals/eev 2518e75 50/64: Use "eev-beginner.el" instead of "eev-readme.el"., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 51e636a 63/64: Deleted eev-pdflike-old.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev b56266f 54/64: Added `eev-beginner' (our first autoload)., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 5dbba21 40/64: Added `find-eunicodeucs'; added lots of documentation.,
Stefan Monnier <=
- [elpa] externals/eev 14d1125 46/64: Converted several elisp files to utf-8., Stefan Monnier, 2019/04/07
- [elpa] externals/eev 22702eb 31/64: Made all secondary intros point to sections of find-eev-quick-intro., Stefan Monnier, 2019/04/07
- [elpa] externals/eev a5f9343 30/64: Small changes in `find-eev-install-links' and in eev-intro.el., Stefan Monnier, 2019/04/07
- [elpa] externals/eev af88c9b 01/64: Initial commit for eev2, Stefan Monnier, 2019/04/07