[elpa] externals/eev 01b2212 13/20: Rewrote `(find-anchors-intro)'.

[Stefan Monnier]

branch: externals/eev
commit 01b221292075ff372b04d29de809c0d10772f4da
Author: Eduardo Ochs <eduardoochs@gmail.com>
Commit: Eduardo Ochs <eduardoochs@gmail.com>

    Rewrote `(find-anchors-intro)'.
---
 ChangeLog         |   4 ++
 VERSION           |   4 +-
 eev-audiovideo.el |   1 -
 eev-edit.el       |  18 +++++-
 eev-intro.el      | 182 +++++++++++++++++++++++++++---------------------------
 eev-tlinks.el     |   3 +-
 6 files changed, 116 insertions(+), 96 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f4f583b..a3aff24 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2020-12-28  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-intro.el (find-anchors-intro): rewrote completely.
+
 2020-12-22  Eduardo Ochs  <eduardoochs@gmail.com>
 
        * eev-hlinks.el (ee-find-dired-links): new function.
diff --git a/VERSION b/VERSION
index 4fb5ea7..94bb1da 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Tue Dec 22 05:13:31 GMT 2020
-Tue Dec 22 02:13:32 -03 2020
+Mon Dec 28 05:27:26 GMT 2020
+Mon Dec 28 02:27:26 -03 2020
diff --git a/eev-audiovideo.el b/eev-audiovideo.el
index ccd229f..8c10628 100644
--- a/eev-audiovideo.el
+++ b/eev-audiovideo.el
@@ -454,7 +454,6 @@ See: (find-audiovideo-intro \"`eev-avadj-mode'\")"
 (defun ee-find-mpv-video (fname &optional pos &rest rest)
   `("mpv"
     ,fname
-    ;; ,@(if pos `("--start" ,(ee-secs-to-mm:ss pos)))
     ,@(if pos (list (format "--start=%s" (ee-secs-to-mm:ss pos))))
     ,@ee-mpv-video-options
     ))
diff --git a/eev-edit.el b/eev-edit.el
index 265401f..888e14e 100644
--- a/eev-edit.el
+++ b/eev-edit.el
@@ -1,6 +1,6 @@
 ;;; eev-edit.el -- tools for editing (mainly refining) elisp hyperlinks.
 
