[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/eev 22702eb 31/64: Made all secondary intros point to s
|
From: |
Stefan Monnier |
|
Subject: |
[elpa] externals/eev 22702eb 31/64: Made all secondary intros point to sections of find-eev-quick-intro. |
|
Date: |
Sun, 7 Apr 2019 16:59:07 -0400 (EDT) |
branch: externals/eev
commit 22702ebe1dd4bd6afa31bde137d84a4314e11cf0
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>
Made all secondary intros point to sections of find-eev-quick-intro.
---
ChangeLog | 14 +
VERSION | 4 +-
eev-intro.el | 3658 ++++++++++++++++++++++++++--------------------------
eev-mode.el | 22 +-
eev-multiwindow.el | 4 +-
5 files changed, 1898 insertions(+), 1804 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 700a4ba..2a34af4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2019-02-01 Eduardo Ochs <address@hidden>
+
+ * eev-intro.el (find-intro-dual): new function - a new hack that
+ replaces `find-intro-here'.
+ (find-intro-here): deleted together with its dependencies.
+ (find-eev-quick-intro): small changes.
+ (find-eval-intro): small changes.
+ (find-links-intro): small changes.
+ (find-eepitch-intro): small changes.
+ (find-eejump-intro): small changes.
+ (find-code-c-d-intro): small changes.
+
+ * eev-multiwindow.el (find-wset-c): new function.
+
2019-01-30 Eduardo Ochs <address@hidden>
* eev-tlinks.el (find-eev-install-links): small changes.
diff --git a/VERSION b/VERSION
index a7ca754..826e509 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Wed Jan 30 21:51:21 GMT 2019
-Wed Jan 30 19:51:21 -02 2019
+Fri Feb 1 14:17:49 GMT 2019
+Fri Feb 1 12:17:49 -02 2019
diff --git a/eev-intro.el b/eev-intro.el
index a35afe5..b14573d 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -20,7 +20,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019jan30
+;; Version: 2019feb01
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -33,16 +33,19 @@
;;
;; Sometime around 2015 I realized that I could make write a sandboxed
;; tutorial - (find-eev-quick-intro) - that could be THE starting
-;; point of eev. It could be at the same time an interactive tutorial
-;; for beginners, a tutorial for advanced users, and an index to the
-;; other sandboxed tutorials, that were mostly quite technical - and
-;; incomplete =(. Also, the default way of installing eev for
-;; beginners would show that "quick intro" in the starting screen.
+;; point of eev. It would be:
+;;
+;; 1) an interactive tutorial for beginners,
+;; 2) the thing that emacs shows when it starts (when we invoke it
+;; as "~/eev"),
+;; 3) a tutorial for advanced users,
+;; 4) an index to the other sandboxed tutorials, that were mostly
+;; quite technical (and incomplete),
+;; 5) a guide to the source files.
;;
;; As of jan/2019, the work to make (find-eev-quick-intro) central is
;; almost complete (...)
-
-
+;;
;; To use this, simply execute any of the sexps below:
;; (find-eev-quick-intro)
;; (find-eev-intro)
@@ -53,7 +56,7 @@
;; Quick index:
-;; �.find-intro-here� (to "find-intro-here")
+;; �.find-intro-dual� (to "find-intro-dual")
;;
;; �.find-eev-quick-intro� (to "find-eev-quick-intro")
;; �.find-emacs-keys-intro� (to "find-emacs-keys-intro")
@@ -61,19 +64,20 @@
;; �.find-eev-intro� (to "find-eev-intro")
;;
;; �.find-eval-intro� (to "find-eval-intro")
+;; �.find-links-intro� (to "find-links-intro")
;; �.find-eepitch-intro� (to "find-eepitch-intro")
;; �.find-wrap-intro� (to "find-wrap-intro")
-;; �.find-links-intro� (to "find-links-intro")
-;; �.find-code-c-d-intro� (to "find-code-c-d-intro")
-;; �.find-psne-intro� (to "find-psne-intro")
-;; �.find-brxxx-intro� (to "find-brxxx-intro")
;; �.find-eejump-intro� (to "find-eejump-intro")
+;; �.find-anchors-intro� (to "find-anchors-intro")
+;; �.find-code-c-d-intro� (to "find-code-c-d-intro")
;; �.find-pdf-like-intro� (to "find-pdf-like-intro")
+;; �.find-brxxx-intro� (to "find-brxxx-intro")
+;; �.find-psne-intro� (to "find-psne-intro")
+;;
;; �.find-audiovideo-intro� (to "find-audiovideo-intro")
;; �.find-multiwindow-intro� (to "find-multiwindow-intro")
;; �.find-rcirc-intro� (to "find-rcirc-intro")
;; �.find-templates-intro� (to "find-templates-intro")
-;; �.find-anchors-intro� (to "find-anchors-intro")
;; �.find-prepared-intro� (to "find-prepared-intro")
;; �.find-bounded-intro� (to "find-bounded-intro")
;; �.find-channels-intro� (to "find-channels-intro")
@@ -95,60 +99,78 @@
;; "Source code: (find-eev \\\\\"eev-intro.el\\\\\"
\\\\\"\\1\\\\\")")
-;; �find-intro-here� (to ".find-intro-here")
+;; �find-intro-dual� (to ".find-intro-dual")
;; Below is a hack that I (edrx) use to edit these intros.
;; Note that it is commented out - and how it is commented out!
-;; The way to run the (progn <multi-line-stuff>) is to put the point
+;; The way to run the ' (progn <multi-line-stuff>) is to put the point
;; after the closing parenthesis - the one on a line by itself - and
-;; type `M-e'.
+;; then type `M-e'.
+;;
+;; If we're editing the defun for `find-foo-intro' at a line that
+;; contains "<a certain string>" then running `M-x fd' there creates a
+;; window setup like this,
;;
-;; Here's how to use this. Suppose that
-;; 1) you're editing this file - eev-intro.el - and
-;; 2) you're inside the defun of an intro, say, `find-eev-quick-intro', and
-;; 3) you're inside the multi-line string that forms the text of the intro,
-;; 4) then if you mark a string, say, "Open the page at",
-;; 5) and run `M-w' (kill-ring-save) on it,
-;; 6) then that string will be pushed onto the kill ring;
-;; 7) if you type `M-x fh' then this will
-;; 7a) evaluate the defun around point,
-;; 7b) i.e., it will redefine find-eev-quick-intro,
-;; 7c) and run (find-2b nil '(find-eev-quick-intro "Open the page at"))
-;; 7d) and you will have the defun of `find-eev-quick-intro' in
-;; the left window and the (find-eev-quick-intro) buffer in the
-;; right window, with the point just after the "Open the page at".
+;; _______________________________________
+;; | | |
+;; | source: | intro: |
+;; | eev-intro.el | *(find-foo-intro)* |
+;; |________________|______________________|
+;;
+;; with both windows centered on the lines with "<a certain string>".
+;; If we're editing the buffer "*(find-foo-intro)*" and we're on a
+;; line containing "<a certain string>" then running `M-x fd' also
+;; creates the same window setup, with the source at the left and the
+;; intro buffer at the right.
'
(progn
;; Test: (ee-sexp-at "2)")
-;; (+ 1 2)
+;; (+ 1 2)
(defun ee-sexp-at (re)
(save-excursion (re-search-forward re) (ee-last-sexp)))
-
(setq ee-intro-sexp-end-re "\\(rest\\|pos-spec-list\\))))")
-
(defun ee-intro-sexp-here ()
"Go to the end of the defun around point and `read' it.
-Only works for \"(defun find-xxx-intro ...)s\"."
+Only works for \"(defun find-xxx-intro ...)s\".
+Returns a list like this: (defun find-xxx-intro ...)."
(read (ee-sexp-at ee-intro-sexp-end-re)))
-(defun find-intro-here ()
- "Evaluate the defun around point, run it, search for (ee-last-kill).
-Only works for \"(defun find-xxx-intro ...)s\"."
+(defun ee-bad-line (str) (string-match "[\\\"]" str))
+(defun ee-this-line0 ()
+ (buffer-substring-no-properties (ee-bol) (ee-eol)))
+(defun ee-this-line ()
+ (let ((line (ee-this-line0)))
+ (if (ee-bad-line line)
+ (error "Current line contains evil characters")
+ line)))
+
+(defun find-intro-intro ()
+"If we're in the defun for `find-foo-intro' run (find-foo-intro
(ee-last-kill))."
(interactive)
- (eval (ee-intro-sexp-here))
- (find-2b nil '(funcall (cadr (ee-intro-sexp-here)) (ee-last-kill))))
-
-(defalias 'fh 'find-intro-here)
+ (funcall (cadr (ee-intro-sexp-here)) (ee-this-line)))
(defun find-intro-source ()
+"If we're in a buffer \"*(find-foo-intro)*\" go to the source for
`find-foo-intro'.
+Actually go to: (find-eev \"eev-intro.el\" \"find-foo-intro\" (ee-last-kill))."
(interactive)
- (find-2a
- '(find-eev "eev-intro.el"
- (format "find-%s-intro" (ee-intro-bufferp))
- (ee-last-kill))
- nil))
+ (find-eev "eev-intro.el" (format "find-%s-intro" (ee-intro-bufferp))
+ (ee-this-line)))
-(defalias 'fi 'find-intro-source)
+;; (defun find-2a (a b) (find-wset "13_o_o" a b))
+;; (defun find-2b (a b) (find-wset "13_o_" a b))
+(defun find-c2a (a b) (find-wset "13_co_co" a b))
+(defun find-c2b (a b) (find-wset "13_co_c" a b))
+
+(defun find-intro-dual ()
+ (interactive)
+ (if (equal (buffer-name) "eev-intro.el")
+ (progn (eval (ee-intro-sexp-here))
+ (find-c2b nil '(find-intro-intro)))
+ (find-c2a '(find-intro-source) nil)))
+
+(defalias 'fs 'find-intro-source)
+(defalias 'fi 'find-intro-intro)
+(defalias 'fd 'find-intro-dual)
)
@@ -398,6 +420,10 @@ creates this buffer, and switches to it:
|--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
|___________________________________________________________|
+
+
+4.1. `find-here-links'
+----------------------
One standard way of using eev is:
a) we keep our current notes in a a file - for example, \"~/TODO\"
@@ -423,14 +449,14 @@ buffer. For example, typing `M-h M-h' here generates:
|--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
|____________________________________________________________|
-The
+The elisp hyperlink
# (find-eev-quick-intro)
opens this tutorial.
Cutting and pasting is explained briefly in section 5.2.
-
+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:
@@ -1593,12 +1619,12 @@ Help would be greatly appreciated!
-;;; _ _
-;;; ___ _____ __ (_)_ __ | |_ _ __ ___
-;;; / _ \/ _ \ \ / /____| | '_ \| __| '__/ _ \
-;;; | __/ __/\ V /_____| | | | | |_| | | (_) |
-;;; \___|\___| \_/ |_|_| |_|\__|_| \___/
-;;;
+;;;
+;;; ___ _____ __
+;;; / _ \/ _ \ \ / /
+;;; | __/ __/\ V /
+;;; \___|\___| \_/
+;;;
;; This works as an index.
;; (find-intro-links "eev")
;; �find-eev-intro� (to ".find-eev-intro")
@@ -1630,25 +1656,26 @@ recommended reading order:
4. (find-eval-intro)
5. (find-links-intro)
6. (find-eepitch-intro)
- 6. (find-wrap-intro)
- 7. (find-eejump-intro)
- 8. (find-code-c-d-intro)
- 9. (find-psne-intro)
- 10. (find-brxxx-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-audiovideo-intro)
- 13. (find-anchors-intro)
- 14. (find-multiwindow-intro)
- 15. (find-rcirc-intro)
- 16. (find-templates-intro)
- 17. (find-prepared-intro)
- 18. (find-bounded-intro)
- 19. (find-channels-intro)
- 20. (find-videos-intro)
-
-Items 00, 1 and 2 should give you a good grasp of the main ideas
-- namely, that _elisp hyperlinks and interactive scripts can be
-embedded anywhere_. The other tutorials mainly show how to make
+ 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)
+
+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
+can be embedded anywhere_. The other tutorials mainly show how to make
these ideas pervasive.
The last item above is an index of the video tutorials, with
@@ -1660,7 +1687,6 @@ workshops, but that are not very eev-specific:
A. (find-emacs-intro)
B. (find-defun-intro)
- C. (find-eev-quick-intro)
@@ -1696,9 +1722,6 @@ For the full lists of keybindings, see:
-
-
-
;;; _
;;; _____ ____ _| |
;;; / _ \ \ / / _` | |
@@ -1711,8 +1734,7 @@ For the full lists of keybindings, see:
;; http://angg.twu.net/eev-article.html#hyperlinks
;; file:///home/edrx/TH/L/eev-article.html#hyperlinks
;; (find-TH "eev-article" "forward-and-back")
-;; (find-efunction 'eek-eval-last-sexp)
-
+;; (find-efunction 'ee-eval-last-sexp)
(defun find-eval-intro (&rest rest) (interactive)
(let ((ee-buffer-name "*(find-eval-intro)*"))
@@ -1727,9 +1749,10 @@ It is meant as both a tutorial and a sandbox.
-Note: most of this material was copied to
+Note: this intro needs to be rewritten!
+Ideally it should _complement_ the material in:
(find-eev-quick-intro \"2. Evaluating Lisp\")
-but some sections are more detailed here...
+
@@ -2087,1032 +2110,1480 @@ hyperlinks in scripts]
-;;; _ _ _ _ _
-;;; ___ ___ _ __ (_) |_ ___| |__ (_)_ __ | |_ _ __ ___
-;;; / _ \/ _ \ '_ \| | __/ __| '_ \ _____| | '_ \| __| '__/ _ \
-;;; | __/ __/ |_) | | || (__| | | |_____| | | | | |_| | | (_) |
-;;; \___|\___| .__/|_|\__\___|_| |_| |_|_| |_|\__|_| \___/
-;;; |_|
-;;
-;; �find-eepitch-intro� (to ".find-eepitch-intro")
-;; (find-intro-links "eepitch")
-;; (find-eev "eepitch.readme")
-(defun find-eepitch-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-eepitch-intro)*"))
+
+;;; _ _ _
+;;; | (_)_ __ | | _____
+;;; | | | '_ \| |/ / __|
+;;; | | | | | | <\__ \
+;;; |_|_|_| |_|_|\_\___/
+;;;
+;; (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-estring "\
-\(Re)generate: (find-eepitch-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-eepitch-intro\")
+\(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-wrap-intro)
+ (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial (for eepitch) and a sandbox.
-
+Is is meant as both a tutorial and a sandbox.
-For an introduction to the ideas here, see:
- (find-eev-quick-intro \"6. Controlling shell-like programs\")
+Note: this intro needs to be rewritten!
+Ideally it should _complement_ the material in:
+ (find-eev-quick-intro \"3. Elisp hyperlinks\")
-The motivation for eepitch: taking notes and redoing
-====================================================
-Suppose that we have to do some reasonably complex task using a
-shell, and that we want to take notes of what we do because we
-might have to do something similar later.
-The two usual ways to interact with a shell are:
+1. What is a hyperlink?
+=======================
+In a previous tutorial - (find-eval-intro) - we saw that several
+kinds of sexps can be used as hyperlinks. For example, these:
- 1) through a _script_, that is, by preparing in advance all
- commands to be executed, putting them in a script file, and
- then running that file,
+ (find-fline \"/tmp/\")
+ (find-node \"(emacs)Lisp Eval\")
+ (find-efunctiondescr 'find-file)
+ (find-efunction 'find-file)
+ (find-man \"cat\")
- 2) _interactively_, by typing the commands one by one on a
- shell prompt.
+Hyperlinks in a web browser _usually_ take us to a different
+page, or to a different position in the same page, and in those
+cases it is possible to go back to previous position from there;
+but sometimes hyperlinks - or webpage buttons - are associated to
+Javascript code, and \"following the link\" then means executing
+that code. Web browsers try to make it impossible to have
+hyperlinks or webpages that will send out your private
+information, or that will put your system in a unusable state.
+Security is web browsers is achieved by restricting what the
+scripts in a page can do.
-Suppose that we have to discover which commands to run as we go;
-that rules out preparing a script beforehand, so we need to use
-the shell interactively. After issuing the right commands, the
-two usual ways to retrieve what we did are:
+Sexp hyperlinks, in contrast, can do essentially anything - and,
+instead of _security_, they have _transparency_. The code that a
+sexp hyperlink will execute is visible, and users are supposed to
+know that sexp hyperlinks with `find-fline', `find-node',
+`find-efunctiondescr', etc, are very safe - but the ones that
+start with `find-sh' may not be. It is possible to write
+something like:
- a) through the _shell history_, which records the last commands
- that the shell received,
+ (find-sh \"<code that deletes all your e-mails>\")
- b) by looking at the full _transcript_ of our interaction with
- the shell.
+but it is not possible to hide that action behind an
+innocent-looking button that says \"click for a larger image\".
-The way (a) gets a list of commands, without comments, that can
-be then saved into a text editor; the way (b) may require some
-tricky editing to isolate the commands from their outputs.
+So, _any_ elisp sexp can be _used_ as a sexp hyperlink; but
+people are only going to follow a sexp hyperlink if they can more
+or less predict (quickly!) what that hyperlink is going to do...
+Readability is important, so let's take a look at the most common
+kinds of hyperlinks.
-Eepitch.el implements a simple alternative way of interacting
-with shells (and other shell-like programs) while keeping notes.
-It has only one essential key binding, <F8>, which is better
-explained through the executable example in the next section, and
-two unessential features, `M-T' and \"\", which will be
-explained later.
-The main key: <F8>
-==================
-Emacs can run a shell in a buffer, and it can split its frame
-into windows, like this:
- ___________________
- | | |
- | our | a |
- | notes | shell |
- | | buffer |
- |_________|_________|
+2. Elisp 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 generated help buffers have hyperlinks,
+that can be followed by typing <RET> on them.
-The usual way to use a shell buffer is to move the cursor there
-and type commands into its prompt; the eepitch-y way is to leave
-the cursor at the \"notes\" buffer, write the commands for the
-shell there, and send these commands to the shell with <F8>.
+Eev has something similar, but using the prefix `M-h' and
+following very different design decisions. Let's start with a
+comparison, between Emacs's `C-h f' (`describe-function') and
+eev's `M-h M-f' (`find-efunction-links'). Remember that `M-e'
+accepts prefix arguments, and that `M-2 M-e' displays the target
+of a hyperlink at another window without switching to there; use
+that on the two sexps below to see the results by yourself:
-Here's what <F8> does:
+ \"C-h f find-file\" -> (find-efunctiondescr 'find-file)
+ \"M-h M-f find-file\" -> (find-efunction-links 'find-file)
- When we type <F8> on a line that starts with a red
- star (\"\"), it executes the rest of the line as Lisp, and
- moves down; when we type <F8> on a line that does not start
- with a \"\", it makes sure that the \"target buffer\" is being
- displayed (the \"target\" is usually the buffer called
- \"*shell*\"), it \"send\"s the current line to the target
- buffer, and moves down.
+Note that we used `find-efunctiondescr' instead of
+`describe-function'; `find-efunctiondescr' is a variant of
+`describe-function' that that follows eev's conventions, as
+explained here:
- \"Sending the current line to the target buffer\" means copying
- the contents of the current line to the target - as if the user
- had typed that line there by hand -, then \"typing\" a <RET> at
- the target buffet.
+ (find-eval-intro \"main conventions\")
-Please try that in the example after this paragraph, by typing
-<F8> six times starting at the first line that says
-\" (eepitch-shell)\". The three red star lines at the top will
-create a target buffer, destroy it, and create it again; the
-other three lines will send commands to the target shell.
+`C-h f find-file' produces a buffer with readable text and
+\"usual\" hyperlinks that can be followed by typing RET on them,
+while `M-h M-f find-file' produces a buffer like this:
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-echo \"We are at: $PWD\"
-cd /tmp/
-echo \"We changed to: $(pwd)\"
+ ___________________________________________________________
+ |# (find-efunction-links 'find-file) |
+ |# (where-is 'find-file) |
+ |# (describe-function 'find-file) |
+ |# (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)) |
+ |# (symbol-file 'find-file 'defun) |
+ |# (find-fline (symbol-file 'find-file 'defun)) |
+ | |
+ |# (Info-goto-emacs-command-node 'find-file) |
+ |# (find-enode \"Command Index\" \"* find-file:\") |
+ |# (find-elnode \"Index\" \"* find-file:\") |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
+ |___________________________________________________________|
+What is that?...
-Other targets
-=============
-Just like `(eepitch-shell)' creates a shell buffer and sets the
-eepitch target to it, `(eepitch-python)' creates a buffer with a
-Python interpreter and uses it as the eepitch target. Try:
- (eepitch-python)
- (eepitch-kill)
- (eepitch-python)
-def square (x):
- return x*x
+3. Elisp hyperlinks buffers conventions
+=======================================
+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
+be expanded later:
-print(square(5))
+ 1) C-h buffers are usually named \"*Help*\", while
+ M-h buffers are usually named \"*Elisp Hyperlinks*\";
- We can use several targets at the time, alternating between them.
- For example:
+ 2) C-h buffers are generated by functions called \"describe-*\",
+ M-h buffers are generated by functions called \"find-*-links\";
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-echo Hello... > /tmp/o
+ 3) C-h buffers may contain \"usual-looking\" links, that can be
+ followed by typing RET on them, and this is implemented via
+ \"buttons\"; C-h buffers are \"ascii plus text properties\",
+ while M-h buffers are plain ascii;
- (eepitch-python)
- (eepitch-kill)
- (eepitch-python)
-print(open(\"/tmp/o\").read())
+ 4) C-h buffers are read-only, while
+ M-h buffers are read-and-write. The idea is that we can not
+ only follow the hyperlinks in a M-h buffer but also modify
+ them - usually by \"refining\" them, like this,
- (eepitch-shell)
-echo ...and bye >> /tmp/o
+ (find-eval-intro \"Refining hyperlinks\")
- (eepitch-python)
-print(open(\"/tmp/o\").read())
+ then test the modified versions, and copy-and-paste those
+ hyperlinks to other, more permanent places. This is much
+ easier to do when we are working in plain ascii; the buttons
+ in C-h buffers are non-trivial to create, to edit and to
+ save.
+ 5) C-h buffers are _readable_, while
+ M-h buffers may look like (technical) gibberish.
- There is a (much) more advanced example of working with several
- targets here:
+ This is intentional - M-h buffers have a do-it-yourself,
+ \"I'm the result of a 5-minute hack\" feeling because most
+ of them started just like that, as 5-minute hacks that
+ turned out to be useful enough, and only suffered very minor
+ changes later on. Try this:
- (find-prepared-intro \"An `ee' for Python\")
+ (find-find-links-links)
+ Most `find-*-links' were created from that template - and it
+ should be easy to create other ones.
+ 5) Many `M-h' commands, like `M-h f' and `M-h M-i', generate
+ sexp hyperlinks that \"point to where we are now\"; but once
+ we are in an M-h buffer this idea - whose basis is:
+ from (almost) anywhere in Emacs it should to be easy to
+ create a hyperlink to where we are now - changes to:
+ 6) The first line (the \"top sexp\") of an M-h buffer
+ regenerates the buffer. And, at last,
+ 7) The elisp hyperlinks in M-h buffers are prefixed by the
+ string in `ee-hyperlink-prefix'.
-More on eepitch-kill
-====================
-Note that `(eepitch-kill)' kills the _current_ target, that may
-or may not be a shell buffer, a Python interaction buffer, etc...
-That explains the first line in blocks like:
- (eepitch-python)
- (eepitch-kill)
- (eepitch-python)
-and:
+4. `find-here-links'
+====================
+The most important of the commands that generates buffers with elisp
+hyperlinks - \"M-h commands\", in the terminology explained above - is
+`find-here-links', which integrates most of the functionalities of
+several more basic M-h commands. We will explain first what it _does_,
+then its _usage_.
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
+`find-here-links' is bound to `M-h M-h' to make it very easy to
+invoke. If you are reading this then \"here\" means the buffer
+\"*(find-links-intro)*\", in a certain position. Try to type `M-h M-h';
+you will get a buffer like this,
-by running the first `(eepitch-python)' we can be sure that the
-following `(eepitch-kill)' will kill the Python buffer, not the
-shell buffer! And the last `(eepitch-python)' in the block of
-three lines will then create a new Python interaction buffer,
-erasing all definitions done in previous sessions.
+ ____________________________________________________________
+ |# See: |
+ |# (find-links-intro \"`find-here-links'\") |
+ |# (find-efunctiondescr 'eev-mode \"M-h M-h\") |
+ | |
+ |# (find-links-intro) |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
+ |____________________________________________________________|
+which contains a 3-line header with help links, that we will explain
+soon, and then a link to \"here\", i.e., to the buffer
+\"*(find-links-intro)*\". Note that the link
+ (find-links-intro)
+can be \"refined\" to, for example,
-Creating eepitch blocks: `M-T'
-==============================
-Write just \"shell\" or \"python\" in a line, then type
-`M-T' (i.e., meta-shift-t) there. The line will be turned into
-three - an \" (eepitch-xxx)\", an \" (eepitch-kill)\", and an
-\" (eepitch-xxx)\". We call these blocks of three lines
-\"eepitch blocks\". Try this below, converting the \"shell\" into
-an eepitch block for starting a shell.
+ (find-links-intro \"which contains a 3-line header\")
-shell
-pwd
-cd /tmp/
-pwd
+using the tricks described in these sections:
+ (find-eval-intro \"Refining hyperlinks\")
+ (find-eval-intro \"Producing and refining hyperlinks\")
+ (find-eval-intro \"Producing and refining hyperlinks\" \"`M-h M-2'\")
+ (find-eval-intro \"Producing and refining hyperlinks\" \"`M-h2hy'\")
+but `find-here-links' by itself only produces \"unrefined\" links - so
+when we say that `find-here-links' produces links to \"here\" we mean
+just \"to the current buffer\", not \"to the a certain position in the
+current buffer\".
+`find-here-links' works for several kinds of \"here\"s - it works for
+intros like this one, for Info pages, for manpages, for files and
+directories, for descriptions of Emacs functions and variables, and
+for a few other cases. Try the sexps below:
-Red stars
-=========
-Eepitch.el sets the glyph for the char 15 to a red star in the
-standard display table. In layman's terms: eepitch.el tells Emacs
-that the character 15 should be displayed as a red star. The
-character 15 corresponds to control-O, whose default
-representation on screen would be \"^O\". You can enter a
-literal ^O in a buffer by typing `C-q C-o'.
+ (find-here-links-test '(find-eval-intro))
+ (find-here-links-test '(find-node \"(dir)Top\"))
+ (find-here-links-test '(find-enode \"Lisp Eval\"))
+ (find-here-links-test '(find-fline \"~/\"))
+ (find-here-links-test '(find-eevfile \"eepitch.el\"))
+ (find-here-links-test '(find-efunction 'ee-eval-last-sexp))
+ (find-here-links-test '(find-efunctiondescr 'ee-eval-last-sexp))
+ (find-here-links-test '(find-evardescr 'ee-hyperlink-prefix))
+ (find-here-links-test '(find-efacedescr 'eepitch-star-face))
+ (find-here-links-test '(find-ecolors \"\\nred\"))
+ (find-here-links-test '(find-efaces \"eepitch-star-face\"))
+ (find-here-links-test '(find-customizegroup 'rcirc))
-For more information
-====================
-On hyperlinks: (find-eval-intro)
-On keys similar to `M-T': (find-wrap-intro)
-An older text about eepitch:
- (find-eev \"eepitch.readme\")
- (find-eev \"eepitch.readme\" \"the-trivial-case\")
- (find-eev \"eepitch.readme\" \"red-stars\")
- (find-eev \"eepitch.readme\" \"eepitch-blocks\")
- (find-eev \"eepitch.readme\" \"eepitch-blocks\")
-Many functions like `eepitch-shell':
- (find-efunction 'eepitch-bash)
-What functions can generate target buffers:
- (find-eevfile \"eepitch.el\" \"shell-like sexp\")
- (find-efunction 'eepitch)
-" rest)))
+ (find-here-links-test '(find-man \"1 cat\"))
+ [^ oops, this test doesn't work on multi-window settings...]
-;; (find-eepitch-intro)
+Each one of them tests a different case of `find-here-links',
+creating a window setup like this:
-;; (find-pytutnode "Methods of File Objects")
+ ______________________________________
+ | | |
+ | | target of |
+ | | sexp |
+ | this |______________________|
+ | intro | |
+ | | result of running |
+ | | find-here-links on |
+ | | [target of sexp] |
+ |_______________|______________________|
+The cursor is kept at the left window (\"this intro\"), so you
+can compare the different cases using just <up>, <down>, and M-e.
-;;; _ _
-;;; __ ___ __ __ _ _ __ (_)_ __ | |_ _ __ ___
-;;; \ \ /\ / / '__/ _` | '_ \ _____| | '_ \| __| '__/ _ \
-;;; \ V V /| | | (_| | |_) |_____| | | | | |_| | | (_) |
-;;; \_/\_/ |_| \__,_| .__/ |_|_| |_|\__|_| \___/
-;;; |_|
-;;
-;; (find-intro-links "wrap")
-;; �find-wrap-intro� (to ".find-wrap-intro")
-(defun find-wrap-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-wrap-intro)*"))
- (apply 'find-estring-lv "\
-\(Re)generate: (find-wrap-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-wrap-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.
+5. `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
+\"e-script\". Then we start to navigate for information, and we find
+something interesting. We want to add a link pointing to that
+\"something interesting\" to our e-script notes - but for that we need
+to produce that sexp hyperlink, and ideally we would like to do that
+in a way that does not disturb much our attention. Consider this
+diagram [note: it DOES NOT imply that the Emacs frame is split into three
+windows - typically we will switch between buffers in a single window]:
+ ______________________________________
+ | | |
+ | | something |
+ | ==> interesting |
+ | e-script |_________||___________|
+ | | \\/ |
+ | | result of running |
+ | <== find-here-links on |
+ | | [sthing intrstng] |
+ |_______________|______________________|
+and this series of steps:
-For an introduction to the ideas here, see:
- (find-eev-quick-intro \"6. Controlling shell-like programs\")
+ 0. We start navigating from the e-script buffer, and when we
+ 1. find something interesting [in another buffer], we
+ 2. run `find-here-links' at the \"something interesting\" buffer,
+ 3. identify among the sexps in the find-here-links buffer one that
+ points to that \"something interesting\",
+ 4. copy that sexp to the kill-ring,
+ 5. go back to the e-script buffer,
+ 6. insert that sexp into the e-script buffer,
+ 7. execute that sexp to go back to the \"something interesting\",
+ 8. continue navigating & doing stuff.
+At (8) we are essentially back to (1), but we have added to our
+e-script buffer a link to \"something interesting\".
+Note that to add refining we need to add a step before (2) and
+another one after (3):
-Eepitch and eev
-===============
-Eepitch defines only two keys - <F8> and <M-T> - and <M-T> is a
-particular case of something more general: \"wrapping commands\", that
-follow these conventions:
+ 1.9. select a string to search for and copy it to the kill-ring,
+ 3.1. refine that sexp using the \"string to search for\" (with M-h2hy)
- 1) they are bound to meta-shift-letter keys (M-T, M-F, M-M, ...),
- 2) they transform the current line and then move down,
- 3) they produce Lisp code meant to be executed with `M-e' or `F8',
- 4) they are listed at:
- (find-efunctiondescr 'eev-mode \"M-F\")
- 5) their keybindings are only available when eev-mode is turned on.
+\[TO DO: explain the keys that I normally use to perform all
+this; explain why I am not the right person to optimize these
+steps - because I can type these key sequences without thinking,
+and step (3) sometimes gives several sexps for us to choose from]
-To understand how they work, please follow the instructions below and
-try them here. Note that this buffer is a sandbox, and it can be
-recreated by executing the sexp \"(find-wrap-intro)\" at the top.
-Note that the wrapping commands are all bound to key sequences of
-the form meta-SHIFT-letter - don't forget the shift!!!
+6. 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?
-<M-T>: produce an eepitch block
-===============================
-If you type <M-T> on a line containing just the word \"shell\" you get
-three lines, like this:
+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
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
+ (find-efunction-links 'find-file)
-We call a block of three lines like this an \"eepitch block\", and
-eepitch blocks can be used to set up interactions with external
-programs. Try typing <M-T> on the lines that say \"shell\" and \"python\"
-below, and use them to send some lines to bash and to a python
-interpreter (with <F8>):
+these hyperlinks
-bash
-export PS1='$PWD% '
-cd /tmp/
-function ee () { set -v; . /tmp/ee.sh; set +v; }
-rm -v /tmp/ee.sh
-cat > /tmp/ee.sh <<'%%%'
- echo Hello
- cd /etc/
-%%%
-cat /tmp/ee.sh
-bash /tmp/ee.sh
-ee
+ (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))
-python
-square = lambda x: x*x
-square(5)
+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:
-<M-F>: hyperlink to a file or a directory
-=========================================
-If you type <M-F> on the lines below,
+ (find-code-c-d-intro)
+ (find-pdf-like-intro)
+ (find-audiovideo-intro)
-/etc/
-/tmp/
-~/
-~/.emacs
+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:
-you get hyperlinks like these:
+ (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\")
-# (find-fline \"/etc/\")
-# (find-fline \"/tmp/\")
-# (find-fline \"~/\")
-# (find-fline \"~/.emacs\")
+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.
-<M-S>: hyperlink to the output of a shell command
-=================================================
-If you type <M-S> on a line containing a shell command you get a
-hyperlink that starts with `find-sh', and that when followed opens a
-temporary buffer with the output of that shell command, like these:
- # (find-sh \"find --help\")
- # (find-sh \"find /etc | sort\")
- # (find-sh \"find /etc -type d | sort\")
- # (find-sh \"find /etc -type d -maxdepth 1 | sort\")
- # (find-sh \"find /etc -type d -maxdepth 2 | sort\")
-Try it here:
-dict smop
-dict 'minor detail'
+7. 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
+the inspiration for all the `find-*-links' functions.
-If you have the packages dict, dictd and dict-jargon installed
-these hyperlinks will show you the meaning of the expressions
-\"smop\" and \"minor detail\".
+If you run `M-x ee-hyperlink-prefix' you should get a buffer like
+this:
- # (find-sh \"dict smop\")
- # (find-sh \"dict 'minor detail'\")
+ ___________________________________________________________
+ |# (ee-hyperlink-prefix) |
+ |# (setq ee-hyperlink-prefix \"# \") |
+ | |
+ |# (setq ee-hyperlink-prefix \"# \") |
+ |# (setq ee-hyperlink-prefix \";; \") |
+ |# (setq ee-hyperlink-prefix \"-- \") |
+ |# (setq ee-hyperlink-prefix \"// \") |
+ |# (setq ee-hyperlink-prefix \"% \") |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
+ |___________________________________________________________|
+where the first line regenerates the buffer, the second line sets
+the variable `ee-hyperlink-prefix' to its current value, and each
+one of the lines after the first blank line sets
+`ee-hyperlink-prefix' to one of several fixed common values. If
+we change the value of `ee-hyperlink-prefix' with one of the
+`setq's and execute the first line again we see that all the
+prefixes, plus the argument \"# \" in the second line, change.
+Try this, with `M-2 M-e' on each line:
+ (progn (setq ee-hyperlink-prefix \"# \") (ee-hyperlink-prefix))
+ (progn (setq ee-hyperlink-prefix \"% \") (ee-hyperlink-prefix))
-<M-M>: hyperlink to a manpage
-=============================
-Try <M-M> here:
-1 tac
+8. The first line regenerates the buffer
+========================================
+\[To do: explain this convention with examples; explain the
+conventions for the \"variants of the first line\"\]
-All wrapping functions
-======================
-Below is a list of all wrapping functions, with tests and
-hyperlinks:
+ (find-find-links-links)
+ (find-find-links-links \"\\\\M-u\")
+ (find-find-links-links \"\\\\M-u\" \"USERTEST\")
+ (find-find-links-links \"\\\\M-u\" \"USERTEST\" \"a\")
+ (find-find-links-links \"\\\\M-u\" \"USERTEST\" \"a b\")
+ (find-find-links-links \"\\\\M-u\" \"USERTEST\" \"a b c\")
- (eek \"2*<down> M-A <down> ;;; Test eewrap-anchor\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-anchor\")
-;; <anchor>
- (eek \"2*<down> M-C <down> ;;; Test eewrap-code-c-d\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-code-c-d\")
-foo /tmp/foobar/
- (eek \"2*<down> M-D <down> ;;; Test eewrap-debian\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-debian\")
-bash
+9. 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,
+to the current Info page, to the current `find-*-intro', to an
+Emacs function or variable we are inspecting, to the current
+buffer, and so on. They don't try to be very smart -
- (eek \"2*<down> M-F <down> ;;; Test eewrap-find-fline\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-find-fline\")
-/tmp/foobar/
+\[To do: write this\]
- (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
-422 (find-eev-intro \"find-wrap-intro\")
+ (find-efunctiondescr 'eev-mode)
+ (find-efunctiondescr 'eev-mode \"M-h f\")
- (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
-42
+ (eek \"M-h M-i\")
- (eek \"2*<down> M-M <down> ;;; Test eewrap-man\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-man\")
-1 tac
+ (find-enode \"Lisp Eval\")
+ (progn (find-enode \"Lisp Eval\") (eek \"M-h M-i\"))
- (eek \"2*<down> M-P <down> ;;; Test eewrap-pdflike\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-pdflike\")
-foopdf $S/http/foo.org/bar.pdf
+ (eek \"M-h f ;; find-file-links\")
+ (eek \"M-h M-b ;; find-ebuffer-links\")
- (eek \"2*<down> M-R <down> ;;; Test eewrap-rm/mkdir/cd\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-rm/mkdir/cd\")
-/tmp/foo/
+ for example, `M-h M-i' generates links to
+ the current \"intro\" buffer - like this one - _and_ to the
+ current Info page (the \"i\" in `M-h M-i' has two meanings).
+ Try:
- (eek \"2*<down> M-S <down> ;;; Test eewrap-sh\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-sh\")
-seq 1 20
+ (eek \"M-h M-i\")
- (eek \"2*<down> M-T <down> ;;; Test eewrap-eepitch\")
- Source: (find-eev \"eepitch.el\" \"eewrap-eepitch\")
-python
+ you should get something like this:
- (eek \"2*<down> M-V <down> ;;; Test eewrap-audiovideo\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-audiovideo\")
-slimetutorial /tmp/slime-tutorial.mp4
+ ___________________________________________________________
+ |# (find-einfo-links \"links\") |
+ | |
+ |[No \"*info*\" buffer] |
+ | |
+ |# (find-links-intro) |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
+ |___________________________________________________________|
- (eek \"2*<down> M-Z <down> ;;; Test eewrap-zsh\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-zsh\")
-echo $SHELL
- (eek \"2*<down> <<eewrap-eewrap>> <down> ;;; Test eewrap-eewrap\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-eewrap\")
-U user-defined a b c
+10. 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
+example is
+ (find-eev-update-links)
+which ends with stuff that you can copy to your .emacs file to
+make Emacs load eev by default. The end of the buffer generated
+by `find-eev-update-links' looks more or less like this:
-Wrapping functions generate hyperlinks
-======================================
-...this is a slogan - a huge idea, in a very shortened form. In its
-full form, that would be:
+ ____________________________________________________________
+ |# (ee-copy-rest 0 '(find-fline \"~/.emacs\")) |
+ | |
+ |;; Load eev2. |
+ |;; See: (find-file \"~/eev/\") |
+ |;; (find-file \"~/eev/eev-readme.el\") |
+ |;; Generated by: (find-eev-update-links \"~/eev/\") |
+ |;; |
+ |(add-to-list 'load-path \"~/eev/\") |
+ |(require 'eev2-all) ; (find-eev \"eev2-all.el\") |
+ |(eev-mode 1) ; (find-eev \"eev-mode.el\") |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* Bot L56 (Fundamental eev)---|
+ |____________________________________________________________|
- (Some) wrapping function provide one of the basic ways to produce
- elisp hyperlinks quickly; the second basic way, which is a bit more
- complex conceptually, is via Elisp hyperlinks buffers. This, and the
- whole rationale behind generating and using elisp hyperlinks, is
- explained here:
+The line with `ee-copy-rest' is a hack. Its first argument is a
+number, that we will call the \"skip\", and the second is
+a (quoted) sexp hyperlink, that we will call the \"code\". The
+rule that defines what is the \"rest of the buffer\" is this:
- (find-links-intro \"Elisp hyperlinks buffers\")
+ Move to the beginning of the next line, then skip (i.e., move
+ down) more SKIP lines. The rest of the buffer is everything
+ from that point on.
-The \"some\" in beginning of the long version of the slogan, above, is
-because a few of the wrapping commands, for example, <M-T> and <M-R>,
-are used to produce things that are not hyperlinks - usually other
-kinds of scripts.
+A sexp like `(ee-copy-rest ...)' does several things:
+
+ 1) it highlights the rest of the buffer temporarily (like as
+ with `M-0 M-e'),
+ 2) it copies the rest of the buffer to the kill ring (like as
+ with `M-w'),
+
+ 3) it runs CODE to open its target in a window at the right
+ side (like as with `M-3 M-e')
+\[To do: add examples - including examples that let us create Lua
+scripts etc\]
-# Local Variables:
-# coding: raw-text-unix
-# ee-anchor-format: \"�%s�\"
-# End:
" rest)))
-;; (find-wrap-intro)
+;; (find-links-intro)
+;; (find-eevfile "eev-template.el" "defun find-efunction-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)*"))
+
+;;; _ _ _
+;;; ___ ___ _ __ (_) |_ ___| |__
+;;; / _ \/ _ \ '_ \| | __/ __| '_ \
+;;; | __/ __/ |_) | | || (__| | | |
+;;; \___|\___| .__/|_|\__\___|_| |_|
+;;; |_|
+;;
+;; �find-eepitch-intro� (to ".find-eepitch-intro")
+;; (find-intro-links "eepitch")
+;; (find-eev "eepitch.readme")
+
+(defun find-eepitch-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-eepitch-intro)*"))
(apply 'find-estring "\
-\(Re)generate: (find-links-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-links-intro\")
+\(Re)generate: (find-eepitch-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-eepitch-intro\")
More intros: (find-eev-quick-intro)
(find-eval-intro)
- (find-eepitch-intro)
+ (find-wrap-intro)
This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
+Is is meant as both a tutorial (for eepitch) and a sandbox.
+Note: this intro needs to be rewritten!
+Ideally it should _complement_ the material in:
+ (find-eev-quick-intro \"6. Controlling shell-like programs\")
-1. What is a hyperlink?
-=======================
-In a previous tutorial - (find-eval-intro) - we saw that several
-kinds of sexps can be used as hyperlinks. For example, these:
- (find-fline \"/tmp/\")
- (find-node \"(emacs)Lisp Eval\")
- (find-efunctiondescr 'find-file)
- (find-efunction 'find-file)
- (find-man \"cat\")
-Hyperlinks in a web browser _usually_ take us to a different
-page, or to a different position in the same page, and in those
-cases it is possible to go back to previous position from there;
-but sometimes hyperlinks - or webpage buttons - are associated to
-Javascript code, and \"following the link\" then means executing
-that code. Web browsers try to make it impossible to have
-hyperlinks or webpages that will send out your private
-information, or that will put your system in a unusable state.
-Security is web browsers is achieved by restricting what the
-scripts in a page can do.
-Sexp hyperlinks, in contrast, can do essentially anything - and,
-instead of _security_, they have _transparency_. The code that a
-sexp hyperlink will execute is visible, and users are supposed to
-know that sexp hyperlinks with `find-fline', `find-node',
-`find-efunctiondescr', etc, are very safe - but the ones that
-start with `find-sh' may not be. It is possible to write
-something like:
+The motivation for eepitch: taking notes and redoing
+====================================================
+Suppose that we have to do some reasonably complex task using a
+shell, and that we want to take notes of what we do because we
+might have to do something similar later.
- (find-sh \"<code that deletes all your e-mails>\")
+The two usual ways to interact with a shell are:
-but it is not possible to hide that action behind an
-innocent-looking button that says \"click for a larger image\".
+ 1) through a _script_, that is, by preparing in advance all
+ commands to be executed, putting them in a script file, and
+ then running that file,
-So, _any_ elisp sexp can be _used_ as a sexp hyperlink; but
-people are only going to follow a sexp hyperlink if they can more
-or less predict (quickly!) what that hyperlink is going to do...
-Readability is important, so let's take a look at the most common
-kinds of hyperlinks.
+ 2) _interactively_, by typing the commands one by one on a
+ shell prompt.
+Suppose that we have to discover which commands to run as we go;
+that rules out preparing a script beforehand, so we need to use
+the shell interactively. After issuing the right commands, the
+two usual ways to retrieve what we did are:
+ a) through the _shell history_, which records the last commands
+ that the shell received,
+ b) by looking at the full _transcript_ of our interaction with
+ the shell.
-2. Elisp 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 generated help buffers have hyperlinks,
-that can be followed by typing <RET> on them.
+The way (a) gets a list of commands, without comments, that can
+be then saved into a text editor; the way (b) may require some
+tricky editing to isolate the commands from their outputs.
-Eev has something similar, but using the prefix `M-h' and
-following very different design decisions. Let's start with a
-comparison, between Emacs's `C-h f' (`describe-function') and
-eev's `M-h M-f' (`find-efunction-links'). Remember that `M-e'
-accepts prefix arguments, and that `M-2 M-e' displays the target
-of a hyperlink at another window without switching to there; use
-that on the two sexps below to see the results by yourself:
+Eepitch.el implements a simple alternative way of interacting
+with shells (and other shell-like programs) while keeping notes.
+It has only one essential key binding, <F8>, which is better
+explained through the executable example in the next section, and
+two unessential features, `M-T' and \"\", which will be
+explained later.
- \"C-h f find-file\" -> (find-efunctiondescr 'find-file)
- \"M-h M-f find-file\" -> (find-efunction-links 'find-file)
-Note that we used `find-efunctiondescr' instead of
-`describe-function'; `find-efunctiondescr' is a variant of
-`describe-function' that that follows eev's conventions, as
-explained here:
- (find-eval-intro \"main conventions\")
+The main key: <F8>
+==================
+Emacs can run a shell in a buffer, and it can split its frame
+into windows, like this:
+ ___________________
+ | | |
+ | our | a |
+ | notes | shell |
+ | | buffer |
+ |_________|_________|
-`C-h f find-file' produces a buffer with readable text and
-\"usual\" hyperlinks that can be followed by typing RET on them,
-while `M-h M-f find-file' produces a buffer like this:
+The usual way to use a shell buffer is to move the cursor there
+and type commands into its prompt; the eepitch-y way is to leave
+the cursor at the \"notes\" buffer, write the commands for the
+shell there, and send these commands to the shell with <F8>.
- ___________________________________________________________
- |# (find-efunction-links 'find-file) |
- |# (where-is 'find-file) |
- |# (describe-function 'find-file) |
- |# (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)) |
- |# (symbol-file 'find-file 'defun) |
- |# (find-fline (symbol-file 'find-file 'defun)) |
- | |
- |# (Info-goto-emacs-command-node 'find-file) |
- |# (find-enode \"Command Index\" \"* find-file:\") |
- |# (find-elnode \"Index\" \"* find-file:\") |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
- |___________________________________________________________|
+Here's what <F8> does:
-What is that?...
+ When we type <F8> on a line that starts with a red
+ star (\"\"), it executes the rest of the line as Lisp, and
+ moves down; when we type <F8> on a line that does not start
+ with a \"\", it makes sure that the \"target buffer\" is being
+ displayed (the \"target\" is usually the buffer called
+ \"*shell*\"), it \"send\"s the current line to the target
+ buffer, and moves down.
+ \"Sending the current line to the target buffer\" means copying
+ the contents of the current line to the target - as if the user
+ had typed that line there by hand -, then \"typing\" a <RET> at
+ the target buffet.
+Please try that in the example after this paragraph, by typing
+<F8> six times starting at the first line that says
+\" (eepitch-shell)\". The three red star lines at the top will
+create a target buffer, destroy it, and create it again; the
+other three lines will send commands to the target shell.
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+echo \"We are at: $PWD\"
+cd /tmp/
+echo \"We changed to: $(pwd)\"
-3. Elisp hyperlinks buffers conventions
-=======================================
-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
-be expanded later:
- 1) C-h buffers are usually named \"*Help*\", while
- M-h buffers are usually named \"*Elisp Hyperlinks*\";
- 2) C-h buffers are generated by functions called \"describe-*\",
- M-h buffers are generated by functions called \"find-*-links\";
- 3) C-h buffers may contain \"usual-looking\" links, that can be
- followed by typing RET on them, and this is implemented via
- \"buttons\"; C-h buffers are \"ascii plus text properties\",
- while M-h buffers are plain ascii;
+Other targets
+=============
+Just like `(eepitch-shell)' creates a shell buffer and sets the
+eepitch target to it, `(eepitch-python)' creates a buffer with a
+Python interpreter and uses it as the eepitch target. Try:
- 4) C-h buffers are read-only, while
- M-h buffers are read-and-write. The idea is that we can not
- only follow the hyperlinks in a M-h buffer but also modify
- them - usually by \"refining\" them, like this,
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
+def square (x):
+ return x*x
- (find-eval-intro \"Refining hyperlinks\")
+print(square(5))
- then test the modified versions, and copy-and-paste those
- hyperlinks to other, more permanent places. This is much
- easier to do when we are working in plain ascii; the buttons
- in C-h buffers are non-trivial to create, to edit and to
- save.
+ We can use several targets at the time, alternating between them.
+ For example:
- 5) C-h buffers are _readable_, while
- M-h buffers may look like (technical) gibberish.
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+echo Hello... > /tmp/o
- This is intentional - M-h buffers have a do-it-yourself,
- \"I'm the result of a 5-minute hack\" feeling because most
- of them started just like that, as 5-minute hacks that
- turned out to be useful enough, and only suffered very minor
- changes later on. Try this:
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
- (find-find-links-links)
+ (eepitch-shell)
+echo ...and bye >> /tmp/o
- Most `find-*-links' were created from that template - and it
- should be easy to create other ones.
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
- 5) Many `M-h' commands, like `M-h f' and `M-h M-i', generate
- sexp hyperlinks that \"point to where we are now\"; but once
- we are in an M-h buffer this idea - whose basis is:
- from (almost) anywhere in Emacs it should to be easy to
- create a hyperlink to where we are now - changes to:
- 6) The first line (the \"top sexp\") of an M-h buffer
- regenerates the buffer. And, at last,
+ There is a (much) more advanced example of working with several
+ targets here:
- 7) The elisp hyperlinks in M-h buffers are prefixed by the
- string in `ee-hyperlink-prefix'.
+ (find-prepared-intro \"An `ee' for Python\")
-4. `find-here-links'
+
+
+More on eepitch-kill
====================
-The most important of the commands that generates buffers with elisp
-hyperlinks - \"M-h commands\", in the terminology explained above - is
-`find-here-links', which integrates most of the functionalities of
-several more basic M-h commands. We will explain first what it _does_,
-then its _usage_.
+Note that `(eepitch-kill)' kills the _current_ target, that may
+or may not be a shell buffer, a Python interaction buffer, etc...
+That explains the first line in blocks like:
-`find-here-links' is bound to `M-h M-h' to make it very easy to
-invoke. If you are reading this then \"here\" means the buffer
-\"*(find-links-intro)*\", in a certain position. Try to type `M-h M-h';
-you will get a buffer like this,
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
- ____________________________________________________________
- |# See: |
- |# (find-links-intro \"`find-here-links'\") |
- |# (find-efunctiondescr 'eev-mode \"M-h M-h\") |
- | |
- |# (find-links-intro) |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
- |____________________________________________________________|
+and:
+
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+
+by running the first `(eepitch-python)' we can be sure that the
+following `(eepitch-kill)' will kill the Python buffer, not the
+shell buffer! And the last `(eepitch-python)' in the block of
+three lines will then create a new Python interaction buffer,
+erasing all definitions done in previous sessions.
+
+
+
+
+Creating eepitch blocks: `M-T'
+==============================
+Write just \"shell\" or \"python\" in a line, then type
+`M-T' (i.e., meta-shift-t) there. The line will be turned into
+three - an \" (eepitch-xxx)\", an \" (eepitch-kill)\", and an
+\" (eepitch-xxx)\". We call these blocks of three lines
+\"eepitch blocks\". Try this below, converting the \"shell\" into
+an eepitch block for starting a shell.
+
+shell
+pwd
+cd /tmp/
+pwd
+
+
+
+
+Red stars
+=========
+Eepitch.el sets the glyph for the char 15 to a red star in the
+standard display table. In layman's terms: eepitch.el tells Emacs
+that the character 15 should be displayed as a red star. The
+character 15 corresponds to control-O, whose default
+representation on screen would be \"^O\". You can enter a
+literal ^O in a buffer by typing `C-q C-o'.
+
+
+
+For more information
+====================
+On hyperlinks: (find-eval-intro)
+On keys similar to `M-T': (find-wrap-intro)
+An older text about eepitch:
+ (find-eev \"eepitch.readme\")
+ (find-eev \"eepitch.readme\" \"the-trivial-case\")
+ (find-eev \"eepitch.readme\" \"red-stars\")
+ (find-eev \"eepitch.readme\" \"eepitch-blocks\")
+ (find-eev \"eepitch.readme\" \"eepitch-blocks\")
+Many functions like `eepitch-shell':
+ (find-efunction 'eepitch-bash)
+What functions can generate target buffers:
+ (find-eevfile \"eepitch.el\" \"shell-like sexp\")
+ (find-efunction 'eepitch)
+" rest)))
+
+;; (find-eepitch-intro)
+
+;; (find-pytutnode "Methods of File Objects")
+
+
+
+
+;;;
+;;; __ ___ __ __ _ _ __
+;;; \ \ /\ / / '__/ _` | '_ \
+;;; \ V V /| | | (_| | |_) |
+;;; \_/\_/ |_| \__,_| .__/
+;;; |_|
+;;
+;; (find-intro-links "wrap")
+;; �find-wrap-intro� (to ".find-wrap-intro")
+
+(defun find-wrap-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-wrap-intro)*"))
+ (apply 'find-estring-lv "\
+\(Re)generate: (find-wrap-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-wrap-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 needs to be rewritten!
+Ideally it should _complement_ the material in:
+ (find-eev-quick-intro \"6.3. Creating eepitch blocks: `M-T'\")
+ (find-eev-quick-intro \"8.3. Creating index/section anchor pairs\")
+ (find-eev-quick-intro \"8.4. Creating e-script blocks\")
+
+
+
+
+
+Eepitch and eev
+===============
+Eepitch defines only two keys - <F8> and <M-T> - and <M-T> is a
+particular case of something more general: \"wrapping commands\", that
+follow these conventions:
+
+ 1) they are bound to meta-shift-letter keys (M-T, M-F, M-M, ...),
+ 2) they transform the current line and then move down,
+ 3) they produce Lisp code meant to be executed with `M-e' or `F8',
+ 4) they are listed at:
+ (find-efunctiondescr 'eev-mode \"M-F\")
+ 5) their keybindings are only available when eev-mode is turned on.
+
+To understand how they work, please follow the instructions below and
+try them here. Note that this buffer is a sandbox, and it can be
+recreated by executing the sexp \"(find-wrap-intro)\" at the top.
+
+Note that the wrapping commands are all bound to key sequences of
+the form meta-SHIFT-letter - don't forget the shift!!!
+
+
+
+<M-T>: produce an eepitch block
+===============================
+If you type <M-T> on a line containing just the word \"shell\" you get
+three lines, like this:
+
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+
+We call a block of three lines like this an \"eepitch block\", and
+eepitch blocks can be used to set up interactions with external
+programs. Try typing <M-T> on the lines that say \"shell\" and \"python\"
+below, and use them to send some lines to bash and to a python
+interpreter (with <F8>):
+
+bash
+export PS1='$PWD% '
+cd /tmp/
+function ee () { set -v; . /tmp/ee.sh; set +v; }
+rm -v /tmp/ee.sh
+cat > /tmp/ee.sh <<'%%%'
+ echo Hello
+ cd /etc/
+%%%
+cat /tmp/ee.sh
+bash /tmp/ee.sh
+ee
+
+python
+square = lambda x: x*x
+square(5)
+
+
+
+<M-F>: hyperlink to a file or a directory
+=========================================
+If you type <M-F> on the lines below,
+
+/etc/
+/tmp/
+~/
+~/.emacs
+
+you get hyperlinks like these:
+
+# (find-fline \"/etc/\")
+# (find-fline \"/tmp/\")
+# (find-fline \"~/\")
+# (find-fline \"~/.emacs\")
+
+
+
+<M-S>: hyperlink to the output of a shell command
+=================================================
+If you type <M-S> on a line containing a shell command you get a
+hyperlink that starts with `find-sh', and that when followed opens a
+temporary buffer with the output of that shell command, like these:
+
+ # (find-sh \"find --help\")
+ # (find-sh \"find /etc | sort\")
+ # (find-sh \"find /etc -type d | sort\")
+ # (find-sh \"find /etc -type d -maxdepth 1 | sort\")
+ # (find-sh \"find /etc -type d -maxdepth 2 | sort\")
+
+Try it here:
+
+dict smop
+dict 'minor detail'
+
+If you have the packages dict, dictd and dict-jargon installed
+these hyperlinks will show you the meaning of the expressions
+\"smop\" and \"minor detail\".
+
+ # (find-sh \"dict smop\")
+ # (find-sh \"dict 'minor detail'\")
+
+
+
+<M-M>: hyperlink to a manpage
+=============================
+Try <M-M> here:
+
+1 tac
+
+
+
+All wrapping functions
+======================
+Below is a list of all wrapping functions, with tests and
+hyperlinks:
+
+ (eek \"2*<down> M-A <down> ;;; Test eewrap-anchor\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-anchor\")
+;; <anchor>
+
+ (eek \"2*<down> M-C <down> ;;; Test eewrap-code-c-d\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-code-c-d\")
+foo /tmp/foobar/
+
+ (eek \"2*<down> M-D <down> ;;; Test eewrap-debian\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-debian\")
+bash
+
+ (eek \"2*<down> M-F <down> ;;; Test eewrap-find-fline\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-find-fline\")
+/tmp/foobar/
+
+ (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
+422 (find-eev-intro \"find-wrap-intro\")
+
+ (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
+42
+
+ (eek \"2*<down> M-M <down> ;;; Test eewrap-man\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-man\")
+1 tac
+
+ (eek \"2*<down> M-P <down> ;;; Test eewrap-pdflike\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-pdflike\")
+foopdf $S/http/foo.org/bar.pdf
+
+ (eek \"2*<down> M-R <down> ;;; Test eewrap-rm/mkdir/cd\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-rm/mkdir/cd\")
+/tmp/foo/
+
+ (eek \"2*<down> M-S <down> ;;; Test eewrap-sh\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-sh\")
+seq 1 20
+
+ (eek \"2*<down> M-T <down> ;;; Test eewrap-eepitch\")
+ Source: (find-eev \"eepitch.el\" \"eewrap-eepitch\")
+python
+
+ (eek \"2*<down> M-V <down> ;;; Test eewrap-audiovideo\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-audiovideo\")
+slimetutorial /tmp/slime-tutorial.mp4
+
+ (eek \"2*<down> M-Z <down> ;;; Test eewrap-zsh\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-zsh\")
+echo $SHELL
+
+ (eek \"2*<down> <<eewrap-eewrap>> <down> ;;; Test eewrap-eewrap\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-eewrap\")
+U user-defined a b c
+
+
+
+
+Wrapping functions generate hyperlinks
+======================================
+...this is a slogan - a huge idea, in a very shortened form. In its
+full form, that would be:
+
+ (Some) wrapping function provide one of the basic ways to produce
+ elisp hyperlinks quickly; the second basic way, which is a bit more
+ complex conceptually, is via Elisp hyperlinks buffers. This, and the
+ whole rationale behind generating and using elisp hyperlinks, is
+ explained here:
+
+ (find-links-intro \"Elisp hyperlinks buffers\")
+
+The \"some\" in beginning of the long version of the slogan, above, is
+because a few of the wrapping commands, for example, <M-T> and <M-R>,
+are used to produce things that are not hyperlinks - usually other
+kinds of scripts.
+" rest)))
+
+;; (find-wrap-intro)
+
+
+
+
+;;; _
+;;; ___ ___ (_)_ _ _ __ ___ _ __
+;;; / _ \/ _ \| | | | | '_ ` _ \| '_ \
+;;; | __/ __/| | |_| | | | | | | |_) |
+;;; \___|\___|/ |\__,_|_| |_| |_| .__/
+;;; |__/ |_|
+;;
+;; (find-elnode "Defining Commands")
+;; (find-enode "Arguments")
+;; (find-TH "emacs" "eejump")
+;; http://angg.twu.net/emacs.html#eejump
+;; file:///home/edrx/TH/L/emacs.html#eejump
+;; �find-eejump-intro� (to ".find-eejump-intro")
+
+(defun find-eejump-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-eejump-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-eejump-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-eejump-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.
-which contains a 3-line header with help links, that we will explain
-soon, and then a link to \"here\", i.e., to the buffer
-\"*(find-links-intro)*\". Note that the link
- (find-links-intro)
-can be \"refined\" to, for example,
+Note: this intro needs to be rewritten!
+Ideally it should _complement_ the material in:
+ (find-eev-quick-intro \"7.1. eejump\")
- (find-links-intro \"which contains a 3-line header\")
-using the tricks described in these sections:
- (find-eval-intro \"Refining hyperlinks\")
- (find-eval-intro \"Producing and refining hyperlinks\")
- (find-eval-intro \"Producing and refining hyperlinks\" \"`M-h M-2'\")
- (find-eval-intro \"Producing and refining hyperlinks\" \"`M-h2hy'\")
-but `find-here-links' by itself only produces \"unrefined\" links - so
-when we say that `find-here-links' produces links to \"here\" we mean
-just \"to the current buffer\", not \"to the a certain position in the
-current buffer\".
+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,
-`find-here-links' works for several kinds of \"here\"s - it works for
-intros like this one, for Info pages, for manpages, for files and
-directories, for descriptions of Emacs functions and variables, and
-for a few other cases. Try the sexps below:
+ 1) we want our list of files to be preserved between one Emacs
+ session and another,
- (find-here-links-test '(find-eval-intro))
- (find-here-links-test '(find-node \"(dir)Top\"))
- (find-here-links-test '(find-enode \"Lisp Eval\"))
- (find-here-links-test '(find-fline \"~/\"))
- (find-here-links-test '(find-eevfile \"eepitch.el\"))
- (find-here-links-test '(find-efunction 'ee-eval-last-sexp))
+ 2) we know that each \"visit a file\" command will correspond
+ to an elisp hyperlink.
- (find-here-links-test '(find-efunctiondescr 'ee-eval-last-sexp))
- (find-here-links-test '(find-evardescr 'ee-hyperlink-prefix))
- (find-here-links-test '(find-efacedescr 'eepitch-star-face))
+One quick solution would be to put the list of elisp hyperlinks
+in a file, and make the key `M-j' open that file. But then
+jumping to a file in that list becomes a two-step process: type
+`M-j', move the point to the right line, type `M-e'. This would
+be similar to what happens when we use one of the `find-e*'
+commands, for example `find-efunction':
- (find-here-links-test '(find-ecolors \"\\nred\"))
- (find-here-links-test '(find-efaces \"eepitch-star-face\"))
- (find-here-links-test '(find-customizegroup 'rcirc))
+ (find-efunction 'find-efunction)
+ (eek \"M-h M-f find-efunction\")
- (find-here-links-test '(find-man \"1 cat\"))
- [^ oops, this test doesn't work on multi-window settings...]
+Those intermediate steps - seeing the list, locating visually the
+right line, moving to it - are distracting, so we want to add new
+items to our wishlist:
-Each one of them tests a different case of `find-here-links',
-creating a window setup like this:
+ 3) it should be possible to jump straight to any of the files
+ in the list, and with very few keystrokes,
- ______________________________________
- | | |
- | | target of |
- | | sexp |
- | this |______________________|
- | intro | |
- | | result of running |
- | | find-here-links on |
- | | [target of sexp] |
- |_______________|______________________|
+ 4) the list should be stored in a format that lets us see
+ quickly which are the keystrokes for accessing each item - so
+ that we won't need to memorize anything,
-The cursor is kept at the left window (\"this intro\"), so you
-can compare the different cases using just <up>, <down>, and M-e.
+ 5) the list should be easy to modify,
+ 6) it should be possible to assign shorter key sequences to
+ files we visit more often,
+ 7) the source code must be very simple.
-5. `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
-\"e-script\". Then we start to navigate for information, and we find
-something interesting. We want to add a link pointing to that
-\"something interesting\" to our e-script notes - but for that we need
-to produce that sexp hyperlink, and ideally we would like to do that
-in a way that does not disturb much our attention. Consider this
-diagram [note: it DOES NOT imply that the Emacs frame is split into three
-windows - typically we will switch between buffers in a single window]:
+
+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,
+when invoked with `M-2 M-j' it opened another, and so on, and
+when it was invoked with an unrecognized prefix or with no prefix
+it jumped to its definition in my ~/.emacs. Its code was like
+this (NOTE: do not execute these defuns):
- ______________________________________
- | | |
- | | something |
- | ==> interesting |
- | e-script |_________||___________|
- | | \\/ |
- | | result of running |
- | <== find-here-links on |
- | | [sthing intrstng] |
- |_______________|______________________|
+ ;; eejump-simplified (`M-j'):
+ ;; M-1 M-j opens a certain file,
+ ;; M-2 M-j opens another file,
+ ;; when the argument is 11, 22, 33 or 44 do something special,
+ ;; like changing the font;
+ ;; with no argument or with an unrecognized argument jump to the
+ ;; definition of eejump in ~/.emacs; then we can see which numbers
+ ;; correspond to which actions (the source is the documentation!), and
+ ;; we can change the definition if needed - just run `M-e' at the
+ ;; right place to make the changes apply.
+ ;;
+ \(global-set-key (kbd \"M-j\") 'eejump-simplified)
+ \(defun eejump-simplified (arg) (interactive \"P\")
+ (cond ((eq arg 1) (find-file \"~/NOTES\"))
+ ((eq arg 2) (find-file \"~/otherfile.txt\"))
+ ;;
+ ((eq arg 11) (set-frame-font \"fixed\"))
+ ((eq arg 22) (set-frame-font \"terminus-16\"))
+ ((eq arg 33) (set-frame-font \"terminus-bold-16\"))
+ ((eq arg 44) (set-frame-font \"10x20\"))
+ (t (find-function 'eejump-simplified))))
-and this series of steps:
+except that my definition became huge with time as I added to it
+more entries for files (and other actions!) that I used often,
+and also entries that were used not so often...
+
+All the \"options\" - i.e., all the `(eq arg nnn)' lines - had to
+be together in a single very big defun, and there was no way to
+add new options temporarily...
+
+
+
+
+Families
+========
+Let's use a shorthand for key sequences: for example, `M-123j'
+instead of `M-1 M-2 M-3 M-j'.
+
+I tend to assign related numbers to related files. For example, I
+use the prefix \"5\" for things that are Emacs-related: `M-5j'
+visits my .emacs, `M-555j' visits the directory with all of eev's
+elisp files, and `M-51j', `M-52j', etc, visit specific eev source
+files that I happen to be working on. Also, I use the prefix
+\"7\" for things related to LaTeX. So, the \"5*\" family is
+composed of Emacs-related files, and the \"7*\" family of
+LaTex-related files.
+
+The definition of `eejump-simplified' given above does not
+satisfy these two (new!) wishlist items:
+
+ 8) it should be possible to jump to the definition of the
+ \"5*\" family by typing something like `M-5678j', where
+ \"5678\" is a non-assigned number that starts with the \"5*\"
+ prefix,
+
+ 9) it should be possible to convert a number/hyperlink pair
+ very easily into to the code that assigns that elisp hyperlink
+ as the desired behavior for that number - and it should be
+ possible to do that both permanently (think in changing the
+ definition of `eejump-simplified' in your .emacs) and
+ temporarily (i.e., for the current Emacs session only).
+
+
+
+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
+the 9 wishlist items above. It works in this way: if you type,
+say, `M-123j', then:
+
+ a) if `eejump-123' is defined, then execute it;
+ b) otherwise, if `eejump-12*' is defined, execute it;
+ c) otherwise, if `eejump-1*' is defined, execute it;
+ d) otherwise, if `eejump-*' is defined, execute it,
+
+and if `eejump-*' also is not defined, you get an error.
+
+Here is a block of \"defun\"s that defines (trivial) meanings for
+\"91\", \"92\", \"991\", and \"992\", plus targets for the \"9*\"
+family and for the \"99*\" family; it also has two tests in
+comments that will be very important for an explanation below.
+Let's refer as that, in this section and the next ones, as \"the
+block of six defuns (plus four tests)\".
+
+ (defun eejump-9* () (find-efunction 'eejump-9*))
+ (defun eejump-91 () (message \"M-91j\"))
+ (defun eejump-92 () (message \"M-92j\"))
+ (defun eejump-99* () (find-efunction 'eejump-99*))
+ (defun eejump-991 () (message \"M-991j\"))
+ (defun eejump-992 () (message \"M-992j\"))
+ ;; (find-function-noselect 'eejump-9*)
+ ;; (find-function-noselect 'eejump-99*)
+ ;; (find-efunction 'eejump-9*)
+ ;; (find-efunction 'eejump-99*)
+
+Try to evaluate each of the sexps above with `M-e', then try to
+run things like `M-92j' and `M-992j' - they should work - and
+then something like `M-99876j'; that will not work, you'll get an
+error like \"Don't know where `eejump-99*' is defined\"...
+
+
+
+eejump blocks
+=============
+Let's a call a sequence of defuns for eejumps with the same
+prefix, like this, starting with a `(defun eejump-<prefix>* ...)',
+
+ (defun eejump-99* () (find-efunction 'eejump-99*))
+ (defun eejump-991 () (message \"M-991j\"))
+ (defun eejump-992 () (message \"M-992j\"))
+
+an \"eejump block\".
+
+There are two sample eejump blocks in eejump.el, for the prefixes
+\"\" and \"5\", starting at:
+
+ (find-eev \"eejump.el\" \"eejump-*\")
+ (find-eev \"eejump.el\" \"eejump-5*\")
+
+You should probably copy them to your .emacs, and then start
+modifying them.
+
+
+
+
+Making an `eejump-nn*' work
+===========================
+If you execute a line like
+
+ (defun eejump-9* () (find-efunction 'eejump-9*))
+
+then Emacs will only record that `eejump-9*' has been defined in
+this buffer - and thus will be able to jump to its definition
+when you type something like `M-987j' - if two conditions are
+met:
+
+ a) the defun is executed with `M-x eval-region', `M-x
+ eval-buffer', or some variant of `load' or `require' (`M-e'
+ will not do!),
+
+ b) the buffer with the definition is associated to a file; see
+ these two pages of the Emacs manuals
+
+ (find-enode \"Buffers\" \"visiting\")
+ (find-elnode \"Buffer File Name\")
- 0. We start navigating from the e-script buffer, and when we
- 1. find something interesting [in another buffer], we
- 2. run `find-here-links' at the \"something interesting\" buffer,
- 3. identify among the sexps in the find-here-links buffer one that
- points to that \"something interesting\",
- 4. copy that sexp to the kill-ring,
- 5. go back to the e-script buffer,
- 6. insert that sexp into the e-script buffer,
- 7. execute that sexp to go back to the \"something interesting\",
- 8. continue navigating & doing stuff.
+ if that concept is not totally familiar to you.
-At (8) we are essentially back to (1), but we have added to our
-e-script buffer a link to \"something interesting\".
+So, as an experiment, copy the block with six defuns and four
+tests above to some buffer associated to a file, mark it, and
+execute it with `M-x eval-region'. Now the tests should work -
+and key sequences like `M-987j' should also work, and should jump
+to the right places. See also:
-Note that to add refining we need to add a step before (2) and
-another one after (3):
+ (find-elnode \"Where Defined\")
- 1.9. select a string to search for and copy it to the kill-ring,
- 3.1. refine that sexp using the \"string to search for\" (with M-h2hy)
-\[TO DO: explain the keys that I normally use to perform all
-this; explain why I am not the right person to optimize these
-steps - because I can type these key sequences without thinking,
-and step (3) sometimes gives several sexps for us to choose from]
+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:
+ 9
+ 91 (message \"M-91j\")
+ 92 (message \"M-92j\")
+ 99
+ 991 (message \"M-991j\")
+ 992 (message \"M-992j\")
+you will notice that you've just generated a block of defuns like
+the one in the previous section! `M-J' works like this: it tries
+to split the current line into \"words\" separated by whitespace,
+but producing a maximum of two \"words\" (the 2nd, 3rd, etc
+\"words\" as treated as a single \"word\"); if the second word is
+empty, then `M-J' produces a definition for an `eejump-nnn*'; if
+it is not empty, then `M-J' produces a definition for an
+`eejump-nnn', treating the second \"word\" as a sexp.
-6. 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?
+Note that `M-J' is quite dumb - it doesn't check if the first
+\"word\" is a number, nor if the second is a sexp. Use it with
+care! Try using `M-J' on the \"a b ...\" lines below - you will
+get useless definitons.
-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
+ a b c d
+ a b c
+ a b
+ a
- (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,
+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
+not evaluated in every Emacs session (and execute it, of course),
+then you'll be attributing just a \"temporary\" meaning to
+`M-91j', ..., `M-992j'.
+" rest)))
- (find-enode \"Command Index\" \"* find-file:\")
- (find-elnode \"Index\" \"* find-file:\")
+;; (find-eejump-intro)
-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\")
+;;; _
+;;; __ _ _ __ ___| |__ ___ _ __ ___
+;;; / _` | '_ \ / __| '_ \ / _ \| '__/ __|
+;;; | (_| | | | | (__| | | | (_) | | \__ \
+;;; \__,_|_| |_|\___|_| |_|\___/|_| |___/
+;;;
+;; �find-anchors-intro� (to ".find-anchors-intro")
+;; (find-intro-links "anchors")
-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.
+(defun find-anchors-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-anchors-intro)*"))
+ (apply 'find-estring-lv "\
+\(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)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
-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.
+Note: this intro needs to be rewritten!
+Ideally it should _complement_ the material in:
+ (find-eev-quick-intro \"8. Anchors\")
-7. 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
-the inspiration for all the `find-*-links' functions.
+Introduction: `ee-anchor-format' and `to'
+=========================================
+A hyperlink like
-If you run `M-x ee-hyperlink-prefix' you should get a buffer like
-this:
+ (to \"foo\")
- ___________________________________________________________
- |# (ee-hyperlink-prefix) |
- |# (setq ee-hyperlink-prefix \"# \") |
- | |
- |# (setq ee-hyperlink-prefix \"# \") |
- |# (setq ee-hyperlink-prefix \";; \") |
- |# (setq ee-hyperlink-prefix \"-- \") |
- |# (setq ee-hyperlink-prefix \"// \") |
- |# (setq ee-hyperlink-prefix \"% \") |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
- |___________________________________________________________|
+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:
-where the first line regenerates the buffer, the second line sets
-the variable `ee-hyperlink-prefix' to its current value, and each
-one of the lines after the first blank line sets
-`ee-hyperlink-prefix' to one of several fixed common values. If
-we change the value of `ee-hyperlink-prefix' with one of the
-`setq's and execute the first line again we see that all the
-prefixes, plus the argument \"# \" in the second line, change.
-Try this, with `M-2 M-e' on each line:
+ ee-anchor-format
+ (format ee-anchor-format \"foo\")
+ (ee-goto-position (format ee-anchor-format \"foo\"))
- (progn (setq ee-hyperlink-prefix \"# \") (ee-hyperlink-prefix))
- (progn (setq ee-hyperlink-prefix \"% \") (ee-hyperlink-prefix))
+We will call strings in `��'s _anchors_, and we will say
+that `(to \"foo\")' jumps \"to the anchor `foo'\".
+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.
-8. The first line regenerates the buffer
-========================================
-\[To do: explain this convention with examples; explain the
-conventions for the \"variants of the first line\"\]
+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-find-links-links)
- (find-find-links-links \"\\\\M-u\")
- (find-find-links-links \"\\\\M-u\" \"USERTEST\")
- (find-find-links-links \"\\\\M-u\" \"USERTEST\" \"a\")
- (find-find-links-links \"\\\\M-u\" \"USERTEST\" \"a b\")
- (find-find-links-links \"\\\\M-u\" \"USERTEST\" \"a b c\")
+ (find-eepitch-intro \"\\nRed stars\\n\")
+For historical reasons, the glyphs for `�' and `�' defined in
+ (find-eev \"eev-anchors.el\")
-9. 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,
-to the current Info page, to the current `find-*-intro', to an
-Emacs function or variable we are inspecting, to the current
-buffer, and so on. They don't try to be very smart -
+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�\".
-\[To do: write this\]
+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-efunctiondescr 'eev-mode)
- (find-efunctiondescr 'eev-mode \"M-h f\")
- (eek \"M-h M-i\")
- (find-enode \"Lisp Eval\")
- (progn (find-enode \"Lisp Eval\") (eek \"M-h M-i\"))
+Indexes
+=======
+In a situation like this,
- (eek \"M-h f ;; find-file-links\")
- (eek \"M-h M-b ;; find-ebuffer-links\")
+ �one� (to \"two\")
+ �two� (to \"one\")
- for example, `M-h M-i' generates links to
- the current \"intro\" buffer - like this one - _and_ to the
- current Info page (the \"i\" in `M-h M-i' has two meanings).
- Try:
+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_.
- (eek \"M-h M-i\")
+In a case like this,
- you should get something like this:
+ �.three� (to \"three\")
+ �three� (to \".three\")
- ___________________________________________________________
- |# (find-einfo-links \"links\") |
- | |
- |[No \"*info*\" buffer] |
- | |
- |# (find-links-intro) |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
- |___________________________________________________________|
+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:
+ (find-eev \"eev-intro.el\" \".find-eev-intro\")
-10. 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
-example is
- (find-eev-update-links)
+Creating index/section anchor pairs
+===================================
+Use `M-A' (`eewrap-anchor'). Note that this has been briefly
+mentioned here:
-which ends with stuff that you can copy to your .emacs file to
-make Emacs load eev by default. The end of the buffer generated
-by `find-eev-update-links' looks more or less like this:
+ (find-wrap-intro \"All wrapping functions\")
- ____________________________________________________________
- |# (ee-copy-rest 0 '(find-fline \"~/.emacs\")) |
- | |
- |;; Load eev2. |
- |;; See: (find-file \"~/eev/\") |
- |;; (find-file \"~/eev/eev-readme.el\") |
- |;; Generated by: (find-eev-update-links \"~/eev/\") |
- |;; |
- |(add-to-list 'load-path \"~/eev/\") |
- |(require 'eev2-all) ; (find-eev \"eev2-all.el\") |
- |(eev-mode 1) ; (find-eev \"eev-mode.el\") |
- | |
- | |
- |--:**- *Elisp hyperlinks* Bot L56 (Fundamental eev)---|
- |____________________________________________________________|
+It will convert a line with a syntax like
-The line with `ee-copy-rest' is a hack. Its first argument is a
-number, that we will call the \"skip\", and the second is
-a (quoted) sexp hyperlink, that we will call the \"code\". The
-rule that defines what is the \"rest of the buffer\" is this:
+ comment-prefix <anchor-name>
- Move to the beginning of the next line, then skip (i.e., move
- down) more SKIP lines. The rest of the buffer is everything
- from that point on.
+into:
-A sexp like `(ee-copy-rest ...)' does several things:
+ comment-prefix �.anchor-name� (to \"anchor-name\")
+ comment-prefix �anchor-name� (to \".anchor-name\")
- 1) it highlights the rest of the buffer temporarily (like as
- with `M-0 M-e'),
+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.
- 2) it copies the rest of the buffer to the kill ring (like as
- with `M-w'),
- 3) it runs CODE to open its target in a window at the right
- side (like as with `M-3 M-e')
-\[To do: add examples - including examples that let us create Lua
-scripts etc\]
+find-anchor
+===========
+\(find-eev \"eev-anchors.el\")
+\(find-eev \"eev-anchors.el\" \"find-anchor\")
+code-c-d and :anchor
+====================
+\(find-eev \"eev-code.el\" \"ee-code-c-d-:anchor\")
" rest)))
-;; (find-links-intro)
-
-;; (find-eevfile "eev-template.el" "defun find-efunction-links")
-
+;; (find-anchors-intro)
-;;; _ _ _ _
-;;; ___ ___ __| | ___ ___ __| | (_)_ __ | |_ _ __ ___
-;;; / __/ _ \ / _` |/ _ \_____ / __|____ / _` |_____| | '_ \| __| '__/ _ \
-;;; | (_| (_) | (_| | __/_____| (_|_____| (_| |_____| | | | | |_| | | (_) |
-;;; \___\___/ \__,_|\___| \___| \__,_| |_|_| |_|\__|_| \___/
-;;;
+;;; _ _
+;;; ___ ___ __| | ___ ___ __| |
+;;; / __/ _ \ / _` |/ _ \_____ / __|____ / _` |
+;;; | (_| (_) | (_| | __/_____| (_|_____| (_| |
+;;; \___\___/ \__,_|\___| \___| \__,_|
+;;;
;; �find-code-c-d-intro� (to ".find-code-c-d-intro")
(defun find-code-c-d-intro (&rest rest) (interactive)
@@ -3128,8 +3599,9 @@ Is is meant as both a tutorial and a sandbox.
-This intro has been mostly superseded by:
-(find-eev-quick-intro \"9.1. `code-c-d'\")
+Note: this intro needs to be rewritten!
+Ideally it should _complement_ the material in:
+ (find-eev-quick-intro \"9.1. `code-c-d'\")
@@ -3264,219 +3736,31 @@ See: (find-brxxx-intro)
Try: (find-code-pdf \"CODE\" \"FILE.pdf\")
(find-code-pdf-text \"CODE\" \"FILE.pdf\")
(find-code-audio \"CODE\" \"FILE.mp3\")
- (find-code-video \"CODE\" \"FILE.mp4\")
-" rest)))
-
-;; (find-TH "eev-article")
-;; (find-TH "eev-article" "shorter-hyperlinks")
-;; (find-code-c-d-intro)
-
-
-
-
-
-;;; _ _
-;;; _ __ ___ _ __ ___ (_)_ __ | |_ _ __ ___
-;;; | '_ \/ __| '_ \ / _ \_____| | '_ \| __| '__/ _ \
-;;; | |_) \__ \ | | | __/_____| | | | | |_| | | (_) |
-;;; | .__/|___/_| |_|\___| |_|_| |_|\__|_| \___/
-;;; |_|
-;;
-;; �find-psne-intro� (to ".find-psne-intro")
-;; (find-TH "eev-article" "local-copies")
-;; (find-angg ".emacs" "brep")
-;; (find-eev "eev-browse-url.el" "find-psne-links")
-;; (find-eev "eev-browse-url.el" "brep")
-
-(defun find-psne-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-psne-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-psne-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-psne-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.
-
-
-
-
-Local copies of files from the internet
-=======================================
-Emacs knows how to fetch files from the internet, but for most
-purposes it is better to use local copies. Suppose that the
-environment variable $S is set to ~/snarf/; then running this
-
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
- mkdir -p $S/http/www.gnu.org/software/emacs/
- cd $S/http/www.gnu.org/software/emacs/
- wget http://www.gnu.org/software/emacs/emacs-paper.html
- echo 'http://www.gnu.org/software/emacs/emacs-paper.html' >> ~/.psne.log
-
- # (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
- # (find-w3m \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
-
-creates a local copy of `emacs-paper.html' inside ~/snarf/http/
-and appends the URL to the file ~/.psne.log. The two lines in
-comments are hyperlinks to the local copy; The `find-fline' opens
-it as a file in the obvious way, and `find-w3m' opens it \"as
-HTML\", using a text-mode web browser called w3m that can be run
-either in standalone mode or inside Emacs; `find-w3m' uses w3m's
-Emacs interface, and it accepts extra arguments, which are
-treated as a pos-spec-list.
-
-
-
-The old way: psne
-=================
-A long time ago eev used to include a shell function called
-`psne' that ran all that with a single command. This:
-
- psne http://www.gnu.org/software/emacs/emacs-paper.html
-
-would run the `mkdir', the `cd', the `wget' and the `echo' above.
-
-If psne were just a shell script then it wouldn't be able to
-change the current directory for the calling shell, so it had to
-be defined as shell function instead of a script, and the user
-had to patch his ~/.bashrc (or ~/.zshrc, or whatever) to install
-the definition for psne and make it available. That was VERY
-clumsy.
-
-From now on we will use \"psne\" as a verb: to psne a URL means
-to download a local copy of it into the right place, change to
-its directory and save its name into the file \"~/.psne.log\".
-
-
-
-
-The new way: M-x brep
-=====================
-Try to run this:
-
- (find-psne-links \"http://www.gnu.org/software/emacs/emacs-paper.html\";)
-
-or, equivalently, put the point on the URL below and then run
-`M-x brep':
-
- http://www.gnu.org/software/emacs/emacs-paper.html
-
-You will get a temporary buffer for psne-ing the URL above. It
-will contain a `mkdir', a `cd', a `wget' and an `echo', plus an
-eepitch block and some elisp hyperlinks, and it can be executed
-with `F8's. Moral of the story: the \"new\" way to download a
-local copy of a url is to put the point on it, then run `M-x
-brep', then execute the resulting e-script. This does not require
-any patching of rcfiles, as the shell-function version of `psne'
-used to do.
-
-
-
-The environment variable $S
-===========================
-If when eev is loaded by Emacs the environment variable $S is
-unset, it will be set to a default value - namely, to the
-expansion of \"$HOME/snarf\". Processes started from Emacs, such
-as shells created with `eepitch-shell' or `find-sh', or external
-terminals created by sexps like
-
- (find-bgprocess \"xterm\")
- (find-bgprocess \"gnome-terminal\")
- (find-bgprocess \"eterm\")
-
-will then inherit that value. Try it:
-
- (getenv \"S\")
- (find-sh0 \"echo $S\")
-
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-echo $S
-
-Try also to create an external shell not from Emacs - for
-example, from your window manager's list of available
-applications, or from a text-mode login - and run \"echo $S\"
-there: you will notice that $S is unset.
-
-Old versions of eev used to require the user to run a script that
-would patch his rcfiles (i.e., ~/.bashrc, ~/.zshrc, etc) to set
-$S on startup. That turned out to be unreliable - it was better
-to teach people how to distinguish those processes that inherit
-$S from Emacs from those that don't, and let the experts patch
-their rcfiles by hand.
-
-
-
-`browse-url' and friends
-========================
-If you place the point on the URL below
-
- http://www.gnu.org/software/emacs/emacs-paper.html
-
-and run `M-x browse-url', Emacs will make an external browser
-visit the remote version of that URL. One (bad) way to visit the
-local copy of that URL is to modify the URL above by hand to
-adjust it to your value of $S, until you obtain something like
-this:
-
- file:///home/edrx/snarf/http/www.gnu.org/software/emacs/emacs-paper.html
-
-and then run `M-x browse-url' on it.
-
-One - rather primitive - way of visiting the local copy of that
-URL with find-file is to modify the URL by hand, replacing its
-\"http://\"; with n \"$S/http/\", and then visit that file. For
-example:
-
- http://www.gnu.org/software/emacs/emacs-paper.html
- (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
-
-If you put the point on the URL and run `M-x brfl' on it you will
-visit the local copy \"as a file\", with `find-file' /
-`find-fline'. Visiting URLs - or their local copies - is
-something that we do so frequently that we need ways to do that
-with few keystrokes, which is why `brfl' has a short - and
-cryptic - name. The conventions are:
-
- \"br\" is the common prefix for all the browse-url-like
- functions in eev,
- \"f\" means to use `find-fline' (or, equivalently, `find-file'),
- \"l\" is an optional suffix meaning to use the local copy.
-
-The details on how to create these \"brxxx functions\" are here:
-
- (find-brxxx-intro)
-
-" rest)))
-
-;; (find-enode "Command Index" "browse-url")
-;; (find-efunction 'browse-url)
-;; (find-elnode "System Environment")
-;; (find-enode "Environment")
-;; (find-eevfile \"eev.el\" \"$HOME/snarf\")
+ (find-code-video \"CODE\" \"FILE.mp4\")
+" rest)))
-;; (find-psne-intro)
+;; (find-TH "eev-article")
+;; (find-TH "eev-article" "shorter-hyperlinks")
+;; (find-code-c-d-intro)
-;;; _ _ _
-;;; | |__ _ ____ ____ ____ __ (_)_ __ | |_ _ __ ___
-;;; | '_ \| '__\ \/ /\ \/ /\ \/ /____| | '_ \| __| '__/ _ \
-;;; | |_) | | > < > < > <_____| | | | | |_| | | (_) |
-;;; |_.__/|_| /_/\_\/_/\_\/_/\_\ |_|_| |_|\__|_| \___/
-;;;
-;; �find-brxxx-intro� (to ".find-brxxx-intro")
-(defun find-brxxx-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-brxxx-intro)*"))
+;;; _ __ _ _ _
+;;; _ __ __| |/ _| | (_) | _____
+;;; | '_ \ / _` | |_ _____| | | |/ / _ \
+;;; | |_) | (_| | _|_____| | | < __/
+;;; | .__/ \__,_|_| |_|_|_|\_\___|
+;;; |_|
+;;
+;; �find-pdf-like-intro� (to ".find-pdf-like-intro")
+
+(defun find-pdf-like-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-pdf-like-intro)*"))
(apply 'find-estring "\
-\(Re)generate: (find-brxxx-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-brxxx-intro\")
+\(Re)generate: (find-pdf-like-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-pdf-like-intro\")
More intros: (find-eev-quick-intro)
(find-eval-intro)
(find-eepitch-intro)
@@ -3485,838 +3769,753 @@ Is is meant as both a tutorial and a sandbox.
-1. Introduction
-===============
-We saw in
-
- (find-psne-intro)
- (find-psne-intro \"M-x brep\")
- (find-psne-intro \"M-x brfl\")
- (find-psne-intro \"`browse-url' and friends\")
-
-that we can use `M-x brep' to download local copies of files from
-the internet, and that `M-x brfl' on a URL runs `find-fline' on
-the local copy of that URL. `brep' and `brfl' are
-\"`browse-url'-like functions\" defined by eev; we will refer to
-them, and to other such functions, as \"brxxx-functions\". Every
-brxxx-function is an interactive interface to some \"base
-function\"; for `brep' and `brfl' we have:
-
- brxxx-function base function
- -------------- -------------
- brep find-psne-links
- brfl find-fline
-What we will see here is how `code-brfile' and `code-brurl' -
-which are somewhat similar to `code-c-d' - can be used to define
-brxxx-functions from base functions.
+Note: this intro needs to be rewritten!
+Ideally it should _complement_ the material in:
+ (find-eev-quick-intro \"9.3. Hyperlinks to PDF files\")
-2. A first example
+PDF-like documents
==================
-Let's define two trivial base functions, one that expects a URL,
-and another one that expects a file name:
-
- (defun foo-url (url) (format \"Got URL: %s\" url))
- (defun foo-file (filename) (format \"Got filename: %s\" filename))
-
-Note that they don't do much - they just return explanatory
-strings.
-
-These two calls,
-
- (code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
- (code-brfile 'foo-file :local 'brshowfl)
-
-define three brxxx-functions: `brshowu' and `brshowul' for the
-base function `foo-url', and `brshowfl' for the base function
-`foo-file'. You can inspect the definitions by running these
-sexps,
-
- (find-code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
- (find-code-brfile 'foo-file :local 'brshowfl)
-
-and you can test what `foo-url', `foo-file', `brshowu',
-`brshowul', and `brshowfl' do by running the sexps below.
-
- (foo-url \"http://a/b\";)
- => \"Got URL: http://a/b\";
-
- (foo-file \"/c/d/e/f\")
- => \"Got filename: /c/d/e/f\"
+Let's introduce a bit of (improvised!) terminology: we will say
+that a document is \"PDF-like\" when it is in a format like PDF,
+PostScript, DVI or DJVU - i.e., divided into pages. Emacs has a
+standard mode for viewing PDF-like documents,
- (brshowu \"http://a/b\";)
- => `(foo-url \"http://a/b\";) -> \"Got URL: http://a/b\";'
+ (find-enode \"Document View\")
- (brshowul \"http://a/b\";)
- => `(foo-url \"file:///home/edrx/snarf/http/a/b\") ->
- \"Got URL: file:///home/edrx/snarf/http/a/b\"'
+but we will see a more eev-like way of pointing to pages of
+PDF-like documents.
- (brshowfl \"http://a/b\";)
- => `(foo-file \"/home/edrx/snarf/http/a/b\") ->
- \"Got filename: /home/edrx/snarf/http/a/b\"'
-Now let's go to what matters. Put the point on the URL below, and
-run `M-x brshowu', `M-x brshowul' and `M-x brshowfl':
- http://a/b
-you will see that `brshowu', `brshowul', and `brshowfl' can be
-called interactively, and when they are called interactively they
-use as their argument either the URL around point, or something
-obtained from it - the local file name or a local URL associated
-to that URL.
+Two test documents
+==================
+The following script creates two PDF-like documents - a DVI and a
+PDF - that we will use in the examples below.
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+cd /tmp/
+cat > /tmp/foo.tex <<'%%%'
+\\documentclass[12pt,oneside]{book}
+\\begin{document}
+\\Huge
+\\frontmatter
+a \\newpage
+b \\newpage
+c \\newpage
+\\mainmatter
+\\chapter{One}
+\\newpage foo
+\\chapter{Two}
+\\end{document}
+%%%
+ latex foo.tex
+pdflatex foo.tex
+In these two documents the page _names_ do not correspond to the
+page _numbers_; the pages are named \"i\", \"ii\", \"iii\",
+\"1\", \"2\", \"3\", but their numbers are 1, 2, 3, 4, 5, 6.
+In a table:
+ number name contents
+ ----------------------
+ 1 i a
+ 2 ii b
+ 3 iii c
+ 4 1 Chapter 1 - One
+ 5 2 foo
+ 6 3 Chapter 3 - Two
-3. The conversions
-==================
-One underlying idea behind all this is that we have two
-conversion functions, one from URLs to file names, and another
-from (absolute) file names to URLs starting with \"file:///\".
-They work like this:
- http://a/b -> $S/http/a/b -> file:///home/edrx/snarf/http/a/b
- /tmp/c -> file:///tmp/c
-try:
- (ee-url-to-fname \"http://a/b\";)
- (ee-fname-to-url \"/tmp/c\")
- (ee-url-to-local-url \"http://a/b\";)
+Using external viewers
+======================
+The following sexps can be used to open the documents
+\"/tmp/foo.dvi\" and \"/tmp/foo.pdf\" on the first page of
+Chapter 1 - i.e., the page whose number is 4, and whose \"name\"
+is 1 - using two of my favorite viewers, xdvi and xpdf, and a
+low-level function, `find-bgprocess':
-Now execute the sexps below (with `M-2 M-e') to examine the code
-that calls to `code-brurl' and `code-brfile' generate and
-execute:
+ (find-bgprocess '(\"xdvi\" \"+4\" \"/tmp/foo.dvi\"))
+ (find-bgprocess '(\"xpdf\" \"/tmp/foo.pdf\" \"4\"))
- (find-code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
- (find-code-brfile 'foo-file :local 'brshowfl)
+Alternatively, we can invoke these viewers like this,
+ (find-xdvi-page \"/tmp/foo.dvi\" 4)
+ (find-xpdf-page \"/tmp/foo.pdf\" 4)
+or, as they ignore extra arguments, like this,
+ (find-xdvi-page \"/tmp/foo.dvi\" (+ 3 1) \"Chapter 1\")
+ (find-xpdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+where the `(+ 3 1)' and the \"Chapter 1\" are just to make these
+links more readable by humans. The `3' is what we will call the
+\"offset\" of the document: a quantity that can be added to page
+\"names\" (outside the \"front matter\" of the document) to
+convert them to page \"numbers\".
+Let's introduce more terminology. Programs like xdvi and xpdf are
+\"external viewers for PDF-like documents\", but that's too long,
+so let's shorten this to \"external PDF-like viewers\", or
+\"external viewers\", or just \"viewers\"; `find-xdvi-page',
+`find-xpdf-page' and similar functions are \"medium-level viewing
+words\".
-4. Naming conventions for brxxx-functions
-=========================================
-By convention, each name for a brxxx-function is composed of a
-prefix, a stem, and a suffix. The prefix is always \"br\", the
-stem is a mnemonic for the base function, and the suffix is
-either \"\", \"l\", or \"d\", meaning:
- \"\" - use the URL without changes
- \"l\" - use the local copy
- \"d\" - dired variation (see below)
-Here are the stems for some of the brxxx-functions defined by
-eev:
- Base function receives stem
- ------------- -------- ----
- find-psne-links URL \"ep\"
- browse-url-firefox URL \"m\"
- find-googlechrome URL \"g\"
- find-w3m URL \"w\"
- find-fline file name \"f\"
- find-audio file name \"audio\"
- find-video file name \"video\"
- find-xpdf-page file name \"xpdf\"
- find-evince-page file name \"evince\"
- find-xdvi-page file name \"xdvi\"
- find-djvu-page file name \"djvu\"
- find-pdf-text file name \"pdftext\"
- find-djvu-text file name \"djvutext\"
+The high-level way
+==================
+File names of PDF-like documents are often very long - especially
+for documents that we have \"psne\"-ed from the web. To avoid
+having to keep copies of these file names everywhere we can use
+`code-c-d'-like words - like these:
-In our example with `foo-url' and `foo-file' we had:
+ (code-xdvi \"fd\" \"/tmp/foo.dvi\")
+ (code-xpdf \"fp\" \"/tmp/foo.pdf\")
+ (find-fdpage (+ 3 1) \"Chapter 1\")
+ (find-fppage (+ 3 1) \"Chapter 1\")
- Base function receives stem
- ------------- -------- ----
- foo-url URL showu
- foo-file file name showf
+Each medium-level viewing word has an associated code-c-d-like
+word - that creates \"high-level viewing words\". In the example
+above, we used `code-xdvi' to create the high-level viewing word
+`find-fdpage', that invokes `find-xdvi-page', and `code-xpdf' to
+create the high-level viewing word `find-fppage', which invokes
+`find-xpdf-page',
+Note that the \"fd\" in `find-fdpage' stands for not only the
+filename - \"/tmp/foo.dvi\" - but also for the medium-level word
+to be used - `find-xdvi-page'; same for \"fp\".
-5. Calling `code-brurl' and `code-brfile'
-=========================================
- (code-brurl '<U-function>
- :remote 'br<stem> :local 'br<stem>l :dired 'br<stem>d)
- \\---------------/ \\---------------/
\\----------------/
- optional optional optional
+Default external viewers
+========================
+We saw that for each of the supported formats of PDF-like
+documents - DVI, PostScript, PDF, DJVU - there are medium-level
+and high-level viewing words that use specific programs; for
+example, for \"xpdf\" we have `find-xpdf-page' and `code-xpdf',
+and for \"evince\" we have `find-evince-page' and `code-evince'.
+But for each of the formats we also have words that use the
+current default viewer for that format:
- (code-brfile '<F-function> :local 'br<stem>l :dired 'br<stem>d)
- \\---------------/ \\----------------/
- optional optional
+ Format Medium-level High-level
+ ----------------------------------------
+ DVI find-dvi-page code-dvi
+ PostScript find-ps-page code-ps
+ PDF find-pdf-page code-pdf
+ DJVU find-djvu-page code-djvu
-This, like many other parts of eev, is a hack with a very concise
-calling syntax - so we will see an example first, and then
-dissect it to understand precisely how it works. If you are
-curious about the inspirations behind it, here they are:
+The four `find-<formatname>-page' words above are aliases to
+`find-<viewername>-page' names, and to change a default viewer
+you should use a `defalias' on the `find-', like these:
- (find-code-c-d-intro)
- (find-code-c-d-intro \"find-code-c-d\")
- (find-code-c-d-intro \"Extra arguments\")
- (find-enode \"Browse-URL\")
+ (defalias 'find-pdf-page 'find-evince-page)
+ (defalias 'find-pdf-page 'find-xdpf-page)
+After running a `defalias' like the above all the high-level
+viewing words defined using `code-pdf' will automatically switch
+to the new default viewer (because words defined with `code-pdf'
+call `find-pdf-page').
-6. The dired variation
-======================
-In dired mode each line corresponds to a file
+PDF-like documents as text
+==========================
+Some PDF-like documents can be converted to text - usually uglily
+and imprecisely, but the result is often useful anyway - by
+external programs like \"pdftotext\" and \"djvutxt\". The
+medium-level sexps below invoke these programs on the given
+filenames and displays their output in an Emacs buffer:
-" rest)))
+ (find-pdftotext-text \"/tmp/foo.pdf\")
+ (find-djvutxt-text \"/tmp/foo.djvu\")
-;; (find-brxxx-intro)
+We can also use the correspondent generic medium-level words,
+that are aliases to the default converters:
+ (find-pdf-text \"/tmp/foo.pdf\")
+ (find-djvu-text \"/tmp/foo.djvu\")
+As the output of these converters is also divided into pages -
+with formfeeds as separators - it is easy to jump to specific
+pages in the output, and if the first argument after the file
+name is a number it is interpreted as a page number; string
+arguments coming after that are interpreted as strings to be
+search (forward) for. So these links make sense:
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
-;;; _
-;;; ___ ___ (_)_ _ _ __ ___ _ __
-;;; / _ \/ _ \| | | | | '_ ` _ \| '_ \
-;;; | __/ __/| | |_| | | | | | | |_) |
-;;; \___|\___|/ |\__,_|_| |_| |_| .__/
-;;; |__/ |_|
-;;
-;; (find-elnode "Defining Commands")
-;; (find-enode "Arguments")
-;; (find-TH "emacs" "eejump")
-;; http://angg.twu.net/emacs.html#eejump
-;; file:///home/edrx/TH/L/emacs.html#eejump
-;; �find-eejump-intro� (to ".find-eejump-intro")
+and note that the following pair of links make sense too - the
+first one calls an external viewer, the second one opens the
+conversion to text:
-(defun find-eejump-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-eejump-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-eejump-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-eejump-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.
+ (find-pdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+Note that they both point to the same page... The argument
+\"Chapter 1\" is ignored in the first link, but when a pair of
+links like that appear on consecutive lines it is clear for human
+readers that they are both links to the same place, only rendered
+in different ways. Note that the passage from this:
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 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,
+to this:
- 1) we want our list of files to be preserved between one Emacs
- session and another,
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
- 2) we know that each \"visit a file\" command will correspond
- to an elisp hyperlink.
+is a special case of \"refining hyperlinks\", an idea that we saw
+in:
-One quick solution would be to put the list of elisp hyperlinks
-in a file, and make the key `M-j' open that file. But then
-jumping to a file in that list becomes a two-step process: type
-`M-j', move the point to the right line, type `M-e'. This would
-be similar to what happens when we use one of the `find-e*'
-commands, for example `find-efunction':
+ (find-eval-intro \"Refining hyperlinks\")
- (find-efunction 'find-efunction)
- (eek \"M-h M-f find-efunction\")
-Those intermediate steps - seeing the list, locating visually the
-right line, moving to it - are distracting, so we want to add new
-items to our wishlist:
- 3) it should be possible to jump straight to any of the files
- in the list, and with very few keystrokes,
- 4) the list should be stored in a format that lets us see
- quickly which are the keystrokes for accessing each item - so
- that we won't need to memorize anything,
+High-level hyperlinks to pdf-like documents
+===========================================
+By executing
- 5) the list should be easy to modify,
+ (code-pdf \"fp\" \"/tmp/foo.pdf\")
+ (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
- 6) it should be possible to assign shorter key sequences to
- files we visit more often,
+we can use shorter hyperlinks, like
- 7) the source code must be very simple.
+ (find-fppage (+ 3 1) \"Chapter 1\")
+ (find-fptext (+ 3 1) \"Chapter 1\")
+instead of the longer forms with `find-pdf-page' and
+`find-pdf-text'. This works exactly like `code-c-d', as explained
+here:
-
-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,
-when invoked with `M-2 M-j' it opened another, and so on, and
-when it was invoked with an unrecognized prefix or with no prefix
-it jumped to its definition in my ~/.emacs. Its code was like
-this (NOTE: do not execute these defuns):
+ (find-code-c-d-intro)
- ;; eejump-simplified (`M-j'):
- ;; M-1 M-j opens a certain file,
- ;; M-2 M-j opens another file,
- ;; when the argument is 11, 22, 33 or 44 do something special,
- ;; like changing the font;
- ;; with no argument or with an unrecognized argument jump to the
- ;; definition of eejump in ~/.emacs; then we can see which numbers
- ;; correspond to which actions (the source is the documentation!), and
- ;; we can change the definition if needed - just run `M-e' at the
- ;; right place to make the changes apply.
- ;;
- \(global-set-key (kbd \"M-j\") 'eejump-simplified)
- \(defun eejump-simplified (arg) (interactive \"P\")
- (cond ((eq arg 1) (find-file \"~/NOTES\"))
- ((eq arg 2) (find-file \"~/otherfile.txt\"))
- ;;
- ((eq arg 11) (set-frame-font \"fixed\"))
- ((eq arg 22) (set-frame-font \"terminus-16\"))
- ((eq arg 33) (set-frame-font \"terminus-bold-16\"))
- ((eq arg 44) (set-frame-font \"10x20\"))
- (t (find-function 'eejump-simplified))))
+Try these sexps to see the code that the `code-pdf' and the
+`code-pdf-text' above execute:
-except that my definition became huge with time as I added to it
-more entries for files (and other actions!) that I used often,
-and also entries that were used not so often...
+ (find-code-pdf \"fp\" \"/tmp/foo.pdf\")
+ (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
-All the \"options\" - i.e., all the `(eq arg nnn)' lines - had to
-be together in a single very big defun, and there was no way to
-add new options temporarily...
+There is a wrapping comand for producing these
+`code-pdf'/`code-pdf-text' pairs quickly - `M-P'. Try it here:
+ fp /tmp/foo.pdf
-Families
-========
-Let's use a shorthand for key sequences: for example, `M-123j'
-instead of `M-1 M-2 M-3 M-j'.
-I tend to assign related numbers to related files. For example, I
-use the prefix \"5\" for things that are Emacs-related: `M-5j'
-visits my .emacs, `M-555j' visits the directory with all of eev's
-elisp files, and `M-51j', `M-52j', etc, visit specific eev source
-files that I happen to be working on. Also, I use the prefix
-\"7\" for things related to LaTeX. So, the \"5*\" family is
-composed of Emacs-related files, and the \"7*\" family of
-LaTex-related files.
+Producing and refining hyperlinks to pages
+==========================================
+We also have something like this
-The definition of `eejump-simplified' given above does not
-satisfy these two (new!) wishlist items:
+ (find-eval-intro \"Producing and refining hyperlinks\")
- 8) it should be possible to jump to the definition of the
- \"5*\" family by typing something like `M-5678j', where
- \"5678\" is a non-assigned number that starts with the \"5*\"
- prefix,
+for pdf-like documents, that will let us produce hyperlinks to
+the current page of the current pdf-like document very quickly,
+but it depends on several hacks.
- 9) it should be possible to convert a number/hyperlink pair
- very easily into to the code that assigns that elisp hyperlink
- as the desired behavior for that number - and it should be
- possible to do that both permanently (think in changing the
- definition of `eejump-simplified' in your .emacs) and
- temporarily (i.e., for the current Emacs session only).
+Note that the functions `code-pdf', `code-pdf-text',
+`find-xxxpage', `find-xxxtext', set the global variables
+`ee-page-c', `ee-page-fname', and `ee-page-offset'. You can
+inspect their definitions with:
+ (find-code-pdf \"fp\" \"/tmp/foo.pdf\")
+ (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+Here's how these variables are used. Try this:
-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
-the 9 wishlist items above. It works in this way: if you type,
-say, `M-123j', then:
+ (code-pdf \"fp\" \"/tmp/foo.pdf\")
+ (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+ (kill-new \"Two\")
+ (eek \"M-h M-p\")
- a) if `eejump-123' is defined, then execute it;
- b) otherwise, if `eejump-12*' is defined, execute it;
- c) otherwise, if `eejump-1*' is defined, execute it;
- d) otherwise, if `eejump-*' is defined, execute it,
+You should get a page with several hyperlinks to the \"current
+page\" of the current pdf-like document, including some like
+these:
-and if `eejump-*' also is not defined, you get an error.
+ (find-fppage 1)
+ (find-fptext 1)
+ (find-fppage (+ 3 -2))
+ (find-fptext (+ 3 -2))
-Here is a block of \"defun\"s that defines (trivial) meanings for
-\"91\", \"92\", \"991\", and \"992\", plus targets for the \"9*\"
-family and for the \"99*\" family; it also has two tests in
-comments that will be very important for an explanation below.
-Let's refer as that, in this section and the next ones, as \"the
-block of six defuns (plus four tests)\".
+ (find-fppage 1 \"Two\")
+ (find-fptext 1 \"Two\")
+ (find-fppage (+ 3 -2) \"Two\")
+ (find-fptext (+ 3 -2) \"Two\")
- (defun eejump-9* () (find-efunction 'eejump-9*))
- (defun eejump-91 () (message \"M-91j\"))
- (defun eejump-92 () (message \"M-92j\"))
- (defun eejump-99* () (find-efunction 'eejump-99*))
- (defun eejump-991 () (message \"M-991j\"))
- (defun eejump-992 () (message \"M-992j\"))
- ;; (find-function-noselect 'eejump-9*)
- ;; (find-function-noselect 'eejump-99*)
- ;; (find-efunction 'eejump-9*)
- ;; (find-efunction 'eejump-99*)
+Where did the \"fp\", the \"1\", the \"3\", the \"-2\" and the
+\"Two\" above come from?
+
+The page number, which in the links above is sometimes \"1\",
+sometimes \"(+ 3 -2)\", is obtained by counting the number of
+formfeeds before point; this makes sense only when we are
+visiting the buffer generated by \"(find-fptext ...)\". The
+\"fp\" is taken from the variable `ee-page-c', which was set by
+`(code-pdf-text \"fp\" ...)' or by `(find-fptext ...)'; same for \"3\",
+which is taken from the variable `ee-page-offset'. Finally, the \"Two\"
+is the last kill, from the top of the kill-ring; we usually set it by
+selecting a region of text from the `(find-fptext ...)' buffer and
+typing `M-w'.
-Try to evaluate each of the sexps above with `M-e', then try to
-run things like `M-92j' and `M-992j' - they should work - and
-then something like `M-99876j'; that will not work, you'll get an
-error like \"Don't know where `eejump-99*' is defined\"...
+An alternative way to produce hyperlinks to pages, which, as the hack
+above, also uses `ee-page-c' and `ee-page-offset', is to prepare a
+series of lines with a page number followed by a text that will play a
+similar role to the \"last kill\", and then type `M-Q' on each line. Try
+this below, by first executing the `code-pdf-text' then typing four
+`M-Q's.
+ (code-pdf \"debt\" \"~/books/graeber__debt.pdf\")
+ (code-pdf-text \"debt\" \"~/books/graeber__debt.pdf\" 8)
+ 1 1 On The Experience of Moral Confusion
+ 21 2 The Myth of Barter
+ 43 3 Primordial Debts
+ 73 4 Cruelty and Redemption
-eejump blocks
-=============
-Let's a call a sequence of defuns for eejumps with the same
-prefix, like this, starting with a `(defun eejump-<prefix>* ...)',
+It is usually not hard to produce such page-number-plus-text
+lines for `M-Q' from the table of contents of a book. The ones
+above were extracted from
- (defun eejump-99* () (find-efunction 'eejump-99*))
- (defun eejump-991 () (message \"M-991j\"))
- (defun eejump-992 () (message \"M-992j\"))
+ (find-debttext 7 \"Contents\")
-an \"eejump block\".
+with a bit of fiddling by hand and keyboard macros. Keyboard
+macros are VERY useful; if you don't use them yet, see:
-There are two sample eejump blocks in eejump.el, for the prefixes
-\"\" and \"5\", starting at:
+ (find-enode \"Keyboard Macros\")
+" rest)))
- (find-eev \"eejump.el\" \"eejump-*\")
- (find-eev \"eejump.el\" \"eejump-5*\")
+;; (find-pdf-like-intro)
-You should probably copy them to your .emacs, and then start
-modifying them.
+;;; _
+;;; | |__ _ ____ ____ ____ __
+;;; | '_ \| '__\ \/ /\ \/ /\ \/ /
+;;; | |_) | | > < > < > <
+;;; |_.__/|_| /_/\_\/_/\_\/_/\_\
+;;;
+;; �find-brxxx-intro� (to ".find-brxxx-intro")
-Making an `eejump-nn*' work
-===========================
-If you execute a line like
+(defun find-brxxx-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-brxxx-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-brxxx-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-brxxx-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.
- (defun eejump-9* () (find-efunction 'eejump-9*))
-then Emacs will only record that `eejump-9*' has been defined in
-this buffer - and thus will be able to jump to its definition
-when you type something like `M-987j' - if two conditions are
-met:
- a) the defun is executed with `M-x eval-region', `M-x
- eval-buffer', or some variant of `load' or `require' (`M-e'
- will not do!),
+Note: this intro needs to be rewritten!
+It expands an idea that was mentioned briefly at:
+ (find-eev-quick-intro \"3.1. Non-elisp hyperlinks\")
- b) the buffer with the definition is associated to a file; see
- these two pages of the Emacs manuals
- (find-enode \"Buffers\" \"visiting\")
- (find-elnode \"Buffer File Name\")
- if that concept is not totally familiar to you.
+1. Introduction
+===============
+We saw in
-So, as an experiment, copy the block with six defuns and four
-tests above to some buffer associated to a file, mark it, and
-execute it with `M-x eval-region'. Now the tests should work -
-and key sequences like `M-987j' should also work, and should jump
-to the right places. See also:
+ (find-psne-intro)
+ (find-psne-intro \"M-x brep\")
+ (find-psne-intro \"M-x brfl\")
+ (find-psne-intro \"`browse-url' and friends\")
- (find-elnode \"Where Defined\")
+that we can use `M-x brep' to download local copies of files from
+the internet, and that `M-x brfl' on a URL runs `find-fline' on
+the local copy of that URL. `brep' and `brfl' are
+\"`browse-url'-like functions\" defined by eev; we will refer to
+them, and to other such functions, as \"brxxx-functions\". Every
+brxxx-function is an interactive interface to some \"base
+function\"; for `brep' and `brfl' we have:
+ brxxx-function base function
+ -------------- -------------
+ brep find-psne-links
+ brfl find-fline
+What we will see here is how `code-brfile' and `code-brurl' -
+which are somewhat similar to `code-c-d' - can be used to define
+brxxx-functions from base functions.
-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:
- 9
- 91 (message \"M-91j\")
- 92 (message \"M-92j\")
- 99
- 991 (message \"M-991j\")
- 992 (message \"M-992j\")
-you will notice that you've just generated a block of defuns like
-the one in the previous section! `M-J' works like this: it tries
-to split the current line into \"words\" separated by whitespace,
-but producing a maximum of two \"words\" (the 2nd, 3rd, etc
-\"words\" as treated as a single \"word\"); if the second word is
-empty, then `M-J' produces a definition for an `eejump-nnn*'; if
-it is not empty, then `M-J' produces a definition for an
-`eejump-nnn', treating the second \"word\" as a sexp.
-Note that `M-J' is quite dumb - it doesn't check if the first
-\"word\" is a number, nor if the second is a sexp. Use it with
-care! Try using `M-J' on the \"a b ...\" lines below - you will
-get useless definitons.
+2. A first example
+==================
+Let's define two trivial base functions, one that expects a URL,
+and another one that expects a file name:
- a b c d
- a b c
- a b
- a
+ (defun foo-url (url) (format \"Got URL: %s\" url))
+ (defun foo-file (filename) (format \"Got filename: %s\" filename))
+Note that they don't do much - they just return explanatory
+strings.
+These two calls,
+ (code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
+ (code-brfile 'foo-file :local 'brshowfl)
-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
-not evaluated in every Emacs session (and execute it, of course),
-then you'll be attributing just a \"temporary\" meaning to
-`M-91j', ..., `M-992j'.
+define three brxxx-functions: `brshowu' and `brshowul' for the
+base function `foo-url', and `brshowfl' for the base function
+`foo-file'. You can inspect the definitions by running these
+sexps,
+ (find-code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
+ (find-code-brfile 'foo-file :local 'brshowfl)
+and you can test what `foo-url', `foo-file', `brshowu',
+`brshowul', and `brshowfl' do by running the sexps below.
+ (foo-url \"http://a/b\";)
+ => \"Got URL: http://a/b\";
-# Local Variables:
-# coding: raw-text-unix
-# ee-anchor-format: \"%s\"
-# End:
-" rest)))
+ (foo-file \"/c/d/e/f\")
+ => \"Got filename: /c/d/e/f\"
-;; (find-eejump-intro)
+ (brshowu \"http://a/b\";)
+ => `(foo-url \"http://a/b\";) -> \"Got URL: http://a/b\";'
+ (brshowul \"http://a/b\";)
+ => `(foo-url \"file:///home/edrx/snarf/http/a/b\") ->
+ \"Got URL: file:///home/edrx/snarf/http/a/b\"'
+ (brshowfl \"http://a/b\";)
+ => `(foo-file \"/home/edrx/snarf/http/a/b\") ->
+ \"Got filename: /home/edrx/snarf/http/a/b\"'
+Now let's go to what matters. Put the point on the URL below, and
+run `M-x brshowu', `M-x brshowul' and `M-x brshowfl':
-;;; _ __ _ _ _
-;;; _ __ __| |/ _| | (_) | _____
-;;; | '_ \ / _` | |_ _____| | | |/ / _ \
-;;; | |_) | (_| | _|_____| | | < __/
-;;; | .__/ \__,_|_| |_|_|_|\_\___|
-;;; |_|
-;;
-;; �find-pdf-like-intro� (to ".find-pdf-like-intro")
+ http://a/b
-(defun find-pdf-like-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-pdf-like-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-pdf-like-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-pdf-like-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.
+you will see that `brshowu', `brshowul', and `brshowfl' can be
+called interactively, and when they are called interactively they
+use as their argument either the URL around point, or something
+obtained from it - the local file name or a local URL associated
+to that URL.
-PDF-like documents
+3. The conversions
==================
-Let's introduce a bit of (improvised!) terminology: we will say
-that a document is \"PDF-like\" when it is in a format like PDF,
-PostScript, DVI or DJVU - i.e., divided into pages. Emacs has a
-standard mode for viewing PDF-like documents,
+One underlying idea behind all this is that we have two
+conversion functions, one from URLs to file names, and another
+from (absolute) file names to URLs starting with \"file:///\".
+They work like this:
- (find-enode \"Document View\")
+ http://a/b -> $S/http/a/b -> file:///home/edrx/snarf/http/a/b
+ /tmp/c -> file:///tmp/c
-but we will see a more eev-like way of pointing to pages of
-PDF-like documents.
+try:
+ (ee-url-to-fname \"http://a/b\";)
+ (ee-fname-to-url \"/tmp/c\")
+ (ee-url-to-local-url \"http://a/b\";)
+Now execute the sexps below (with `M-2 M-e') to examine the code
+that calls to `code-brurl' and `code-brfile' generate and
+execute:
+
+ (find-code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
+ (find-code-brfile 'foo-file :local 'brshowfl)
-Two test documents
-==================
-The following script creates two PDF-like documents - a DVI and a
-PDF - that we will use in the examples below.
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-cd /tmp/
-cat > /tmp/foo.tex <<'%%%'
-\\documentclass[12pt,oneside]{book}
-\\begin{document}
-\\Huge
-\\frontmatter
-a \\newpage
-b \\newpage
-c \\newpage
-\\mainmatter
-\\chapter{One}
-\\newpage foo
-\\chapter{Two}
-\\end{document}
-%%%
- latex foo.tex
-pdflatex foo.tex
-In these two documents the page _names_ do not correspond to the
-page _numbers_; the pages are named \"i\", \"ii\", \"iii\",
-\"1\", \"2\", \"3\", but their numbers are 1, 2, 3, 4, 5, 6.
-In a table:
- number name contents
- ----------------------
- 1 i a
- 2 ii b
- 3 iii c
- 4 1 Chapter 1 - One
- 5 2 foo
- 6 3 Chapter 3 - Two
+4. Naming conventions for brxxx-functions
+=========================================
+By convention, each name for a brxxx-function is composed of a
+prefix, a stem, and a suffix. The prefix is always \"br\", the
+stem is a mnemonic for the base function, and the suffix is
+either \"\", \"l\", or \"d\", meaning:
+ \"\" - use the URL without changes
+ \"l\" - use the local copy
+ \"d\" - dired variation (see below)
+Here are the stems for some of the brxxx-functions defined by
+eev:
-Using external viewers
-======================
-The following sexps can be used to open the documents
-\"/tmp/foo.dvi\" and \"/tmp/foo.pdf\" on the first page of
-Chapter 1 - i.e., the page whose number is 4, and whose \"name\"
-is 1 - using two of my favorite viewers, xdvi and xpdf, and a
-low-level function, `find-bgprocess':
+ Base function receives stem
+ ------------- -------- ----
+ find-psne-links URL \"ep\"
+ browse-url-firefox URL \"m\"
+ find-googlechrome URL \"g\"
+ find-w3m URL \"w\"
+ find-fline file name \"f\"
+ find-audio file name \"audio\"
+ find-video file name \"video\"
+ find-xpdf-page file name \"xpdf\"
+ find-evince-page file name \"evince\"
+ find-xdvi-page file name \"xdvi\"
+ find-djvu-page file name \"djvu\"
+ find-pdf-text file name \"pdftext\"
+ find-djvu-text file name \"djvutext\"
- (find-bgprocess '(\"xdvi\" \"+4\" \"/tmp/foo.dvi\"))
- (find-bgprocess '(\"xpdf\" \"/tmp/foo.pdf\" \"4\"))
+In our example with `foo-url' and `foo-file' we had:
-Alternatively, we can invoke these viewers like this,
+ Base function receives stem
+ ------------- -------- ----
+ foo-url URL showu
+ foo-file file name showf
- (find-xdvi-page \"/tmp/foo.dvi\" 4)
- (find-xpdf-page \"/tmp/foo.pdf\" 4)
-or, as they ignore extra arguments, like this,
- (find-xdvi-page \"/tmp/foo.dvi\" (+ 3 1) \"Chapter 1\")
- (find-xpdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
-where the `(+ 3 1)' and the \"Chapter 1\" are just to make these
-links more readable by humans. The `3' is what we will call the
-\"offset\" of the document: a quantity that can be added to page
-\"names\" (outside the \"front matter\" of the document) to
-convert them to page \"numbers\".
+5. Calling `code-brurl' and `code-brfile'
+=========================================
-Let's introduce more terminology. Programs like xdvi and xpdf are
-\"external viewers for PDF-like documents\", but that's too long,
-so let's shorten this to \"external PDF-like viewers\", or
-\"external viewers\", or just \"viewers\"; `find-xdvi-page',
-`find-xpdf-page' and similar functions are \"medium-level viewing
-words\".
+ (code-brurl '<U-function>
+ :remote 'br<stem> :local 'br<stem>l :dired 'br<stem>d)
+ \\---------------/ \\---------------/
\\----------------/
+ optional optional optional
+ (code-brfile '<F-function> :local 'br<stem>l :dired 'br<stem>d)
+ \\---------------/ \\----------------/
+ optional optional
+This, like many other parts of eev, is a hack with a very concise
+calling syntax - so we will see an example first, and then
+dissect it to understand precisely how it works. If you are
+curious about the inspirations behind it, here they are:
+ (find-code-c-d-intro)
+ (find-code-c-d-intro \"find-code-c-d\")
+ (find-code-c-d-intro \"Extra arguments\")
+ (find-enode \"Browse-URL\")
-The high-level way
-==================
-File names of PDF-like documents are often very long - especially
-for documents that we have \"psne\"-ed from the web. To avoid
-having to keep copies of these file names everywhere we can use
-`code-c-d'-like words - like these:
- (code-xdvi \"fd\" \"/tmp/foo.dvi\")
- (code-xpdf \"fp\" \"/tmp/foo.pdf\")
- (find-fdpage (+ 3 1) \"Chapter 1\")
- (find-fppage (+ 3 1) \"Chapter 1\")
-Each medium-level viewing word has an associated code-c-d-like
-word - that creates \"high-level viewing words\". In the example
-above, we used `code-xdvi' to create the high-level viewing word
-`find-fdpage', that invokes `find-xdvi-page', and `code-xpdf' to
-create the high-level viewing word `find-fppage', which invokes
-`find-xpdf-page',
+6. The dired variation
+======================
-Note that the \"fd\" in `find-fdpage' stands for not only the
-filename - \"/tmp/foo.dvi\" - but also for the medium-level word
-to be used - `find-xdvi-page'; same for \"fp\".
+In dired mode each line corresponds to a file
+" rest)))
+;; (find-brxxx-intro)
-Default external viewers
-========================
-We saw that for each of the supported formats of PDF-like
-documents - DVI, PostScript, PDF, DJVU - there are medium-level
-and high-level viewing words that use specific programs; for
-example, for \"xpdf\" we have `find-xpdf-page' and `code-xpdf',
-and for \"evince\" we have `find-evince-page' and `code-evince'.
-But for each of the formats we also have words that use the
-current default viewer for that format:
- Format Medium-level High-level
- ----------------------------------------
- DVI find-dvi-page code-dvi
- PostScript find-ps-page code-ps
- PDF find-pdf-page code-pdf
- DJVU find-djvu-page code-djvu
-The four `find-<formatname>-page' words above are aliases to
-`find-<viewername>-page' names, and to change a default viewer
-you should use a `defalias' on the `find-', like these:
- (defalias 'find-pdf-page 'find-evince-page)
- (defalias 'find-pdf-page 'find-xdpf-page)
+;;;
+;;; _ __ ___ _ __ ___
+;;; | '_ \/ __| '_ \ / _ \
+;;; | |_) \__ \ | | | __/
+;;; | .__/|___/_| |_|\___|
+;;; |_|
+;;
+;; �find-psne-intro� (to ".find-psne-intro")
+;; (find-TH "eev-article" "local-copies")
+;; (find-angg ".emacs" "brep")
+;; (find-eev "eev-browse-url.el" "find-psne-links")
+;; (find-eev "eev-browse-url.el" "brep")
-After running a `defalias' like the above all the high-level
-viewing words defined using `code-pdf' will automatically switch
-to the new default viewer (because words defined with `code-pdf'
-call `find-pdf-page').
+(defun find-psne-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-psne-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-psne-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-psne-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 needs to be rewritten!
+It expands an idea that was mentioned briefly at:
+ (find-eev-quick-intro \"9.3. Hyperlinks to PDF files\")
+ (find-eev-quick-intro \"9.3. Hyperlinks to PDF files\" \"local copies\")
-PDF-like documents as text
-==========================
-Some PDF-like documents can be converted to text - usually uglily
-and imprecisely, but the result is often useful anyway - by
-external programs like \"pdftotext\" and \"djvutxt\". The
-medium-level sexps below invoke these programs on the given
-filenames and displays their output in an Emacs buffer:
- (find-pdftotext-text \"/tmp/foo.pdf\")
- (find-djvutxt-text \"/tmp/foo.djvu\")
-We can also use the correspondent generic medium-level words,
-that are aliases to the default converters:
+Local copies of files from the internet
+=======================================
+Emacs knows how to fetch files from the internet, but for most
+purposes it is better to use local copies. Suppose that the
+environment variable $S is set to ~/snarf/; then running this
- (find-pdf-text \"/tmp/foo.pdf\")
- (find-djvu-text \"/tmp/foo.djvu\")
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+ mkdir -p $S/http/www.gnu.org/software/emacs/
+ cd $S/http/www.gnu.org/software/emacs/
+ wget http://www.gnu.org/software/emacs/emacs-paper.html
+ echo 'http://www.gnu.org/software/emacs/emacs-paper.html' >> ~/.psne.log
-As the output of these converters is also divided into pages -
-with formfeeds as separators - it is easy to jump to specific
-pages in the output, and if the first argument after the file
-name is a number it is interpreted as a page number; string
-arguments coming after that are interpreted as strings to be
-search (forward) for. So these links make sense:
+ # (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
+ # (find-w3m \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+creates a local copy of `emacs-paper.html' inside ~/snarf/http/
+and appends the URL to the file ~/.psne.log. The two lines in
+comments are hyperlinks to the local copy; The `find-fline' opens
+it as a file in the obvious way, and `find-w3m' opens it \"as
+HTML\", using a text-mode web browser called w3m that can be run
+either in standalone mode or inside Emacs; `find-w3m' uses w3m's
+Emacs interface, and it accepts extra arguments, which are
+treated as a pos-spec-list.
-and note that the following pair of links make sense too - the
-first one calls an external viewer, the second one opens the
-conversion to text:
- (find-pdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
-Note that they both point to the same page... The argument
-\"Chapter 1\" is ignored in the first link, but when a pair of
-links like that appear on consecutive lines it is clear for human
-readers that they are both links to the same place, only rendered
-in different ways. Note that the passage from this:
+The old way: psne
+=================
+A long time ago eev used to include a shell function called
+`psne' that ran all that with a single command. This:
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
+ psne http://www.gnu.org/software/emacs/emacs-paper.html
-to this:
+would run the `mkdir', the `cd', the `wget' and the `echo' above.
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+If psne were just a shell script then it wouldn't be able to
+change the current directory for the calling shell, so it had to
+be defined as shell function instead of a script, and the user
+had to patch his ~/.bashrc (or ~/.zshrc, or whatever) to install
+the definition for psne and make it available. That was VERY
+clumsy.
-is a special case of \"refining hyperlinks\", an idea that we saw
-in:
+From now on we will use \"psne\" as a verb: to psne a URL means
+to download a local copy of it into the right place, change to
+its directory and save its name into the file \"~/.psne.log\".
- (find-eval-intro \"Refining hyperlinks\")
+The new way: M-x brep
+=====================
+Try to run this:
-High-level hyperlinks to pdf-like documents
-===========================================
-By executing
+ (find-psne-links \"http://www.gnu.org/software/emacs/emacs-paper.html\";)
- (code-pdf \"fp\" \"/tmp/foo.pdf\")
- (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+or, equivalently, put the point on the URL below and then run
+`M-x brep':
-we can use shorter hyperlinks, like
+ http://www.gnu.org/software/emacs/emacs-paper.html
- (find-fppage (+ 3 1) \"Chapter 1\")
- (find-fptext (+ 3 1) \"Chapter 1\")
+You will get a temporary buffer for psne-ing the URL above. It
+will contain a `mkdir', a `cd', a `wget' and an `echo', plus an
+eepitch block and some elisp hyperlinks, and it can be executed
+with `F8's. Moral of the story: the \"new\" way to download a
+local copy of a url is to put the point on it, then run `M-x
+brep', then execute the resulting e-script. This does not require
+any patching of rcfiles, as the shell-function version of `psne'
+used to do.
-instead of the longer forms with `find-pdf-page' and
-`find-pdf-text'. This works exactly like `code-c-d', as explained
-here:
- (find-code-c-d-intro)
-Try these sexps to see the code that the `code-pdf' and the
-`code-pdf-text' above execute:
+The environment variable $S
+===========================
+If when eev is loaded by Emacs the environment variable $S is
+unset, it will be set to a default value - namely, to the
+expansion of \"$HOME/snarf\". Processes started from Emacs, such
+as shells created with `eepitch-shell' or `find-sh', or external
+terminals created by sexps like
- (find-code-pdf \"fp\" \"/tmp/foo.pdf\")
- (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+ (find-bgprocess \"xterm\")
+ (find-bgprocess \"gnome-terminal\")
+ (find-bgprocess \"eterm\")
-There is a wrapping comand for producing these
-`code-pdf'/`code-pdf-text' pairs quickly - `M-P'. Try it here:
+will then inherit that value. Try it:
- fp /tmp/foo.pdf
+ (getenv \"S\")
+ (find-sh0 \"echo $S\")
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+echo $S
+Try also to create an external shell not from Emacs - for
+example, from your window manager's list of available
+applications, or from a text-mode login - and run \"echo $S\"
+there: you will notice that $S is unset.
+Old versions of eev used to require the user to run a script that
+would patch his rcfiles (i.e., ~/.bashrc, ~/.zshrc, etc) to set
+$S on startup. That turned out to be unreliable - it was better
+to teach people how to distinguish those processes that inherit
+$S from Emacs from those that don't, and let the experts patch
+their rcfiles by hand.
-Producing and refining hyperlinks to pages
-==========================================
-We also have something like this
- (find-eval-intro \"Producing and refining hyperlinks\")
-for pdf-like documents, that will let us produce hyperlinks to
-the current page of the current pdf-like document very quickly,
-but it depends on several hacks.
+`browse-url' and friends
+========================
+If you place the point on the URL below
-Note that the functions `code-pdf', `code-pdf-text',
-`find-xxxpage', `find-xxxtext', set the global variables
-`ee-page-c', `ee-page-fname', and `ee-page-offset'. You can
-inspect their definitions with:
+ http://www.gnu.org/software/emacs/emacs-paper.html
- (find-code-pdf \"fp\" \"/tmp/foo.pdf\")
- (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+and run `M-x browse-url', Emacs will make an external browser
+visit the remote version of that URL. One (bad) way to visit the
+local copy of that URL is to modify the URL above by hand to
+adjust it to your value of $S, until you obtain something like
+this:
-Here's how these variables are used. Try this:
+ file:///home/edrx/snarf/http/www.gnu.org/software/emacs/emacs-paper.html
- (code-pdf \"fp\" \"/tmp/foo.pdf\")
- (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
- (kill-new \"Two\")
- (eek \"M-h M-p\")
+and then run `M-x browse-url' on it.
-You should get a page with several hyperlinks to the \"current
-page\" of the current pdf-like document, including some like
-these:
+One - rather primitive - way of visiting the local copy of that
+URL with find-file is to modify the URL by hand, replacing its
+\"http://\"; with n \"$S/http/\", and then visit that file. For
+example:
- (find-fppage 1)
- (find-fptext 1)
- (find-fppage (+ 3 -2))
- (find-fptext (+ 3 -2))
+ http://www.gnu.org/software/emacs/emacs-paper.html
+ (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
- (find-fppage 1 \"Two\")
- (find-fptext 1 \"Two\")
- (find-fppage (+ 3 -2) \"Two\")
- (find-fptext (+ 3 -2) \"Two\")
+If you put the point on the URL and run `M-x brfl' on it you will
+visit the local copy \"as a file\", with `find-file' /
+`find-fline'. Visiting URLs - or their local copies - is
+something that we do so frequently that we need ways to do that
+with few keystrokes, which is why `brfl' has a short - and
+cryptic - name. The conventions are:
-Where did the \"fp\", the \"1\", the \"3\", the \"-2\" and the
-\"Two\" above come from?
+ \"br\" is the common prefix for all the browse-url-like
+ functions in eev,
+ \"f\" means to use `find-fline' (or, equivalently, `find-file'),
+ \"l\" is an optional suffix meaning to use the local copy.
-The page number, which in the links above is sometimes \"1\",
-sometimes \"(+ 3 -2)\", is obtained by counting the number of
-formfeeds before point; this makes sense only when we are
-visiting the buffer generated by \"(find-fptext ...)\". The
-\"fp\" is taken from the variable `ee-page-c', which was set by
-`(code-pdf-text \"fp\" ...)' or by `(find-fptext ...)'; same for \"3\",
-which is taken from the variable `ee-page-offset'. Finally, the \"Two\"
-is the last kill, from the top of the kill-ring; we usually set it by
-selecting a region of text from the `(find-fptext ...)' buffer and
-typing `M-w'.
+The details on how to create these \"brxxx functions\" are here:
-An alternative way to produce hyperlinks to pages, which, as the hack
-above, also uses `ee-page-c' and `ee-page-offset', is to prepare a
-series of lines with a page number followed by a text that will play a
-similar role to the \"last kill\", and then type `M-Q' on each line. Try
-this below, by first executing the `code-pdf-text' then typing four
-`M-Q's.
+ (find-brxxx-intro)
- (code-pdf \"debt\" \"~/books/graeber__debt.pdf\")
- (code-pdf-text \"debt\" \"~/books/graeber__debt.pdf\" 8)
+" rest)))
- 1 1 On The Experience of Moral Confusion
- 21 2 The Myth of Barter
- 43 3 Primordial Debts
- 73 4 Cruelty and Redemption
+;; (find-enode "Command Index" "browse-url")
+;; (find-efunction 'browse-url)
+;; (find-elnode "System Environment")
+;; (find-enode "Environment")
+;; (find-eevfile \"eev.el\" \"$HOME/snarf\")
-It is usually not hard to produce such page-number-plus-text
-lines for `M-Q' from the table of contents of a book. The ones
-above were extracted from
+;; (find-psne-intro)
- (find-debttext 7 \"Contents\")
-with a bit of fiddling by hand and keyboard macros. Keyboard
-macros are VERY useful; if you don't use them yet, see:
- (find-enode \"Keyboard Macros\")
-" rest)))
-;; (find-pdf-like-intro)
@@ -5459,152 +5658,6 @@ Experiments
-;; �find-anchors-intro� (to ".find-anchors-intro")
-;; (find-intro-links "anchors")
-
-(defun find-anchors-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-anchors-intro)*"))
- (apply 'find-estring-lv "\
-\(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)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
-
-
-
-NOTE: This has been mostly superseded by:
-(find-eev-quick-intro \"8. Anchors\")
-
-
-
-Introduction: `ee-anchor-format' and `to'
-=========================================
-A hyperlink like
-
- (to \"foo\")
-
-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:
-
- ee-anchor-format
- (format ee-anchor-format \"foo\")
- (ee-goto-position (format ee-anchor-format \"foo\"))
-
-We will call strings in `��'s _anchors_, and we will say
-that `(to \"foo\")' jumps \"to the anchor `foo'\".
-
-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.
-
-
-
-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
-
- (find-eev \"eev-anchors.el\")
-
-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�\".
-
-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.
-
-
-
-Indexes
-=======
-In a situation like this,
-
- �one� (to \"two\")
- �two� (to \"one\")
-
-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_.
-
-In a case like this,
-
- �.three� (to \"three\")
- �three� (to \".three\")
-
-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:
-
- (find-eev \"eev-intro.el\" \".find-eev-intro\")
-
-
-
-
-Creating index/section anchor pairs
-===================================
-Use `M-A' (`eewrap-anchor'). Note that this has been briefly
-mentioned here:
-
- (find-wrap-intro \"All wrapping functions\")
-
-It will convert a line with a syntax like
-
- comment-prefix <anchor-name>
-
-into:
-
- comment-prefix �.anchor-name� (to \"anchor-name\")
- comment-prefix �anchor-name� (to \".anchor-name\")
-
-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-anchor
-===========
-\(find-eev \"eev-anchors.el\")
-\(find-eev \"eev-anchors.el\" \"find-anchor\")
-
-
-code-c-d and :anchor
-====================
-\(find-eev \"eev-code.el\" \"ee-code-c-d-:anchor\")
-
-
-
-# Local Variables:
-# coding: raw-text-unix
-# ee-anchor-format: \"�%s�\"
-# End:
-" rest)))
-
-;; (find-anchors-intro)
-
-
-
;;; _
;;; _ __ _ __ ___ _ __ __ _ _ __ ___ __| |
@@ -6648,8 +6701,13 @@ This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.
-\[At present this is just a _skeleton_ for a tutorial on defining
-functions in Lisp...]
+Note: this intro needs to be rewritten!
+I wrote it for a mini-tutorial on Lisp that I gave.
+It complements this:
+ (find-eev-quick-intro \"2. Evaluating Lisp\")
+ (find-eval-intro \"3. What to execute, and in what order\")
+ (find-eval-intro \"3. What to execute, and in what order\" \"defun\")
+
diff --git a/eev-mode.el b/eev-mode.el
index 05dfa07..673240d 100644
--- a/eev-mode.el
+++ b/eev-mode.el
@@ -19,7 +19,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019jan23
+;; Version: 2019feb01
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-mode.el>
@@ -130,9 +130,29 @@ and: (find-eval-intro \"`M-k'\")"
;;
)
+
+;; Now we run the function `eev-mode-map-set' above, but we only do
+;; that if the variable `eev-mode-map' holds nil:
+;;
(when (not eev-mode-map)
(setq eev-mode-map (make-sparse-keymap))
(eev-mode-map-set))
+;;
+;; The (when ...) above means that if you want to define your own
+;; `eev-mode-map' with different keybindings you can do that by
+;; putting something like this in your .emacs _before the point where
+;; you load eev_:
+;;
+;; (setq eev-mode-map (make-sparse-keymap))
+;; (define-key eev-mode-map "\M-e" 'ee-eval-sexp-eol)
+;; (define-key eev-mode-map "\M-E" 'ee-eval-last-sexp)
+;; (define-key eev-mode-map "\M-k" 'ee-kill-this-buffer)
+;; (define-key eev-mode-map "\M-K" 'bury-buffer)
+;; (define-key eev-mode-map "\M-j" 'eejump)
+;; (define-key eev-mode-map [f8] 'eepitch-this-line)
+;; (define-key eev-mode-map "\M-T" 'eewrap-eepitch)
+
+
diff --git a/eev-multiwindow.el b/eev-multiwindow.el
index dd0cff4..b7f105f 100644
--- a/eev-multiwindow.el
+++ b/eev-multiwindow.el
@@ -19,7 +19,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019jan23
+;; Version: 2019feb01
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-multiwindow.el>
@@ -52,6 +52,7 @@
(defun find-wset-o () (other-window 1))
(defun find-wset-O () (other-window -1))
(defun find-wset-+ () (balance-windows))
+(defun find-wset-c () (recenter))
(defun find-wset-_ () (eval (car sexps)) (setq sexps (cdr sexps)))
(defun find-wset-\ ()) ; allow whitespace
@@ -66,6 +67,7 @@ Here is a list of the standard characters that can be used in
CHARS:
s: `split-window-sensibly'
o: `other-window' (C-x o)
+: `balance-windows' (C-x +)
+ c: `recenter' (C-l)
_: execute the next sexp in SEXPS.
To add support for a new character, say `C', just define
- [elpa] externals/eev 9d39df9 36/64: Several clean-ups in eev-elinks.el and eev-tlinks.el., (continued)
- [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, 2019/04/07
- [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 <=
- [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