[elpa] externals/eev b0f124e 48/64: Added material to `find-escripts-intro' and `find-eev-quick-intro'.

[Stefan Monnier]

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

    Added material to `find-escripts-intro' and `find-eev-quick-intro'.
---
 ChangeLog     |   7 ++++
 VERSION       |   4 +-
 eejump.el     | 104 +++++++++++++++++++++++++++++++---------------------
 eepitch.el    |   3 +-
 eev-elinks.el |   3 +-
 eev-intro.el  | 116 ++++++++++++++++++++++++++++++++++++++++------------------
 6 files changed, 155 insertions(+), 82 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ce4c797..e153724 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2019-03-03  Eduardo Ochs  <address@hidden>
+
+       * eev-elinks.el (ee-find-intro-links): set the correct default
+       value for `stem'.
+
+       * eejump.el (eejump-6): point to (find-escripts-intro).
+
 2019-03-02  Eduardo Ochs  <address@hidden>
 
        * eev-anchors.el: converted to utf-8.
diff --git a/VERSION b/VERSION
index ddb55e6..00ed0a0 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sun Mar  3 00:17:28 GMT 2019
-Sat Mar  2 21:17:28 -03 2019
+Mon Mar  4 00:46:47 GMT 2019
+Sun Mar  3 21:46:47 -03 2019
diff --git a/eejump.el b/eejump.el
index af08c1f..1058d86 100644
--- a/eejump.el
+++ b/eejump.el
@@ -1,6 +1,6 @@
 ;;; eejump.el -- jump quickly to predefined places.
 
-;; Copyright (C) 2012,2016 Free Software Foundation, Inc.
+;; Copyright (C) 2012,2016,2019 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:    2019feb13
+;; Version:    2019mar03
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eejump.el>
@@ -34,20 +34,52 @@
 
 ;;; Commentary:
 
-;; See: (find-eev-quick-intro "7.1. `eejump'")
-;;      (find-eev-quick-intro "7.1. `eejump'" "meta-uppercase-j")
-;;      (find-eev-quick-intro "7.2. The list of eejump targets")
-;;      (find-eevfile "eev-mode.el" "M-j" "eejump")
-;;      (find-eevfile "eev-mode.el" "M-J" "eewrap-eejump")
-;;      (find-eejump-intro)
-;; Some features are defined elsewhere:
-;;      (find-eev "eev-blinks.el" "find-eejumps")
-;;      (find-eev "eev-wrap.el" "eewrap-eejump")
-
- 
+;; This file defines `eejump', that is bound to `M-j'. Its usage is
+;; explained here:
+;;
+;;   (find-eev-quick-intro "7.1. `eejump'")
+;;   (find-eev-quick-intro "7.2. The list of eejump targets")
+;;
+;; The functions `find-eejumps' - that is invoked when we type `M-j'
+;; without an argument - and `eewrap-eejump' - invoked by `M-J' - are
+;; defined in other files:
+;;
+;;   (find-eev "eev-mode.el" "eev-mode-map-set" "M-j" "eejump")
+;;   (find-eev "eev-mode.el" "eev-mode-map-set" "M-J" "eewrap-eejump")
+;;   (find-eev "eev-blinks.el" "find-eejumps")
+;;   (find-eev "eev-wrap.el" "eewrap-eejump")
+;;
+;; See:
+;;
+;;   (find-eev-quick-intro "7.3. Defining eejump targets")
+;;   (find-eev-quick-intro "7.3. Defining eejump targets" "M-J")
+;;
+;; `find-eejumps' is a relatively new idea, and before implementing it
+;; `M-j' did something MUCH harder to explain. Suppose that
+;;
+;;   * `eejump-12345' was not defined,
+;;   * `eejump-1234' was not defined,
+;;   * `eejump-123' was not defined,
+;;   * `eejump-12*' was defined in my .emacs as:
+;;     (defun eejump-12* () (find-efunction 'eejump-12*))
+;;
+;; then typing `M-12345j' would run (find-efunction 'eejump-12*), that
+;; would jump to the definition of a `eejump-12*' in my .emacs; I
+;; would put all my definitions of eejumps with prefixes starting with
+;; "12" close to it. This (old) intro still describes that behavior:
+;;
+;;   (find-eejump-intro)
+;;   (find-eejump-intro "5. eejump blocks")
+
+
+
+;; (define-key eev-mode-map "\M-j" 'eejump)
+;;
 (defun eejump (arg)
-  "See: (find-eev-quick-intro \"7.1. `eejump'\")
-and: (find-eejump-intro)"
+  "Execute the one-liner associated to the numeric argument ARG.
+When called without an argument execute `find-eejumps', that
+shows all the current one-liners associated to numbers.
+See: (find-eev-quick-intro \"7.1. `eejump'\")"
   (interactive "P")
   (if (null arg)
       (find-eejumps)                   ; was: (eejump-*)
@@ -66,48 +98,36 @@ See: (find-eejump-intro \"\\neejump\\n\")"
 
 
 
-;; This is an "eejump block", as described in:
-;;   (find-eejump-intro "eejump blocks")
-;; You should probably copy this to your .emacs - and
-;; then start modifying it.
-;;
-;; Note that with eev-mode you can use:
-;;   M-e to follow elisp hyperlinks,   see: (find-eval-intro "`M-e'")
-;;   M-k to go back,                   see: (find-eval-intro "`M-k'")
-;;   M-j to jump to predefined places, see: (find-eejump-intro "Families")
-;;                  in particular:  M-j --> (find-efunction 'eejump-*)
-;;                                 M-2j --> (find-emacs-intro)
-;;                                 M-5j --> (find-eev-intro)
-;;                                M-50j --> (find-eev "eev-readme.el")
-;;
 (defun eejump-*   () (find-efunction 'eejump-*))
 (defun eejump-1   () (find-fline "~/TODO"))
-(defun eejump-10  () (set-frame-font "5x7"  t))
-(defun eejump-11  () (set-frame-font "6x13" t))
 (defun eejump-2   () (find-emacs-keys-intro))
-(defun eejump-5*  () (find-efunction 'eejump-5*))
 (defun eejump-5   () (find-eev-quick-intro))
-(defun eejump-50  () (find-eev "eev-readme.el"))
-(defun eejump-59  () (find-eev-update-links))
-(defun eejump-6   () (find-freenode    "#eev"))
-(defun eejump-66  () (find-freenode-3a "#eev"))
+(defun eejump-6   () (find-escripts-intro))
+
+(defun eejump-10  () (set-frame-font "5x7"  t))
+(defun eejump-11  () (set-frame-font "6x13" t))
+(defun eejump-12  () (set-frame-font "10x20" t))
 
 (defun eejump-55  () (find-fline "~/.emacs"))
-(defun eejump-552 () (find-eev "eev2-all.el"))
 (defun eejump-555 () (find-eev ""))
 
+;; Deleted:
+;; (defun eejump-50  () (find-eev "eev-readme.el"))
+;; (defun eejump-59  () (find-eev-update-links))
+;; (defun eejump-5*  () (find-efunction 'eejump-5*))
+;; (defun eejump-6   () (find-freenode    "#eev"))
+;; (defun eejump-66  () (find-freenode-3a "#eev"))
+;; (defun eejump-552 () (find-eev "eev2-all.el"))
 
 
+;; To see all current targets, run:
+;;   (find-eejumps)
 
 (provide 'eejump)
 
-;; To see all current targets, run:
-;;   (find-eejumps)
 
 
-
 ;; Local Variables:
-;; coding:            raw-text-unix
-;; ee-anchor-format:  "defun %s "
+;; coding:            utf-8-unix
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eepitch.el b/eepitch.el
index 654dbf3..4bc5f83 100644
--- a/eepitch.el
+++ b/eepitch.el
@@ -764,7 +764,6 @@ This is useful for for running processes that use pagers 
like
 
 
 ;; Local Variables:
-;; coding:            raw-text-unix
-;; ee-anchor-format:  "defun %s "
+;; coding:            utf-8-unix
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eev-elinks.el b/eev-elinks.el
index b56e1d5..4577534 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar02
+;; Version:    2019mar03
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -553,6 +553,7 @@ This can be used to test if the current buffer is an intro 
buffer."
 
 ;; Test: (find-elinks (ee-find-intro-links "FOO"))
 (defun ee-find-intro-links (&optional stem)
+  (setq stem (or stem (ee-intro-stem)))
   (let ((find-xxx-intro (ee-intern "find-%s-intro" stem))
        (url (format "http://angg.twu.net/eev-intros/find-%s-intro.html"; stem)))
     `(,(ee-H url)
diff --git a/eev-intro.el b/eev-intro.el
index b109349..5fb50fe 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar02
+;; Version:    2019mar03
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -781,9 +781,50 @@ literal ^O in a buffer by typing `C-q C-o'.
 7. Quick access to one-liners
 =============================
 
-
 7.1. `eejump'
 -------------
+Some key sequences in Emacs accept numeric arguments. For
+example, try typing `M-9 a' (not `M-9 M-a'!) - this will insert 9
+copies of the letter `a'. See:
+
+  (find-enode \"Arguments\")
+
+Eev binds the key `M-j' (`eejump') to a function that jumps to a
+place that depends on the numeric argument. For example, `M-5
+M-j' runs (find-eev-quick-intro), that reloads this intro and
+goes to the top of it, and
+
+  `M-2 M-j' runs: (find-emacs-keys-intro)
+  `M-6 M-j' runs: (find-escripts-intro)
+  `M-1 M-j' runs: (find-fline \"~/TODO\")
+
+The way to associate a number to a place to jump to - or, more
+precisely, to a single-line piece of Elisp code, i.e., a
+\"one-liner\" - is through code like this:
+
+  (defun eejump-5 () (find-eev-quick-intro))
+  (defun eejump-2 () (find-emacs-keys-intro))
+  (defun eejump-6 () (find-escripts-intro))
+  (defun eejump-1 () (find-fline \"~/TODO\"))
+
+The pattern is:
+
+  (defun eejump-<nnn> () <one-liner associated to the argument nnn>)
+
+`defun' is explained here:
+
+  (find-elnode \"Defining Functions\" \"(defun foo () 5)\")
+
+As a special case, a plain `M-j' without a prefix argument runs a
+special function, `find-eejumps', that shows a help text followed
+by all the `(defun eejump-<nnn> () ...)'s that are currently
+active. So:
+
+      `M-j' runs: (find-eejumps)
+
+Let's try to understand this from both a user's point of view and
+from a technical point of view.
+
 We may have elisp one-liners that we want to be able to execute very
 quickly, and from anywhere. For example, I keep all my notes that I
 have not organized yet in a file called \"~/TODO\", and if I type
@@ -816,14 +857,14 @@ the `1' and the `j'.
 Internally, what happens when you type `M-1 M-j' is this:
 
   `M-j' is bound to `eejump',
-  `M-1 M-j' runs `eejump' with argument 1, i.e., (eejump 1)
-  (eejump 1) runs (eejump-1)
+  `M-1 M-j' runs `eejump' with argument 1, i.e., (eejump 1),
+  (eejump 1) runs (eejump-1),
   (eejump-1) has been defined with:
 
     (defun eejump-1 () (find-fline \"~/TODO\"))
 
-So `M-1 M-j' runs the one-liner `(find-fline \"~/TODO\")',
-`M-5 M-j' runs the one-liner `(find-eev-quick-intro)',
+So `M-1 M-j' runs the one-liner `(find-fline \"~/TODO\")'.
+Similarly, `M-5 M-j' runs the one-liner `(find-eev-quick-intro)',
 and so on.
 
 
@@ -831,8 +872,8 @@ and so on.
 7.2. The list of eejump targets
 -------------------------------
 If you type `M-j' without a prefix argument then it runs
-`(find-eejumps)', that displays all the current eejump targets as
-defuns, one in each line. Try it:
+`(find-eejumps)', that displays a help text followed by all the
+current eejump targets as defuns, one in each line. Try it:
 
   (eek \"M-j\")
   (find-eejumps)
@@ -877,9 +918,9 @@ next section. Try it now:
 Let's start with an example. If we are editing a LaTeX file, say
 \"/tmp/foo.tex\", then it is convenient to have quick ways to:
 
-  c) compile \"foo.tex\" into a \"foo.pdf\",
-  d) display the resulting \"foo.pdf\",
-  e) jump to \"foo.tex\" from anywhere to edit it.
+  c) [c]ompile \"foo.tex\" into a \"foo.pdf\",
+  d) [d]isplay the resulting \"foo.pdf\",
+  e) jump to \"foo.tex\" from anywhere to [e]dit it.
 
 If our \"/tmp/foo.tex\" starts with these lines
 
@@ -3599,12 +3640,14 @@ 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 \"7.1. `eejump'\")
+See the comments in:
+  (find-eev \"eejump.el\")
 
 
 
 
-The problem
-===========
+1. The problem
+==============
 Suppose that we have several files that we are working on, and we
 want a quick way to jump to (i.e., to visit) any of them with
 very few keystrokes; moreover,
@@ -3645,8 +3688,8 @@ items to our wishlist:
 
 
   
-A miniature
-===========
+2. A miniature
+==============
 My original solution was this: I used only one keybinding, `M-j',
 that acted differently when invoked with different numeric
 prefixes; when invoked as `M-1 M-j' it opened a certain file,
@@ -3688,8 +3731,8 @@ add new options temporarily...
 
 
 
-Families
-========
+3. Families
+===========
 Let's use a shorthand for key sequences: for example, `M-123j'
 instead of `M-1 M-2 M-3 M-j'.
 
@@ -3719,8 +3762,8 @@ satisfy these two (new!) wishlist items:
 
 
 
-eejump
-======
+4. `eejump'
+===========
 The definition of `eejump' that comes with eev is a bit more
 complex than the one given above, and it will not be shown
 here (it involves a tricky recursive function) but it satisfies
@@ -3759,8 +3802,8 @@ error like \"Don't know where `eejump-99*' is defined\"...
 
 
 
-eejump blocks
-=============
+5. eejump blocks
+================
 Let's a call a sequence of defuns for eejumps with the same
 prefix, like this, starting with a `(defun eejump-<prefix>* ...)',
 
@@ -3782,8 +3825,8 @@ modifying them.
 
 
 
-Making an `eejump-nn*' work
-===========================
+6. Making an `eejump-nn*' work
+==============================
 If you execute a line like 
 
   (defun eejump-9* () (find-efunction 'eejump-9*))
@@ -3815,8 +3858,8 @@ to the right places. See also:
 
 
 
-Producing `eejump-nnn's and `eejump-nnn*'s
-==========================================
+7. Producing `eejump-nnn's and `eejump-nnn*'s
+=============================================
 Look again to the block of six \"defun\"s above. Now type `M-J'
 on each of the six lines below:
 
@@ -3849,8 +3892,8 @@ get useless definitons.
 
 
 
-Permanent and temporary
-=======================
+8. Permanent and temporary
+==========================
 If you create a block like the block of six defuns above in your
 .emacs file then you'll be attributing a \"permanent\" meaning to
 `M-91j', ..., `M-992j', and if you create it in a file that is
@@ -7626,6 +7669,7 @@ More intros:  (find-eev-quick-intro)
               (find-eev-intro)
 This buffer is _temporary_ and _editable_.
 Is is meant as both a tutorial and a sandbox.
+The quickest way to open or recreate this is with `M-6 M-j'.
 
 
 
@@ -8078,11 +8122,13 @@ block, after the hyperlinks to files from that package)
 ==============================
 One of my favorite ways of describing eev is as a \"tool to
 create executable logs\", but this only make sense if we clarify
-some ideas and terms. The e-script in Example 1 has two e-script
-blocks plus an index. The fist block has notes about installing
-the packages for Lua5.1 in Debian and inspecting them, and the
-second block is about downloading and using an eev-based Lua
-tutorial. Let's think of each of these blocks as a _task_.
+some ideas and terms.
+
+The e-script in Example 1 has two _e-script blocks_ plus an
+_index_. The fist block has notes about installing the packages
+for Lua5.1 in Debian and inspecting them, and the second block is
+about downloading and using an eev-based Lua tutorial. Let's
+think of each of these blocks as a _task_.
 
 The task \"install Lua5.1\" is performed in one way if we're
 doing it for the first time, and in a different was if we're
@@ -8110,9 +8156,9 @@ an e-script block is \"executable\". But in what sense it 
is a
      there was nothing automatic in taking notes with them. We
      would have to decide what to write and how to write it, and
      we would have to alternate between the \"task\" and \"taking
-     notes\". After many years of practice people _some_ people
-     would learn how to take notes without distract themselves
-     much from the task at hand, and they would learn how to make
+     notes\". After many years of practice _some_ people would
+     learn how to take notes without distract themselves much
+     from the task at hand, and they would learn how to make
      their notes at the same time concise and readable enough.
 
   2. Nowadays, with computers, there are _some_ ways to write