-;; Copyright (C) 2012-2019 Free Software Foundation, Inc.
+;; Copyright (C) 2012-2020 Free Software Foundation, Inc.
 ;;
 ;; This file is part of GNU eev.
 ;;
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    2019sep27
+;; Version:    2020dec28
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-edit.el>
@@ -60,6 +60,8 @@
 ;;
 ;; «ee-duplicate-this-line» (to ".ee-duplicate-this-line")
 ;; (define-key eev-mode-map "\M-h\M-2" 'ee-duplicate-this-line)
+;; See: (find-refining-intro "2. Refining hyperlinks")
+;;      (find-refining-intro "2. Refining hyperlinks" "M-h M-2")
 
 (defun ee-duplicate-this-line ()
   "Duplicate the current line (without any changes to the kill ring)."
@@ -77,6 +79,9 @@
 ;;
 ;; «ee-yank-pos-spec» (to ".ee-yank-pos-spec")
 ;; (define-key eev-mode-map "\M-h\M-y" 'ee-yank-pos-spec)
+;; See: (find-refining-intro "2. Refining hyperlinks")
+;;      (find-refining-intro "2. Refining hyperlinks" "M-h M-y")
+;;      (find-refining-intro "yanks" "the text at the end of the sexp")
 
 (defun ee-yank-pos-spec ()
   "Append the top of the kill ring to a hyperlink sexp, as a Lisp string.
@@ -121,6 +126,8 @@ and you copy that hyperlink to a more permanent place."
 ;;
 ;; «ee-copy-this-line-to-kill-ring» (to ".ee-copy-this-line-to-kill-ring")
 ;; (define-key eev-mode-map "\M-h\M-w" 'ee-copy-this-line-to-kill-ring)
+;; See: (find-refining-intro "3. Three buffers")
+;;      (find-refining-intro "3. Three buffers" "M-h M-w")
 
 (defun ee-copy-this-line-to-kill-ring (&optional arg)
   "Copy the current line to the kill ring and highlight (\"flash\") it.
@@ -136,7 +143,10 @@ With a prefix argument run 
`ee-copy-preceding-tag-to-kill-ring' instead."
       (message msg))))
 
 
+
 ;; Experimental, 2019aug29
+;; See: (find-anchors-intro "3. The preceding tag")
+;;
 ;; (defun ee-tag-re () (ee-tolatin1 "«\\([!-~]+\\)»"))
 (defvar ee-tag-re-utf-8 "«\\([!-~]+\\)»")
 (defun  ee-tag-re () ee-tag-re-utf-8)
@@ -168,6 +178,7 @@ A \"tag\" is the string between \"«»\"s in an anchor."
 ;;;                              
 ;; «ee-shrink-hyperlink-at-eol» (to ".ee-shrink-hyperlink-at-eol")
 ;; (define-key eev-mode-map "\M-h\M--" 'ee-shrink-hyperlink-at-eol)
+;; See: (find-anchors-intro "2. Shrinking")
 
 (defun ee-shrink-sexp (sexp)
   "If the car of SEXP of the form `find-xxxfile', reduce it to `find-xxx'."
@@ -201,6 +212,7 @@ A \"tag\" is the string between \"«»\"s in an anchor."
 ;; «ee-flip-psne-ness» (to ".ee-flip-psne-ness")
 ;; (define-key eev-mode-map "\M-s" 'ee-flip-psne-ness)
 ;; See: (find-psne-intro "6. `ee-flip-psne-ness'")
+;;      (find-psne-intro "6. `ee-flip-psne-ness'" "M-s")
 
 (defun ee-flip-psne-ness ()
   (interactive)
@@ -222,6 +234,8 @@ A \"tag\" is the string between \"«»\"s in an anchor."
 ;; «eewrap-vldi-list-line» (to ".eewrap-vldi-list-line")
 ;; (define-key eev-mode-map "\M-I" 'eewrap-vldi-list-line)
 ;;
+;; This is an undocumented hack! (?)
+;;
 ;; In a Debian system, for each installed package named xxxx there is
 ;; an associated file, at /var/lib/dpkg/info/xxxx.list - let's call
 ;; that the "vldi list" associated to the package xxxx - that lists
diff --git a/eev-intro.el b/eev-intro.el
index 6059c25..83b4114 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    2020dec22
+;; Version:    2020dec27
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -1436,7 +1436,7 @@ hyperlinks are all equivalent:
   (find-fline  \"~/eev2/eev-blinks.el\" \"«find-wottb»\")
 
 You can use this - or the shorter hyperlinks to anchors in
-section 9.3 - to point to anchors or to e-script blocks in your
+section 9.2 - to point to anchors or to e-script blocks in your
 files.
 
 
@@ -1545,7 +1545,7 @@ and that code
      run   (find-efile \"files.el.gz\")
      if the file \"files.el\" is not found,
 
-  3) makes (find-eev     \"eev-blinks.el\" \"find-wottb\")
+  3) makes (find-eev     \"eev-blinks.el\"  \"find-wottb\")
      run:  (find-eevfile \"eev-blinks.el\" \"«find-wottb»\")
      or actually: (find-anchor (ee-eevfile \"eev-blinks.el\") \"find-wottb\")
 
@@ -1841,6 +1841,7 @@ Some other keys that create buffers with elisp hyperlinks:
   M-h M-f   - (find-eev-quick-intro \"4.2. `find-ekey-links' and friends\")
   M-h M-p   - (find-pdf-like-intro \"9. Generating three pairs\")
               (find-pdf-like-intro \"9. Generating three pairs\" \"M-h M-p\")
+  M-h M-e   - (find-audiovideo-intro \"4.1. `find-extra-file-links'\")
     See also: (find-links-intro \"5. The first line regenerates the buffer\")
 
 
@@ -5843,131 +5844,123 @@ then you'll be attributing just a \"temporary\" 
meaning to
 \(Re)generate: (find-anchors-intro)
 Source code:  (find-eev \"eev-intro.el\" \"find-anchors-intro\")
 More intros:  (find-eev-quick-intro)
-              (find-eval-intro)
-              (find-eepitch-intro)
+              (find-here-links-intro)
+              (find-refining-intro)
 This buffer is _temporary_ and _editable_.
 It 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 \"8. Anchors\")
+Notes: this is an advanced tutorial!
+And it is very incomplete at the moment!
 
 
 
-Introduction: `ee-anchor-format' and `to'
-=========================================
-A hyperlink like
 
-  (to \"foo\")
+1. Introduction
+===============
+These sections of the main tutorial explain what anchors are, and
+explain two simple ways of creating index/section anchor pairs:
 
-jumps to the first occurrence of the string \"«foo»\" in the
-current buffer. The way to convert from \"foo\" to \"«foo»\" is
-controlled by the variable `ee-anchor-format', and the sexp
-`(to \"foo\")' is roughly equivalent the third sexp below:
+  (find-eev-quick-intro \"8. Anchors\")
+  (find-eev-quick-intro \"8.1. Introduction: `to'\")
+  (find-eev-quick-intro \"8.3. Creating index/section anchor pairs\")
+  (find-eev-quick-intro \"8.3. Creating index/section anchor pairs\" \"`M-A'\")
+  (find-eev-quick-intro \"8.4. Creating e-script blocks\")
+  (find-eev-quick-intro \"8.4. Creating e-script blocks\" \"`M-B'\")
 
-                            ee-anchor-format
-                    (format ee-anchor-format \"foo\")
-  (ee-goto-position (format ee-anchor-format \"foo\"))
+and these other sections explain briefly how hyperlinks to
+anchors in other files work,
 
-We will call strings in `«»'s _anchors_, and we will say
-that `(to \"foo\")' jumps \"to the anchor `foo'\".
+  (find-eev-quick-intro \"8.5. Hyperlinks to anchors in other files\")
+  (find-eev-quick-intro \"9.2. Extra arguments to `code-c-d'\")
+  (find-eev-quick-intro \"9.2. Extra arguments to `code-c-d'\" \":anchor)\")
+  (find-eev-quick-intro \"9.2. Extra arguments to `code-c-d'\" \"makes 
(find-eev\")
 
-Anchors can be used to create sections and indexes, as we shall
-see soon - but due to some old design decisions that I was never
-able to find good alternatives for, this tutorial needs to start
-with a BIG WARNING.
+but they stop right before explaining how to use them in a
+practical way, i.e., with few keystrokes. This intro is about
+this.
 
 
 
-WARNING: some glyphs need raw-text-unix
-=======================================
-The best way to make anchors stand out is to use colored glyphs
-for them - just like we made `^O's appear as red star glyphs for
-eepitch, as described here:
 
-  (find-eepitch-intro \"\\nRed stars\\n\")
 
-For historical reasons, the glyphs for `«' and `»' defined in
+2. Shrinking
+============
+We saw in
 
-  (find-eev \"eev-anchors.el\")
+  (find-eev-quick-intro \"9.2. Extra arguments to `code-c-d'\" \"makes 
(find-eev\")
 
-use the characters 171 and 187; as far as I know, these
-characters are only \"safe\" - in the sense that Emacs will not
-try to convert them to anything else - in unibyte buffers. The
-best way to make sure that anchors with `«»'s will work in a
-certain file is to put a \"Local variables:\" section at the end
-of it, as has been done in this buffer - and use that to set both
-the file coding to raw-text-unix and the value of
-`ee-anchor-format' to \"«%s»\".
+that these two hyperlinks are equivalent:
 
-Note that if you change a \"Local variables:\" section by hand
-you will probably have to either reload the file or run `M-x
-normal-mode' to make the new settings take effect.
+  (find-eevfile \"eev-blinks.el\" \"«find-wottb»\")
+  (find-eev     \"eev-blinks.el\"  \"find-wottb\")
 
+The first one searches for a string in \"eev-blinks.el\" in the
+normal way; the second one treats the \"find-wottb\" as a tag,
+wraps it in `«»'s, and then searches for the anchor
+\"«find-wottb»\" in the file \"eev-blinks.el\".
 
+We will refer to the operation that converts the hyperlink
 
-Indexes
-=======
-In a situation like this,
+  (find-eevfile \"eev-blinks.el\")
 
-  «one»   (to \"two\")
-  «two»   (to \"one\")
+to
 
-we have two anchors, and typing `M-e' at the line with the anchor
-\"one\" takes us to the line with the anchor \"two\", and typing
-`M-e' at the line with the anchor \"two\" takes us to the line
-with the anchor \"one\". In a situation like this we say that the
-anchors \"one\" and \"two\" _point to one another_.
+  (find-eev \"eev-blinks.el\")
 
-In a case like this,
+as _shrinking_ the hyperlink. Eev has a key sequence that does
+that, and for simplicity its behavor is just this: it looks at
+first element of the sexp at eol (the \"head\" of the sexp), and
+if it is a symbol that ends with \"file\" then rewrite the sexp
+replacing the head symbol by it minus its suffix \"file\". That
+key sequence is `M-h M--' (`ee-shrink-hyperlink-at-eol'), and its
+source code is here:
 
-  «.three»   (to \"three\")
-   «three»  (to \".three\")
+  (find-eev \"eev-edit.el\" \"ee-shrink-hyperlink-at-eol\")
 
-where the names of two anchors pointing to one another differ by
-an initial dot, we will say that the anchor \".three\" is the
-\"index anchor\", and the anchor \"three\" is the \"section
-anchor\"; and one way to create an index for a file is to group
-all the index anchors together. For an example, see:
+Try it on the two lines below:
 
-  (find-eev \"eev-intro.el\" \".find-eev-intro\")
+  (find-eevfile  \"eev-edit.el\"  \"ee-shrink-hyperlink-at-eol\")
+  (find-eev      \"eev-edit.el\"  \"ee-shrink-hyperlink-at-eol\")
 
 
 
 
-Creating index/section anchor pairs
-===================================
-Use `M-A' (`eewrap-anchor'). Note that this has been briefly
-mentioned here:
+3. The preceding tag
+====================
+The key sequence `M-h M-w' copies the current line to the kill
+ring, highlights it for a fraction of a second, and shows the
+message
 
-  (find-wrap-intro \"All wrapping functions\")
+  \"Copied the current line to the kill ring - use C-y to paste\"
 
-It will convert a line with a syntax like
+in the echo area. Here are links to its source code and to a
+section of a tutorial that mentions it:
 
-  comment-prefix <anchor-name>
+  (find-eev \"eev-edit.el\" \"ee-copy-this-line-to-kill-ring\")
+  (find-refining-intro \"3. Three buffers\" \"M-h M-w\")
 
-into:
+When we run `M-h M-w' with a numeric argument - for example, as
+`M-1 M-h M-w' - it highlights and copies to the kill ring the
+\"preceding tag\" instead of the current line; the \"preceding
+tag\" is the string between `«»'s in the anchor closest to the
+point if we search backwards. As an exercise, type `M-1 M-h M-w'
+at some point below, and then use `M-h M-y' (`ee-yank-pos-spec')
+to add it to the hyperlink with `find-anchors-intro' below the
+anchors.
 
-  comment-prefix «.anchor-name»        (to \"anchor-name\")
-  comment-prefix «anchor-name» (to \".anchor-name\")
+  «first-anchor»
+  «second-anchor»
+  «third-anchor»
 
-where comment-prefix is any string and anchor-name is a string
-without `<>'s. Note that the `<>'s, which are easy to type, are
-converted into `«»'s, which are harder.
+  (find-anchors-intro)
 
 
 
-find-anchor
-===========
-\(find-eev \"eev-anchors.el\")
-\(find-eev \"eev-anchors.el\" \"find-anchor\")
+[TO DO: write the other sections!]
 
 
-code-c-d and :anchor
-====================
-\(find-eev \"eev-code.el\" \"ee-code-c-d-:anchor\")
 " rest)))
 
 ;; (find-anchors-intro)
@@ -7635,9 +7628,9 @@ default audio/video file at that timestamp.
 
 
 
-5. Passing options to mplayer
-=============================
-By default mplayer is called with just a few command-line options,
+5. Passing options to mpv
+=========================
+By default mpv is called with just a few command-line options,
 besides the ones that tell it at what position to start playing -
 typically just these for videos,
 
@@ -7646,12 +7639,21 @@ typically just these for videos,
 to make it run in full-screen mode with an on-screen display
 showing the current position, and no options for audio.
 
-If you want to change this you should redefine these functions:
+If you want to change this you should set the variable
+`ee-mpv-video-options'. See:
+
+  (find-efunction 'find-mpv-video)
+  (find-evariable   'ee-mpv-video-options)
+
+Here is an example of changing `'ee-mpv-video-options' temporarily:
 
-  (ee-mplayer-video-options)
-  (ee-mplayer-audio-options)
+  (defun find-mpv-rot90-video (fname &optional pos &rest rest)
+    \"Like `find-mpv-video', but with the extra option '--video-rotate=90'.\"
+    (interactive \"sFile name: \")
+    (let ((ee-mpv-video-options
+          (cons \"--video-rotate=90\" ee-mpv-video-options)))
+      (find-mpv-video fname pos)))
 
-
   
 
 
diff --git a/eev-tlinks.el b/eev-tlinks.el
index fef717b..1441dde 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    2020oct30
+;; Version:    2020dec27
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-tlinks.el>
@@ -1876,6 +1876,7 @@ os.exit()
 
 ;; «find-extra-file-links»  (to ".find-extra-file-links")
 ;; Skel: (find-find-links-links-new "extra-file" "fname c" "dir")
+;; Docs: (find-audiovideo-intro "4.1. `find-extra-file-links'")
 ;;
 (defun find-extra-file-links (&optional fname c &rest pos-spec-list)
 "Visit a temporary buffer containing hyperlinks for extra-file."