[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/eev ad9558a 1/4: New intro: (find-refining-intro).
|
From: |
Stefan Monnier |
|
Subject: |
[elpa] externals/eev ad9558a 1/4: New intro: (find-refining-intro). |
|
Date: |
Fri, 17 May 2019 18:27:27 -0400 (EDT) |
branch: externals/eev
commit ad9558a500f759dfd0232b7cad2e7e679677b9f7
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>
New intro: (find-refining-intro).
---
ChangeLog | 25 +++++
VERSION | 4 +-
eev-beginner.el | 4 +-
eev-blinks.el | 4 +-
eev-edit.el | 28 +++++-
eev-elinks.el | 14 ++-
eev-intro.el | 308 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
eev-mode.el | 3 +-
eev-rcirc.el | 7 ++
eev-tlinks.el | 4 +-
eev.el | 8 +-
11 files changed, 383 insertions(+), 26 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index f549a0e..be7df61 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,31 @@
+2019-04-25 Eduardo Ochs <address@hidden>
+
+ * eev-intro.el (find-emacs-keys-intro): point to
+ (find-refining-intro).
+
+ * eev-elinks.el (find-here-links-beginner): new function.
+
+2019-04-24 Eduardo Ochs <address@hidden>
+
+ * eev-mode.el (eev-mode-map-set): new keybinding: `M-h M-w' for
+ `ee-copy-this-line-to-kill-ring'.
+
+ * eev-edit.el (ee-copy-this-line-to-kill-ring): new function.
+
+ * eev-intro.el (find-refining-intro): new function.
+
+2019-04-15 Eduardo Ochs <address@hidden>
+
+ * eev-rcirc.el (eepitch-freenode): new function.
+
2019-04-14 Eduardo Ochs <address@hidden>
+ * eev-intro.el (find-eev-install-intro): small changes.
+
+ * eev.el: small changes.
+
* eev-intro.el (find-rcirc-intro): rewrote completely.
+ (find-escripts-intro): small changes.
* eev-rcirc.el: rewrote all comments and some docstrings.
(ee-irc-channel-around-point): commented out.
diff --git a/VERSION b/VERSION
index 63f9b9a..9ddedb2 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sun Apr 14 17:08:11 GMT 2019
-Sun Apr 14 14:08:11 -03 2019
+Thu Apr 25 18:32:00 GMT 2019
+Thu Apr 25 15:32:00 -03 2019
diff --git a/eev-beginner.el b/eev-beginner.el
index fd2d32c..ae0430d 100644
--- a/eev-beginner.el
+++ b/eev-beginner.el
@@ -53,8 +53,8 @@
;;
;; When, or if, you are no longer a beginner, you may want to load eev
;; by just adding a "(require 'eev-load)" to your ".emacs". This loads
-;; all the main modules but not turn on eev-mode on by default, and
-;; does not open the tutorial. See:
+;; all the main modules but does not turn on eev-mode on by default,
+;; and does not open the tutorial. See:
;;
;; (find-eev-intro "1. `eev-mode'")
;; (find-eev "eev-load.el")
diff --git a/eev-blinks.el b/eev-blinks.el
index 06c6f5c..18bad9e 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -1,6 +1,6 @@
;;; eev-blinks.el -- support for basic hyperlinks in Emacs.
-;;; The basic hyperlinks are the ones that do not depend on templates,
-;;; and that are not created by `code-c-d' and friends.
+;; The basic hyperlinks are the ones that do not depend on templates,
+;; and that are not created by `code-c-d' and friends.
;; Copyright (C) 1999-2019 Free Software Foundation, Inc.
;;
diff --git a/eev-edit.el b/eev-edit.el
index 9b81436..e91eeef 100644
--- a/eev-edit.el
+++ b/eev-edit.el
@@ -19,7 +19,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019mar02
+;; Version: 2019apr25
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-edit.el>
@@ -31,6 +31,7 @@
;;; Commentary:
;; See:
+;; (find-refining-intro "2. Refining hyperlinks")
;; (find-eval-intro "9. Producing and refining hyperlinks")
;; (find-escripts-intro "5.7. Refining hyperlinks")
;; (find-escripts-intro "5.8. Pointing to anchors")
@@ -42,6 +43,7 @@
;; «.ee-duplicate-this-line» (to "ee-duplicate-this-line")
;; «.ee-yank-pos-spec» (to "ee-yank-pos-spec")
+;; «.ee-copy-this-line-to-kill-ring» (to "ee-copy-this-line-to-kill-ring")
;; «.ee-shrink-hyperlink-at-eol» (to "ee-shrink-hyperlink-at-eol")
;; «.ee-flip-psne-ness» (to "ee-flip-psne-ness")
;; «.eewrap-vldi-list-line» (to "eewrap-vldi-list-line")
@@ -110,6 +112,30 @@ 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)
+
+(defun ee-copy-this-line-to-kill-ring ()
+ "Copy the current line to the kill ring and highlight (\"flash\") it."
+ (interactive)
+ (let* ((start (ee-bol))
+ (end (save-excursion (next-line) (ee-bol)))
+ (str (buffer-substring start end))
+ (msg "Copied the current line to the kill ring - use C-y to paste"))
+ (eeflash+ start end eeflash-copy)
+ (kill-new str)
+ (message msg)))
+
+
+
+
;;; _ _ _
;;; ___| |__ _ __(_)_ __ | | __
;;; / __| '_ \| '__| | '_ \| |/ /
diff --git a/eev-elinks.el b/eev-elinks.el
index 3fdca83..5a4b455 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019apr01
+;; Version: 2019apr25
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -1273,6 +1273,18 @@ This needs a temporary directory; see:
(find-prepared-intro)"
+;; This is a hack for beginners that is explained in a tutorial. See:
+;; (find-refining-intro "4. A tip for beginners")
+;; (find-refining-intro "4. A tip for beginners" "find-here-links-beginner")
+;;
+(defun find-here-links-beginner ()
+ "A variant of `find-here-links' that creates a three-window setting."
+ (interactive)
+ (find-wset "13_o2_o_coo" nil '(find-here-links) '(eejump-1)))
+
+
+
+
diff --git a/eev-intro.el b/eev-intro.el
index 007601b..bb47d63 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019apr14
+;; Version: 2019apr25
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -62,6 +62,7 @@
;; «.find-emacs-keys-intro» (to "find-emacs-keys-intro")
;; «.find-eev-install-intro» (to "find-eev-install-intro")
;; «.find-eev-intro» (to "find-eev-intro")
+;; «.find-refining-intro» (to "find-refining-intro")
;;
;; «.find-eval-intro» (to "find-eval-intro")
;; «.find-links-conv-intro» (to "find-links-conv-intro")
@@ -529,8 +530,7 @@ A way to go quickly to \"~/TODO\" is explained in section
7.1.
A way to \"refine\" hyperlinks to make them more precise is
explained here:
- (find-eval-intro \"9. Producing and refining hyperlinks\")
-
+ (find-refining-intro \"2. Refining hyperlinks\")
@@ -1662,6 +1662,8 @@ The keys for creating \"hyperlinks to here\" and refining
them are:
M-h M-h - `find-here-links'. See: (find-eev-quick-intro \"`M-h M-h'\")
M-h M-2 - `ee-duplicate-this-line'. See: (find-eval-intro \"M-h M-2\")
M-h M-y - `ee-yank-pos-spec'. See: (find-eval-intro \"M-h M-y\")
+ See also: (find-refining-intro \"2. Refining hyperlinks\")
+ (find-refining-intro \"4. A tip for beginners\")
2. Key sequences and how to abort them
@@ -1693,6 +1695,7 @@ the \"point\" and the \"mark\":
(find-enode \"Point\")
(find-enode \"Mark\")
+ (find-enode \"Shift Selection\")
You can do cut, copy and paste by using the icons in the toolbar
or by using the menu bar (the relevant options are under
@@ -1706,6 +1709,7 @@ or by using the menu bar (the relevant options are under
See: (find-enode \"Tool Bars\")
(find-enode \"Menu Bar\")
+ (find-emacs-keys-intro \"3. Cutting & pasting\")
@@ -1980,15 +1984,16 @@ be byte-compilable, 2) be compatible with lexical
binding, and 3)
have all the autoloads. My reasons for not complying - or for not
complying NOW - are explained in the subsections below.
-I will try to submit eev to MELPA in the next few days - in
-mid-april 2019. I have the feeling that the issues blocking it
-from going into ELPA will take a few years to be solved.
-
Btw: except for Stefan's e-mails ***100%*** the feedback that I
received about eev in the last three years came from beginners.
I am not willing to make changes that will make eev
beginner-UNfriendly.
+UPDATE: in 2019apr14 eev became a part of ELPA even despite its
+quirks!!! Its ELPA page is here:
+
+ http://elpa.gnu.org/packages/eev.html
+
@@ -2268,6 +2273,287 @@ For the full lists of keybindings, see:
+;;; __ _ _
+;;; _ __ ___ / _(_)_ __ (_)_ __ __ _
+;;; | '__/ _ \ |_| | '_ \| | '_ \ / _` |
+;;; | | | __/ _| | | | | | | | | (_| |
+;;; |_| \___|_| |_|_| |_|_|_| |_|\__, |
+;;; |___/
+;;
+;; «find-refining-intro» (to ".find-refining-intro")
+;; (find-intro-links "refining")
+
+(defun find-refining-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-refining-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-refining-intro)
+Source code: (find-efunction 'find-refining-intro)
+More intros: (find-eev-quick-intro)
+ (find-eval-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
+
+
+(find-eval-intro \"9. Producing and refining hyperlinks\")
+(find-emacs-keys-intro \"and refining them\")
+(find-eval-intro \"6. Refining hyperlinks\")
+
+
+
+
+1. Pos-spec-lists
+=================
+Most hyperlinks functions defined by eev can be \"refined\" by
+the addition of extra arguments. These extra arguments are called
+a \"pos-spec\" (or a \"pos-spec-list\") and they specify a
+position in the target buffer. The first argument means a certain
+line number, when it is a number, or the first occurrence of a
+certain string, when it is a string. Try:
+
+ (find-enode \"Command Index\")
+ (find-enode \"Command Index\" \"eval-last-sexp\")
+
+Further arguments mean either \"move down n lines\" or \"search
+for the next occurrence of a string\", depending on whether they
+are numbers or strings. Try:
+
+ (find-sh \"seq 2095 2115\")
+ (find-sh \"seq 2095 2115\" \"2100\")
+ (find-sh \"seq 2095 2115\" \"2100\" \"9\")
+ (find-sh \"seq 2095 2115\" \"2100\" 2)
+
+In most cases an empty pos-spec-list, like this,
+
+ (find-sh \"seq 2095 2115\")
+
+means: \"if the target buffer already exists then just open it\"
+- so that following that hyperlink would jump to the current
+position of the point in that buffer.
+
+Pos-spec-lists are usually interpreted by the function
+`ee-goto-position'. The first argument is interpreted in a
+special way, according to its type:
+
+ string -> jump to the first occurrence of
+ that string in the buffer
+ number -> jump to the n-th line
+
+and the other arguments are interpreted (recursively) by
+`ee-goto-rest':
+
+ string -> jump to the next occurence of that string
+ number -> move down n lines
+ list -> evaluate the list
+
+Here is an example in which one of the arguments is a list.
+Suggestion: execute it with `M-2 M-e'.
+
+ (find-sh \"seq 2095 2115\" \"2100\" \"9\" '(eek \"!!!\"))
+
+There are some variants of `ee-goto-position' in which the first
+argument is interpreted in a different way, but we will not
+discuss them here. See:
+
+ (find-efunction 'ee-goto-anchor)
+ (find-eev \"eev-pdflike.el\" \"ee-goto-position-page\")
+
+If you want to add support for more complex pos-spec-lists, just
+replace `ee-goto-rest' with your own extended version.
+
+
+
+
+2. Refining hyperlinks
+======================
+To _refine_ a hyperlink means to add items to its pos-spec-list
+to make it point to a more precise location. For example, in the
+links below the first one points to an \"intro\", the second
+points to a section in it, and the third points to an important
+idea in that section:
+
+ (find-escripts-intro)
+ (find-escripts-intro \"5. Tools for writing e-scripts\")
+ (find-escripts-intro \"5. Tools for writing e-scripts\" \"alternate\")
+
+The paragraph where the word \"alternate\" is talks about how to
+alternate between a \"task\" and \"taking notes\" without losing
+focus on the \"task\". Eev has some keys sequences for doing
+that:
+
+ M-h M-h - `find-here-links'. See: (find-eev-quick-intro \"`M-h M-h'\")
+ M-h M-2 - `ee-duplicate-this-line'
+ M-h M-y - `ee-yank-pos-spec'
+ M-h M-w - `ee-copy-this-line-to-kill-ring'
+
+Let me explain them starting by the two middle ones. This sexp
+
+ (kill-new \"Tools-for\")
+
+puts the string \"Tools for\" on the top of the kill ring; we can
+use it to simulate what happens when the user marks a region
+containing that string and runs `M-w'. See:
+
+ (find-enode \"Kill Ring\")
+ (find-emacs-keys-intro \"3. Cutting & pasting\")
+
+Try the first two sexps below:
+
+ (kill-new \"Tools-for\")
+ (eek \"<down> M-h M-2 M-h M-y\")
+ (find-escripts-intro)
+
+The `eek' duplicates the line with \"(find-escripts-intro)\" and
+then runs `M-h M-y' (`ee-yank-pos-spec') on it; `M-h M-y' is
+based on `C-y' (`yank'),
+
+ (find-enode \"Yanking\")
+
+but `M-h M-y' \"yanks\" the text at the end of the sexp, in
+quotes, as an new argument.
+
+
+
+
+3. Three buffers
+================
+One very common usage pattern involves three buffers:
+
+ 1. a buffer where we are storing our notes (the \"notes
+ buffer\").
+
+ 2. a buffer with something interesting that we want to create a
+ link to (the \"target buffer\"),
+
+ 3. a temporary buffer with editable hyperlinks, usually created
+ by `find-here-links' (the \"elinks buffer\").
+
+Usually beginners use the file \"~/TODO\" - that can be accessed
+with `M-1 M-j' - for all the e-script notes that they create;
+learning to keep notes in several files is a skill that comes
+later.
+
+Let's take a concrete example. We found something interesting in
+section 4 of `(find-escripts-intro)', and we want to keep a link
+to that; we decided to use the string \"snip, snip\" to refine
+the hyperlink -
+
+ (find-escripts-intro)
+ (find-escripts-intro \"4. How to read an e-script\")
+ (find-escripts-intro \"snip, snip\")
+
+and we want to produce the refined hyperlink - using the keys
+from the previous section -, copy it to our notes buffer, and go
+back to the target buffer. The keys to switch buffers are shown
+below,
+
+ ________ ________ ________ ________
+ | | : : | | | |
+ | target | M-h M-h : elinks : M-1 M-j | notes | M-K M-K | target |
+ | buffer | ------> : buffer : ------> | buffer | ------> | buffer |
+ |________| :________: |________| |________|
+
+but there are also some things that we need to do inside each one
+of these buffers:
+
+ a. In the target buffer: mark the string \"snip, snip\" and
+ copy it to the kill ring with `M-w' (`kill-ring-save');
+
+ b. In the elinks buffer: go to the line with the hyperlink that
+ points to the target buffer - `(find-escripts-intro)' -,
+ refine it with `M-h M-2 M-h M-y', copy its line to the kill
+ ring with `M-h M-w' (`ee-copy-this-line-to-kill-ring');
+
+ c. In the notes buffer: insert the refined hyperlink with
+ `C-y' (`yank').
+
+Note: `M-h M-w' (`ee-copy-this-line-to-kill-ring') is a key
+sequence intended for beginners. I prefer to use something like
+`C-a shift-<down> M-w'.
+
+
+
+
+4. A tip for beginners
+======================
+Some people find the instructions above hard to follow because
+they force them to remember lots of things that are off-screen.
+If you run the second sexp below,
+
+ (define-key eev-mode-map \"\\M-h\\M-h\" 'find-here-links)
+ (define-key eev-mode-map \"\\M-h\\M-h\" 'find-here-links-beginner)
+
+it will rebind the key sequence `M-h M-h' to a variant of
+`find-here-links' for beginners that creates this window
+configuration:
+
+ _____________________
+ | | |
+ | | elinks |
+ | | buffer |
+ | target |__________|
+ | buffer | |
+ | | notes |
+ | | buffer |
+ |__________|__________|
+
+You can then try to run the instructions in the last section with
+all the three buffers visible, switching from one buffer to
+another by clicking on their windows. Note the the order is:
+
+ _____________________
+ | | |
+ | ==> elinks |
+ | | buffer |
+ | target |____||____|
+ | buffer | \\/ |
+ | | notes |
+ | <== buffer |
+ |__________|__________|
+
+and note also that, in the terminology of
+
+ (find-escripts-intro \"alternate\" \"task\" \"notes\")
+
+the left side is \"task\" and the right side is \"notes\".
+
+To rebind `M-h M-h' to its original function, run this:
+
+ (define-key eev-mode-map \"\\M-h\\M-h\" 'find-here-links)
+
+or restart Emacs.
+
+The big figure below shows all the keys sequences:
+
+ _______________________________________
+ | | |
+ | | elinks |
+ | target `M-h M-h' buffer: |
+ | buffer: ::::::::> `M-h M-y |
+ | `M-w' | M-h M-w' |
+ | | |
+ | | ::`M-1 M-j' |
+ | |_______ :: __________|
+ | | \\/ |
+ | | |
+ | `M-K M-K' notes |
+ | <:::::::: buffer: |
+ | | `C-y' |
+ | | |
+ |_________________|_____________________|
+
+
+
+
+
+
+
+
+
+" pos-spec-list)))
+
+;; (find-refining-intro)
+
+
;;; _
@@ -6402,8 +6688,8 @@ discussion of free software projects happen), called
-1. The example the I use in workshops
-=====================================
+1. The example that I use in workshops
+======================================
Let's start with an example. In
(setq rcirc-default-nick \"hakuryo\")
@@ -8504,7 +8790,7 @@ reviewed in the subsections below.
# (find-fline \"/tmp/lua-intro.e\")
# (find-anchor \"/tmp/lua-intro.e\" \"intro:types\")
- # (defun eejump-11 () (find-fline \"/tmp/lua-intro.e\"))
+ # (defun eejump-71 () (find-fline \"/tmp/lua-intro.e\"))
--snip, snip--
@@ -8708,7 +8994,7 @@ 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
+doing it for the first time, and in a different way if we're
doing it for the n-th time with some memory of what we did in the
previous times and of what we found important and what not.
Performing a task like this consists of several steps, that can
diff --git a/eev-mode.el b/eev-mode.el
index 76a6dc2..a7dc1a5 100644
--- a/eev-mode.el
+++ b/eev-mode.el
@@ -19,7 +19,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019mar02
+;; Version: 2019apr24
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-mode.el>
@@ -144,6 +144,7 @@ and: (find-eval-intro \"`M-k'\")"
;; Source: (find-eev "eev-edit.el")
(define-key eev-mode-map "\M-h\M-2" 'ee-duplicate-this-line)
(define-key eev-mode-map "\M-h\M-y" 'ee-yank-pos-spec)
+ (define-key eev-mode-map "\M-h\M-w" 'ee-copy-this-line-to-kill-ring)
(define-key eev-mode-map "\M-h\M--" 'ee-shrink-hyperlink-at-eol)
;;
;; These ones are also from: (find-eev "eev-edit.el")
diff --git a/eev-rcirc.el b/eev-rcirc.el
index f104b38..4b38ea8 100644
--- a/eev-rcirc.el
+++ b/eev-rcirc.el
@@ -336,6 +336,13 @@ This is like `find-rcirc-buffer-3a' but uses
+;; See: (find-efunction 'eepitch)
+;; (find-efunction 'eepitch-to-buffer)
+(defun eepitch-freenode (channel)
+ (interactive) (eepitch '(find-freenode channel)))
+
+
+
;;; __ _ _ _ _
;;; / _|_ __ ___ ___ _ __ ___ __| | ___ | (_)_ __ | | _____
diff --git a/eev-tlinks.el b/eev-tlinks.el
index fee038d..f9e39c9 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -420,9 +420,9 @@ Hello
,(ee-template0 "
;;; {stem-el} -- ???.
-;; Copyright (C) 2012 Free Software Foundation, Inc.
+;; Copyright (C) 2019 Free Software Foundation, Inc.
;;
-;; This file is (not yet?) part of GNU eev.
+;; This file is part of GNU eev.
;;
;; GNU eev is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
diff --git a/eev.el b/eev.el
index b893322..73a24dd 100644
--- a/eev.el
+++ b/eev.el
@@ -1,12 +1,12 @@
-;;; eev.el --- Support for e-scripts (eepitch blocks, elisp hyperlinks, etc)
+;;; eev.el --- Support for e-scripts (eepitch blocks, elisp hyperlinks, etc)
-*- lexical-binding: t; -*-
-;; Copyright (C) 2012-2019 Free Software Foundation, Inc.
+;; Copyright (C) 2019 Free Software Foundation, Inc.
;; Author: Eduardo Ochs <address@hidden>
-;; Package-Requires: ((emacs "24.3"))
+;; Package-Requires: ((emacs "24.1"))
;; Keywords: lisp e-scripts
;; URL: http://angg.twu.net/#eev
-;; Version: 2019apr10
+;; Version: 20190425
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by