[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/eev a5f9343 30/64: Small changes in `find-eev-install-l
|
From: |
Stefan Monnier |
|
Subject: |
[elpa] externals/eev a5f9343 30/64: Small changes in `find-eev-install-links' and in eev-intro.el. |
|
Date: |
Sun, 7 Apr 2019 16:59:07 -0400 (EDT) |
branch: externals/eev
commit a5f93439db021369c365b69428c52b55db1bb975
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>
Small changes in `find-eev-install-links' and in eev-intro.el.
---
ChangeLog | 8 +
VERSION | 4 +-
eev-brxxx.el | 27 +-
eev-intro.el | 10038 ++++++++++++++++++++++++++++----------------------------
eev-tlinks.el | 21 +-
5 files changed, 5028 insertions(+), 5070 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index e2250da..700a4ba 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2019-01-30 Eduardo Ochs <address@hidden>
+
+ * eev-tlinks.el (find-eev-install-links): small changes.
+
+ * eev-intro.el (find-videos-intro): small changes.
+ (find-eev-intro): small changes.
+ (find-eev-quick-intro): small changes.
+
2019-01-29 Eduardo Ochs <address@hidden>
* eev-wrap.el (ee-wrap-pdflike): use `code-pdf-page' instead of
diff --git a/VERSION b/VERSION
index 7ce726c..a7ca754 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Tue Jan 29 14:34:37 GMT 2019
-Tue Jan 29 12:34:37 -02 2019
+Wed Jan 30 21:51:21 GMT 2019
+Wed Jan 30 19:51:21 -02 2019
diff --git a/eev-brxxx.el b/eev-brxxx.el
index 2070a9b..8f9f55e 100644
--- a/eev-brxxx.el
+++ b/eev-brxxx.el
@@ -288,26 +288,25 @@ This should be made smarter - file:// urls should be
returned unchanged."
;;; \___\___/ \__,_|\___| |_.__/|_| /_/\_\/_/\_\/_/\_\___/
;;;
;; �code-brxxxs� (to ".code-brxxxs")
+;; See: (find-eev "eev-pdflike.el" "code-brxxxs")
+;; (find-eev "eev-blinks.el" "find-w3m")
+;; (find-efile "net/browse-url.el")
-;; See:
-;; (find-eev "eev-blinks.el" "find-w3m")
-;; (find-efile "net/browse-url.el")
+(defun find-googlechrome (url) (find-bgprocess `("google-chrome" ,url)))
+(defun find-firefox (url) (find-bgprocess `("firefox" ,url)))
-(code-brurl 'find-psne-links
- :remote 'brep)
-(code-brurl 'browse-url-firefox
- :remote 'brm :local 'brml :dired 'brmd)
-(code-brurl 'find-googlechrome
- :remote 'brg :local 'brgl :dired 'brgd)
-(code-brurl 'find-w3m
- :remote 'brw :local 'brwl :dired 'brwd)
+(code-brurl 'find-psne-links :remote 'brep)
-(code-brfile 'find-fline :local 'brfl)
+;; (code-brurl 'browse-url-firefox :remote 'brm :local 'brml :dired 'brmd)
+;; (code-brurl 'browse-url-firefox :remote 'brff :local 'brffl :dired 'brffd)
+(code-brurl 'find-firefox :remote 'brm :local 'brml :dired 'brmd)
+(code-brurl 'find-firefox :remote 'brff :local 'brffl :dired 'brffd)
+(code-brurl 'find-googlechrome :remote 'brg :local 'brgl :dired 'brgd)
+(code-brurl 'find-w3m :remote 'brw :local 'brwl :dired 'brwd)
+(code-brfile 'find-fline :local 'brfl)
-(defun find-googlechrome (url) (find-bgprocess `("google-chrome" ,url)))
-(defun find-firefox (url) (find-bgprocess `("firefox" ,url)))
;; These are defined elsewhere.
diff --git a/eev-intro.el b/eev-intro.el
index 3ec0828..a35afe5 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -1,7 +1,7 @@
-;;; eev-intro.el --- intro scripts for eev
+;;; eev-intro.el --- sandboxed tutorials for eev, like (find-eev-quick-intro)
-;; Copyright (C) 2013,2014,2016,2017,2018 Free Software Foundation,
-;; Inc.
+;; Copyright (C) 2013,2014,2016,2017,2018,2019 Free Software
+;; Foundation, Inc.
;;
;; This file is (not yet?) part of GNU eev.
;;
@@ -20,7 +20,7 @@
;;
;; Author: Eduardo Ochs <address@hidden>
;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version: 2019jan29
+;; Version: 2019jan30
;; Keywords: e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -31,6 +31,18 @@
;;; Commentary:
;;
+;; 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.
+;;
+;; 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)
@@ -43,7 +55,11 @@
;; Quick index:
;; �.find-intro-here� (to "find-intro-here")
;;
+;; �.find-eev-quick-intro� (to "find-eev-quick-intro")
+;; �.find-emacs-keys-intro� (to "find-emacs-keys-intro")
+;; �.find-eev-install-intro� (to "find-eev-install-intro")
;; �.find-eev-intro� (to "find-eev-intro")
+;;
;; �.find-eval-intro� (to "find-eval-intro")
;; �.find-eepitch-intro� (to "find-eepitch-intro")
;; �.find-wrap-intro� (to "find-wrap-intro")
@@ -64,11 +80,8 @@
;; �.find-videos-intro� (to "find-videos-intro")
;; �.find-defun-intro� (to "find-defun-intro")
-;; �.find-emacs-keys-intro� (to "find-emacs-keys-intro")
;; �.find-emacs-intro� (to "find-emacs-intro")
;; �.find-org-intro� (to "find-org-intro")
-;; �.find-eev-quick-intro� (to "find-eev-quick-intro")
-;; �.find-eev-install-intro� (to "find-eev-install-intro")
;; �.find-escripts-intro� (to "find-escripts-intro")
;; See: (find-anchors-intro)
@@ -127,659 +140,438 @@ Only works for \"(defun find-xxx-intro ...)s\"."
(defalias 'fh 'find-intro-here)
-)
+(defun find-intro-source ()
+ (interactive)
+ (find-2a
+ '(find-eev "eev-intro.el"
+ (format "find-%s-intro" (ee-intro-bufferp))
+ (ee-last-kill))
+ nil))
+(defalias 'fi 'find-intro-source)
+)
-;;; _ _
-;;; ___ _____ __ (_)_ __ | |_ _ __ ___
-;;; / _ \/ _ \ \ / /____| | '_ \| __| '__/ _ \
-;;; | __/ __/\ V /_____| | | | | |_| | | (_) |
-;;; \___|\___| \_/ |_|_| |_|\__|_| \___/
-;;;
-;; This works as an index.
-;; (find-intro-links "eev")
-;; �find-eev-intro� (to ".find-eev-intro")
-(defun find-eev-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-eev-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-eev-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-eev-intro\")
-Main intros: (find-eev-quick-intro)
+;;; _ _ _ _
+;;; ___ _____ __ __ _ _ _(_) ___| | __ (_)_ __ | |_ _ __ ___
+;;; / _ \/ _ \ \ / /____ / _` | | | | |/ __| |/ /____| | '_ \| __| '__/ _ \
+;;; | __/ __/\ V /_____| (_| | |_| | | (__| <_____| | | | | |_| | | (_) |
+;;; \___|\___| \_/ \__, |\__,_|_|\___|_|\_\ |_|_| |_|\__|_| \___/
+;;; |_|
+;;
+;; �find-eev-quick-intro� (to ".find-eev-quick-intro")
+;; (find-intro-links "eev-quick")
+
+(defun find-eev-quick-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-eev-quick-intro)*"))
+ (apply 'find-estring (ee-tolatin1 "\
+\(Re)generate: (find-eev-quick-intro)
+Source code: (find-efunction 'find-eev-quick-intro)
+More intros: (find-emacs-keys-intro)
+ (find-escripts-intro)
+ (find-eev-intro)
(find-eval-intro)
(find-eepitch-intro)
- (find-wrap-intro)
-Index to the source files: (find-eev \"eev2-all.el\")
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.
-The quickest way to reach this index is with `M-5 M-j'.
-
+The quickest way to open or recreate this is with `M-5 M-j'.
-Here is a list of all the available sandbox-y tutorials that
-explain parts and concepts of eev, listed in (a kind of)
-recommended reading order:
-
- 00. (find-eev-quick-intro)
- 0. (find-eev-intro)
- 1. (find-eval-intro)
- 2. (find-eepitch-intro)
- 3. (find-wrap-intro)
- 4. (find-links-intro)
- 5. (find-eejump-intro)
- 6. (find-code-c-d-intro)
- 7. (find-psne-intro)
- 9. (find-brxxx-intro)
- 10. (find-pdf-like-intro)
- 11. (find-audiovideo-intro)
- 12. (find-anchors-intro)
- 13. (find-multiwindow-intro)
- 14. (find-rcirc-intro)
- 15. (find-templates-intro)
- 16. (find-prepared-intro)
- 17. (find-bounded-intro)
- 18. (find-channels-intro)
- 19. (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
-these ideas pervasive.
+This is a tutorial for real beginners.
+It supposes that you have Emacs installed.
+You may start by watching these (old) videos:
-The last item above is an index of the video tutorials, with
-scripts for downloading local copies of them and links to
-important positions in the videos.
+ http://angg.twu.net/eev-videos/video-eev-quick-0.mp4 (installation basics)
+ http://angg.twu.net/eev-videos/video4-eepitch.mp4 (eev's main ideas)
-There are also these two, ahem, \"things\", that I use in
-workshops, but that are not very eev-specific:
- A. (find-emacs-intro)
- B. (find-defun-intro)
- C. (find-eev-quick-intro)
+1. Installing eev
+=================
+Open the page at
+ http://angg.twu.net/eev-intros/find-eev-quick-intro.html
-Installation: way 1
-===================
-If you're a real beginner and you are reading this in a web browser
-then this is the easiest way to install eev and start playing with it.
-Mark the multi-line \"{ ... }\" block below, copy it to the clipboard
-with ctrl-C, and paste it to a shell running in a terminal to execute
-its commands. It will download the current version of eev and unpack
-it into ~/eev/.
+in a browser, and open a terminal running a shell. Mark the multi-line
+\"{ ... }\" block below, copy it to the clipboard with ctrl-C, and paste
+it into the shell to run its commands.
{
- rm -Rv ~/eev/
- mkdir ~/eev/
- cd ~/eev/
+ rm -Rv ~/eev
+ rm -Rv ~/eev2/
+ mkdir ~/eev2/
+ cd ~/eev2/
rm -v eev2.tgz
wget http://angg.twu.net/eev-current/eev2.tgz
tar -xvzf eev2.tgz
-}
-
-Now do the same with this block:
-
-{
{
echo '#!/bin/sh'
- echo 'cd ~/eev/ && emacs -l ./eev-readme.el --eval=\"(find-eval-intro)\"'
- } > ~/e
- chmod 755 ~/e
+ echo 'cd ~/eev2/ && emacs -l eev-readme.el
--eval=\"(find-eev-quick-intro)\" $*'
+ } > ~/eev
+ chmod 755 ~/eev
}
You now have a shell script that you can invoke with
- ~/e
+ ~/eev
+
+that starts Emacs, loads eev, and opens a copy of this tutorial.
-that starts Emacs, loads eev, and opens this tutorial:
+Every time that Emacs gets stuck into something that you don't know
+how to leave, or how to undo, you should kill the Emacs window and
+start it again by typing \"~/eev\" again in the shell prompt.
- (find-eval-intro)
+Eventually you will learn how go get out of everything and how to undo
+almost anything, _BUT THAT WILL NOT HAPPEN IN THE FIRST TEN MINUTES_.
+This tutorial is intented to make you learn the most essential things
+in the first ten minutes - including how to navigate in Emacs's
+manuals.
-Once you learn how to navigate the help system by following elisp
-hyperlinks and going back, the rest is easy.
+For more on ways to install eev see:
+ (find-eev-install-intro)
-The README
-==========
-The README for eev2 is an elisp file,
- (find-eev \"eev-readme.el\")
-that contains an easy way of installing eev - in either a
-temporary directory or in a permanent one - and initial
-instructions for trying the main keys. HIGHLY RECOMMENDED!
+2. Evaluating Lisp
+==================
+The most important idea in Emacs is that Lisp code can appear
+anywhere, and you can evaluate a Lisp expression (a \"sexp\") by
+placing the cursor (the \"point\") just after it and typing `C-x
+C-e'; the result is then displayed in the echo area.
+Note: `C-e' means control-E, `M-e' means alt-e, `M-E' means
+alt-shift-e. If you have Caps Lock on then Emacs will receive an `M-E'
+if you type alt-e, and `M-e' if you type alt-shift-e. Hint: avoid Caps
+Lock!
+You can try `C-x C-e' in the line below, with the point in the three
+different indicated positions - you should get different results...
-Installing eev
-==============
-The instructions below are adapted from:
+ (+ (* 2 3) (* 4 5))
+ ^ ^^
+ | | \\
+ 6 20 26
- (find-eev-update-links \"/tmp/eev/\")
- and: (find-eev \"eev-readme.el\")
+...but `C-x C-e' is not beginner-friendly, and it even enters a
+debugger that is hard to leave if it finds errors, so let's see
+something better.
-You should download the tarball with all the elisp files, unpack
-it somewhere - doing something like this (here you can use F8 if
-you already have eev installed),
+When you type `M-e' emacs moves the point to the end of the
+current line, then runs a variant of `C-x C-e'. Try this on each
+line of the block below:
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-rm -Rv /tmp/eev/
-mkdir /tmp/eev/
-cd /tmp/eev/
-wget http://angg.twu.net/eev-current/eev2.tgz
-tar -xvzf eev2.tgz
+ (+ (* 2 3)
+ (* 4 5)
+ )
-and then evaluate these sexps (type C-x C-e at the end of each
-line):
+`M-e' accepts several different numeric prefixes that alter its
+behavior. We are only interested in one of them now - `M-0 M-e'
+highlights the sexp for a fraction of a second insted of executing it.
+Try it above.
- (add-to-list 'load-path \"/tmp/eev/\")
- (require 'eev2-all)
- (eev-mode 1)
-This will turn on eev-mode - which just activates a few
-keybindings. To understand the main ideas, please follow these
-two tutorials:
- (find-eval-intro)
- (find-eepitch-intro)
-To toggle eev-mode on and off, use `M-x eev-mode'.
+3. Elisp hyperlinks
+===================
+Each one of the sexps below makes Emacs \"go somewhere\" if you execute
+it with `M-e'. Executing sexps like those - we will call them \"elisp
+hyperlinks\" - is like following a hyperlink in a browser.
+In a browser you can \"go back\" after following a hyperlink because the
+previous page is kept in the memory somehow. In Emacs+eev the easiest
+way to \"go back\" is with `M-k', which runs a function called
+`ee-kill-this-buffer'. If you follow one of the links below with
+`M-e', it creates a new buffer and displays it. If you then type `M-k'
+this new buffer is killed, and Emacs displays the buffer that was just
+below it, which is this tutorial... try it! Here are some nice elisp
+hyperlinks:
+ (find-fline \"/tmp/\")
+ (find-efunctiondescr 'find-file)
+ (find-man \"cat\")
-The keybindings
-===============
-`eev-mode' defines its own meanings for lots of meta-shift-letter
-key combinations - which are not normally used by Emacs - and,
-besides that, only for:
+Not all elisp hyperlinks \"go somewhere\"; some are like buttons that
+perform an action, like the one below, that acts as if the user had
+pressed a series of keys,
- `M-e' (find-eval-intro \"`M-e'\")
- `M-k' (find-eval-intro \"`M-k'\")
- `M-j' (find-eejump-intro \"\\neejump\\n\")
- `M-h' (find-links-intro \"Elisp hyperlinks buffers\")
- `<f8>' (find-eepitch-intro \"The main key: <F8>\")
+ (eek \"<down> C-a H E L L O ! <up> C-e\")
-For the full lists of keybindings, see:
+and some display their output in the echo area:
- (find-efunctiondescr 'eev-mode)
- (find-eminormodekeymapdescr 'eev-mode)
- (find-efunctiondescr 'eev-avadj-mode)
- (find-eminormodekeymapdescr 'eev-avadj-mode)
-" rest)))
+ (find-sh0 \"date\")
-;; (find-eev-intro)
+The following elisp hyperlinks may or may not work - try them too, but
+be aware that they may show errors instead of opening a new buffer.
+The first two of them open a page - actually a section, whose short
+title is \"Lisp Eval\" - from the main Emacs manual. The third one
+opens the file with the source code (in Lisp) for the function
+`find-file'.
+ (find-node \"(emacs)Lisp Eval\")
+ (find-enode \"Lisp Eval\")
+ (find-efunction 'find-file)
+If they don't work that means that you don't have the Emacs manuals,
+or the elisp source files, installed. The names for the packages which
+have those things vary from one GNU/Linux distro to another. On Debian
+something like
+ sudo apt-get install emacs24-el
+ sudo apt-get install emacs24-common-non-dfsg
+may work - but \"emacs24-common-non-dfsg\" may need you to enable
+access to the \"non-free\" respository... ask for help if you need!
+3.1. Non-elisp hyperlinks
+-------------------------
+Emacs has ways to follow URLs, but the keys for that are totally
+different from the ones for elisp hyperlinks. You can follow the URL
+below by putting the point on it and typing `M-x browse-url':
-;;; _
-;;; _____ ____ _| |
-;;; / _ \ \ / / _` | |
-;;; | __/\ V / (_| | |
-;;; \___| \_/ \__,_|_|
-;;;
-;; �find-eval-intro� (to ".find-eval-intro")
-;; (find-intro-links "eval")
-;; (find-TH "eev-article" "hyperlinks")
-;; 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)
+ http://www.lua.org/start.html
+This will make emacs invoke the default browser on that URL. See:
-(defun find-eval-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-eval-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-eval-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-eval-intro\")
-More intros: (find-eev-quick-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-It is meant as both a tutorial and a sandbox.
+ (find-enode \"Browse-URL\")
+Eev defines several functions similar to `browse-url'. These elisp
+hyperlinks
+ (find-firefox \"http://www.lua.org/start.html\";)
+ (find-googlechrome \"http://www.lua.org/start.html\";)
-For an introduction to the ideas here, see:
- (find-eev-quick-intro \"2. Evaluating Lisp\")
+invoke \"firefox\" and \"google-chrome\" respectively on the given URL;
+note that the \"firefox\" in a Debian-based system is usually a free
+derivative of Firefox, and that \"google-chrome\" does not come
+installed by default because it is \"gratis\" but not free. Also,
+ M-x brff -- runs `find-firefox' on the URL at point,
+ M-x brg -- runs `find-googlechrome' on the URL at point.
+For more on the \"brxxx functions\" of eev, see:
+ (find-brxxx-intro)
-1. The standard way to evaluate Lisp: `C-x C-e'
-===============================================
-The most important idea in Emacs is that Lisp code can appear
-anywhere, and you can evaluate a Lisp expression (a \"sexp\") by
-placing the cursor (the \"point\") just after it and typing `C-x
-C-e'; the result is then displayed in the echo area. Try it in
-the line below, with the point in the three different indicated
-positions - you should get different results.
- (+ (* 2 3) (* 4 5))
- ^ ^^
- | | \\
- 6 20 26
-2. The end of line and `M-e'
+4. Creating Elisp Hyperlinks
============================
-A common operation is to move the point to the end of the current
-line, then run `C-x C-e'. That can be done with `C-e C-x C-e',
-but eev-mode implements a shorthand for it: `M-e'. Try it here:
+You can write elisp hyperlinks by hand, but that is hard. It is better
+to generate hyperlinks automatically and then use cut and paste.
- (+ (* 2 3)
- (* 4 5)
- )
+Eev has several functions that generate \"elisp hyperlinks\" buffers.
+For example,
-`M-e' accepts several different numeric prefixes that alter its
-behavior. We are only interested in one of them now - `M-0 M-e'
-highlights the sexp for a fraction of a second insted of
-executing it. Try it above.
+ (find-efunction-links 'find-file)
-In some rare occasions we might want to run something like `M-e'
-but without moving to the end of the line first. Eev-mode
-implements a key binding for that: `M-E' (meta-shift-e). As an
-exercise, try to use `M-0 M-E' at several positions below, to
-hightlight the subsexps `(* 2 3)', `(* 4 5)', and `4'.
+creates this buffer, and switches to it:
+ ___________________________________________________________
+ |# (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)--|
+ |___________________________________________________________|
- (+ (* 2 3) (* 4 5))
+One standard way of using eev is:
+ a) we keep our current notes in a a file - for example, \"~/TODO\"
+ b) these notes are an \"executable log\" of what we did, including:
+ c) hyperlinks to things we saw or visited
+ d) commands issued to shells or shell-like programs (see sec. 6)
+The quickest way of generating hyperlinks for (c) is with `M-h M-h'
+\(`find-here-links'). When we type `M-h M-h' eev tries to generate an
+elisp hyperlinks buffer containing some hyperlinks to \"here\" - and how
+it does that depends on the major mode and on the name of the current
+buffer. For example, typing `M-h M-h' here generates:
+ ____________________________________________________________
+ |# See: |
+ |# (find-links-intro \"`find-here-links'\") |
+ |# (find-efunctiondescr 'eev-mode \"M-h M-h\") |
+ | |
+ |http://angg.twu.net/eev-intros/find-eev-quick-intro.html |
+ |# (find-eev-quick-intro) |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
+ |____________________________________________________________|
+The
-3. What to execute, and in what order
-=====================================
-Note that the order of evaluation may be important:
+ # (find-eev-quick-intro)
- (setq a 5)
- (setq a 6)
- (* a a)
+opens this tutorial.
-By executing `(setq a 5)' and then `(* a a)' above we get 25,
-by executing `(setq a 6)' and then `(* a a)' we get 36 - the
-current value of `a' is the one of the last `setq' executed.
+Cutting and pasting is explained briefly in section 5.2.
-An exercise: edit the three sexps above to introduce a
-`(setq a 22)', then use that sexp and the `(* a a)' to calculate
-the square of 22.
+A way to \"refine\" hyperlinks to make them more precise is
+explained here:
-Another exercise: just as `setq' sets variables and can override
-their previous values, `defun' defines, and redefines, functions.
-Execute the sexps below in different orders to obtain the results
-25, 36, 50, and 60.
+ (find-eval-intro \"Producing and refining hyperlinks\")
- (setq a 5)
- (setq a 6)
- (defun f (x) (* x x))
- (defun f (x) (* x 10))
- (f a)
-MORAL: Elisp code can appear anywhere in any Emacs buffer, but it
-is _passive by default_. It only gets executed if we move the
-point to the right positions and type `C-x C-e', `M-e', or
-similar keys. Sexps can be executed any number of times, in any
-order, and can be edited and modified.
+5. Links to Emacs documentation
+===============================
+Try these links (some of them need the Emacs manuals installed):
-4. Elisp hyperlinks
-===================
-Some Emacs functions can be used as hyperlinks. When sexps like
+ (find-emacs-intro \"Cutting & pasting\")
+ (find-node \"(emacs)Screen\")
+ (find-efunctiondescr 'find-file)
+ (find-efunction-links 'find-file)
- (find-file \"/tmp/\")
- (info \"(emacs)Lisp Eval\")
- (describe-function 'find-file)
- (find-function 'find-file)
- (man \"cat\")
+This part of the eev tutorials has links to almost all the keys that
+I've learned by heart after using Emacs for 20 years:
-are executed they \"open a new page\" - actually, they create a
-new buffer, or reuse it if it already exists - and it is usually
-possible to \"go back\" by killing the new buffer. However for
-some functions, like `man', which by default open a manpage in
-another window, \"going back\" would mean something different.
+ (find-emacs-intro \"Basic keys (Emacs)\")
-Eev defines several functions to let us use sexps as hyperlinks.
-The main conventions on these functions are:
+They are not very many, because I use this a lot,
- 1) their names start with \"find-\",
+ (find-node \"(emacs)M-x\")
- 2) calls to them can be \"refined\" with a pos-spec (this will
- be discussed below),
+and I use elisp hyperlinks to create quick reminders for the keys that
+I only need to remember when I am performing specific tasks.
- 3) they open the new buffer in the current window (to make it
- easier to \"go back\" after following them - see the next
- section),
+Moral: when you want a quick reference of the main Emacs and eev keys,
+type `M-2 M-j'.
- 4) they don't display much output in the echo area,
- 5) when they create temporary buffers with lots of sexps then:
- a) the first sexp in that buffer is one that can regenerate
- that buffer when executed,
+5.1. Navigating the Emacs manuals
+---------------------------------
+The Emacs manuals are in \"info\" format, which means:
- b) all the sexps are prefixed with the string stored in the
- variable `ee-hyperlink-prefix', to let these sexps be
- pasted into scripts as comments (see below).
+ a) they are divided into \"nodes\" - a top node, and chapters,
+ sections, subsections, etc,
-Note that sometimes the most obvious name for a hyperlink
-function starting with `find-' is already taken by Emacs - for
-example, `find-file' and `find-function'. In those cases eev use
-other names: `find-fline', `find-efunction', etc. Here are the
-eev versions of the links above:
+ b) the nodes in each manual in info format are organized as a tree,
+ and they're all numbered except for the top node, the indexes and
+ the appendixes. For example:
- (find-fline \"/tmp/\")
- (find-node \"(emacs)Lisp Eval\")
- (find-efunctiondescr 'find-file)
- (find-efunction 'find-file)
- (find-man \"cat\")
+ top --.-- 1 --.-- 1.1
+ | `-- 1.2
+ |-- 2
+ |-- 3 ----- 3.1 --.-- 3.1.1
+ | |-- 3.1.2
+ | `-- 3.1.3
+ |-- Appendix A
+ `-- Index
+ c) each node also has a short name. Elisp hyperlinks use the
+ (internal) name of the manual and the short name to jump straight
+ to a node in a manual. The table below has some examples:
+ Manual (full name) Node \"number\" elisp hyperlink
+ -----------------------------------------------------
+ Emacs Top (find-node \"(emacs)\")
+ Emacs 7 (find-node \"(emacs)Basic\")
+ Emacs 7.4 (find-node \"(emacs)Basic Undo\")
+ Emacs Concept Index (find-node \"(emacs)Concept
Index\")
+ Emacs Lisp Top (find-node \"(elisp)\")
+ d) Emacs uses \"Info mode\" when displaying nodes of manuals in info
+ format. These are the most important keys of Info mode:
-5. Going back
-=============
-Web browsers let you follow a hyperlink and then \"go back\".
-There are different ways of going back - if you opened the new
-page on a new window or tab, then going back means deleting the
-new window or tab (or just switching to the old window/tab); if
-you opened the new page on the same window/tab, then you need to
-use the \"back\" button.
+ q exit (go back to some other buffer)
+ (arrows) move point
+ RET follow link at point
+ TAB move to next link
+ BACKTAB move to prev link
+ n next (1->2->3->Appendix A; 3.1.1->3.1.1->3.1.2)
+ p previous (1<-2<-3<-Appendix A; 3.1.1<-3.1.1<-3.1.2)
+ u up (Top<-1<-1.1; 1<-1.2; 3<-3.1<-3.1.2, etc)
+ ] forward-node (Top->1->1.1->1.2->2->3->3.1->...->Index)
+ [ backward-node (Top<-1<-1.1<-1.2<-2<-3<-3.1<-...<-Index)
-Eev-mode defines two keys for \"going back\": `M-k', that kills
-the current buffer, and `M-K', that just hides it (\"buries\" it
-in the bottom of the list of all buffers). Try following the link
-below by <M-e>, then deleting its buffer with `M-k' to go back:
+Try the keys above now - they are VERY important! Use:
- (find-node \"(emacs)Shell\")
+ (eek \"<down> M-3 M-e ;; open the hyperlink below in another window\")
+ (find-node \"(emacs)Basic\")
+ (find-node \"(emacs)Major Modes\")
-In some cases we know that we may want to go \"forward\" again
-after going back, and we may not want to delete the target buffer
-- for example, because it would take a while to rebuild it again,
-or because we would lose the position of the point there. Most
-hyperlink functions in eev are able to reuse a buffer that
-\"looks like\" the desired target buffer; the test for
-lookalikeness is based on the name of the buffer only. Try to
-follow the links below with `M-e', then come back to this buffer
-with `M-k', then follow them again. Then try the same thing with
-`M-K' instead of `M-k', to see the difference - in the `find-sh'
-example below the \"sleep\" takes one second to run, so
-revisiting the existing output buffer after a `M-K' is much
-quicker than recreating it anew.
- (find-man \"1 bash\")
- (find-sh \"sleep 1; echo 'This was run at:'; date\")
+5.2. Cutting and pasting
+------------------------
+You can do cut, copy and paste in a \"user-friendly\" way by using
+ a) the rightmost icons in the toolbar, or
+ b) the \"Edit\" menu in the menu-bar,
+but the keys are very much worth learning:
-6. Refining hyperlinks
-======================
-Most hyperlinks functions defined by eev can be \"refined\" by
-the addition of extra arguments. These extra arguments are called
-a \"pos-spec\" (or a \"pos-spec-list\") and they specify a
-position in the target buffer. The first argument means a certain
-line number, when it is a number, or the first occurrence of a
-certain string, when it is a string. Try:
+ C-SPC -- set-mark-command (find-enode \"Setting Mark\")
+ C-x C-x -- exchange-point-and-mark (find-enode \"Setting Mark\" \"C-x
C-x\")
+ C-w -- kill-region (cut) (find-enode \"Other Kill Commands\")
+ M-w -- kill-ring-save (copy) (find-enode \"Kill Ring\")
+ C-y -- yank (paste) (find-enode \"Kill Ring\")
- (find-node \"(emacs)Command Index\")
- (find-node \"(emacs)Command Index\" \"eval-last-sexp\")
+The \"region\" where cut & paste operate is always what is between
+the \"point\" and the \"mark\". See:
-Further arguments mean either \"move down n lines\" or \"search
-for the next occurrence of a string\", depending on whether they
-are numbers or strings. Try:
+ (find-enode \"Point\")
+ (find-enode \"Mark\")
- (find-sh \"seq 2095 2115\")
- (find-sh \"seq 2095 2115\" \"2100\")
- (find-sh \"seq 2095 2115\" \"2100\" \"9\")
- (find-sh \"seq 2095 2115\" \"2100\" 2)
+Exercise: understand how the `eek' sexp below switches the two
+lines just after it.
+ (eek \"<down> C-a C-SPC <down> C-w <down> C-y 3*<up>\")
+ First
+ Second
-7. Pos-spec-lists
-===---===========
-The optional arguments that refine a hyperlink form what we call
-a \"pos-spec-list\". For example, the pos-spec-list here has two
-elements,
- (find-sh \"seq 2095 2115\" \"2100\" \"9\")
-and in most cases an empty pos-spec-list, like this,
- (find-sh \"seq 2095 2115\")
-means: \"if the target buffer already exists then just open it\"
-- so that following that hyperlink would jump to the current
-position of the point in that buffer.
-Pos-spec-lists are usually interpreted by the function
-`ee-goto-position'. The first argument is interpreted in a
-special way, according to its type:
-
- string -> jump to the first occurrence of
- that string in the buffer
- number -> jump to the n-th line
-
-and the other arguments are interpreted (recursively) by
-`ee-goto-rest':
-
- string -> jump to the next occurence of that string
- number -> move down n lines
- list -> evaluate the list
-
-If you want to add support for more complex pos-spec-lists, just
-replace `ee-goto-rest' with your own extended version.
-
-
-
-8. Anchors and pages
-====================
-\[See:\] (find-anchors-intro)
-
-Some hyperlink functions, like `find-efunction' and
-`find-evariable', jump to specific positions in buffers - the
-beginning of the definition of a function or a variable in the
-source code - even when their pos-spec-lists are empty, so they
-process all their extra arguments with just `ee-goto-rest'.
-
-Other hyperlink functions transform the first argument of a
-pos-spec-list in a special way it if is a string - for example,
-in `find-available', which is based on `find-Package',
-
- (find-available \"bash\")
- (find-available \"bash\" \"bash-doc\")
-
-the argument \"bash\" is converted to \"\\nPackage: bash\\n\",
-and the two hyperlinks above jump to the description of the
-package \"bash\" in the list of the available packages in a
-Debian system.
-
-The functions based on `find-anchor' transform an initial string
-argument in the pos-spec-list by running `ee-format-as-anchor' on
-it [TODO: document this], and the ones based on
-`ee-goto-position-page' jump to the n-th \"page\" of a buffer if
-the first argument of the pos-spec-list is a number, n; for
-exemple, if n is 234 that will jump to the 233-th formfeed (233
-and not 234 because the page 1 is before the first formfeed). For
-more on \"pages\", see:
-
- (find-pdf-like-intro \"PDF-like documents as text\")
-
-
-
-
-9. Producing and refining hyperlinks
-====================================
-If you are on an Info page, typing `M-h M-i' will create a
-temporary buffer containing a header - which we will discuss
-later - and several (possibly equivalent) links to that info
-page. Something like this:
- ________________________________________________________
- |;; (find-einfo-links) |
- | |
- |;; (info \"(emacs)Misc Buffer\") |
- |;; (find-node \"(emacs)Misc Buffer\") |
- |;; (find-enode \"Misc Buffer\") |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental)---|
- |________________________________________________________|
-
-These links are meant to be cut & pasted - possibly after
-refining them to make them more precise. Let's look first at the
-two key sequences that make refining much easier. Remember that
-`M-w' (`kill-ring-save') is roughly correspondent to what is
-called \"copy\" is most modern interfaces, and `C-y' (`yank') is
-roughly correspondent to \"paste\". Both `M-w' and `C-y' operate
-on Emacs's \"kill ring\", and to make our examples trivial to
-follow we will first put a string on the kill ring:
-
- (kill-new \"C-y\")
- (car kill-ring)
-
-Now let's see how refine hyperlinks quickly. `M-h M-2' duplicates
-the current line; we will use that to refine a copy of a working
-hyperlink, instead of working directly on the original, and
-risking breaking it. And `M-h M-y' refines the hyperlink on the
-current line by adding a string - the top element in the kill
-ring - to its sexp. Try this below; you should be able to convert
-
- (find-enode \"Kill Ring\")
- (find-enode \"Yanking\")
-
-into
-
- (find-enode \"Kill Ring\")
- (find-enode \"Kill Ring\" \"C-y\")
- (find-enode \"Yanking\")
- (find-enode \"Yanking\" \"C-y\")
-
-with few keystrokes, as you can leave the Meta key pressed. The
-full key sequence for duplicating and refining is `M-h M-2 M-h
-M-y', but we can think of it as `M-h2hy'.
-
-Now try a more serious exercise: follow the `(find-enode ...)'
-hyperlink below, copy a word or two from its contents to the kill
-ring with `M-w', then generate the temporary buffer with
-hyperlinks to that Info page with `M-h M-i', then duplicate one
-of its hyperlinks with `M-h M-2', refine it with `M-h M-y', and
-copy the result to this sandbox with `M-w' (or `C-w') and `C-y'.
-As this is a long sequence of instructions, it is better to run
-`C-x 1 C-x 2' or `C-x 1 C-x 3' before following the hyperlink, to
-keep the instructions visible.
-
- (find-enode \"Command Index\")
-
-
-
-
-What else?
-==========
-Eev-mode defines several other key sequences similar to `M-h
-M-i'. You can get the full list here:
-
- (find-efunctiondescr 'eev-mode)
- (find-efunctiondescr 'eev-mode \"M-h f\")
-
-Try also this:
- (find-efunction-links 'eev-mode)
-
-and for other tutorials like this one, try:
-
- (find-wrap-intro)
- (find-eepitch-intro)
-
-\[To do: explain M-x ee-hyperlink prefix and how to embed
-hyperlinks in scripts]
-" rest)))
-
-;; (find-eval-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-eepitch-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-eepitch-intro\")
-More intros: (find-eev-quick-intro)
- (find-eval-intro)
- (find-wrap-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial (for eepitch) and a sandbox.
-
-
-
-For an introduction to the ideas here, see:
- (find-eev-quick-intro \"6. Controlling shell-like programs\")
-
-
-
-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) 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,
-
- 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,
+6. Controlling shell-like programs
+==================================
+This is the second main feature of eev. The hyperlinks thing used the
+keys `M-e', `M-k', and `M-h M-h', plus standard Emacs keys for cutting
+and pasting. The module of eev that controls shell-like programs - it
+is called \"eepitch\" - uses `<F8>' and `M-T'. Note that it is
+`alt-shift-t', to not interfere with Emacs's `M-t'.
- b) by looking at the full _transcript_ of our interaction with
- the shell.
+The sections below were adapted from:
-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.
+ (find-eepitch-intro \"The main key: <F8>\")
-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>
-==================
+6.1. The main key: <F8>
+-----------------------
Emacs can run a shell in a buffer, and it can split its frame
into windows, like this:
___________________
@@ -825,8 +617,8 @@ echo \"We changed to: $(pwd)\"
-Other targets
-=============
+6.2. 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:
@@ -859,2107 +651,1924 @@ echo ...and bye >> /tmp/o
print(open(\"/tmp/o\").read())
- There is a (much) more advanced example of working with several
- targets here:
- (find-prepared-intro \"An `ee' for Python\")
+6.3. 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
-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)
+6.4. 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'.
-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.
+7. Quick access to one-liners
+=============================
+7.1. eejump
+-----------
+We may have elisp one-liners that we want to be able to execute very
+quickly, and from anywhere. For example, I keep all my notes that I
+have not organized yet in a file called \"~/TODO\", and if I type
-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.
+ M-1 M-j
-shell
-pwd
-cd /tmp/
-pwd
+then I \"jump\" to \"~/TODO\" - the effect is the same as running this:
+ (find-fline \"~/TODO\")
+Note that `M-1 M-j' can be typed as:
+ hold the meta key,
+ type 1,
+ type j,
+ release the meta key.
-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'.
+instead of:
+ hold the meta key,
+ type 1,
+ release the meta key,
+ hold the meta key,
+ type j,
+ release the meta key;
+There is no need to release and press again the meta key between
+the `1' and the `j'.
-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)))
+Internally, what happens when you type `M-1 M-j' is this:
-;; (find-eepitch-intro)
+ `M-j' is bound to `eejump',
+ `M-1 M-j' runs `eejump' with argument 1, i.e., (eejump 1)
+ (eejump 1) runs (eejump-1)
+ (eejump-1) has been defined with:
-;; (find-pytutnode "Methods of File Objects")
+ (defun eejump-1 () (find-fline \"~/TODO\"))
+So `M-1 M-j' runs the one-liner `(find-fline \"~/TODO\")',
+`M-5 M-j' runs the one-liner `(find-eev-quick-intro)',
+and so on.
-;;; _ _
-;;; __ ___ __ __ _ _ __ (_)_ __ | |_ _ __ ___
-;;; \ \ /\ / / '__/ _` | '_ \ _____| | '_ \| __| '__/ _ \
-;;; \ V V /| | | (_| | |_) |_____| | | | | |_| | | (_) |
-;;; \_/\_/ |_| \__,_| .__/ |_|_| |_|\__|_| \___/
-;;; |_|
-;;
-;; (find-intro-links "wrap")
-;; �find-wrap-intro� (to ".find-wrap-intro")
+7.2. The list of eejump targets
+-------------------------------
+If you type `M-j' without a prefix argument then it runs
+`(find-eejumps)', that displays all the current eejump targets as
+defuns, one in each line. Try it:
-(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.
+ (eek \"M-j\")
+ (find-eejumps)
+You will see that two of those entries are:
+ (defun eejump-1 () (find-fline \"~/TODO\"))
+ (defun eejump-5 () (find-eev-quick-intro))
-For an introduction to the ideas here, see:
- (find-eev-quick-intro \"6. Controlling shell-like programs\")
+7.3. Defining eejump targets
+----------------------------
+We can define new eejump targets, or overwrite the current ones, by
+just running `defun's to define functions with names starting with
+`eejump-'. Try:
-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:
+ (defun eejump-9 () (find-eev-quick-intro \"7.2.\"))
+ (defun eejump-9 () (find-eev-quick-intro \"7.3.\"))
+ (fmakunbound 'eejump-9)
+ (find-eejumps)
- 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.
+Note that if you type `M-J' (i.e., meta-uppercase-j,
+`eewrap-eejump') on the line below then it will be converted into
+the first \"(defun eejump- ...)\" above:
-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.
+ 9 (find-eev-quick-intro \"7.2.\")
-Note that the wrapping commands are all bound to key sequences of
-the form meta-SHIFT-letter - don't forget the shift!!!
+An advanced feature: if you type `M-J' on a line that starts with
+something that is not a number, you get a defun for a \"command
+with a very short name\" like the ones that are described in the
+next section. Try it now:
+ (eek \"<down> M-J\")
+ e (find-fline \"/tmp/foo.tex\")
-<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>):
+7.2. Commands with very short names
+-----------------------------------
+Let's start with an example. If we are editing a LaTeX file, say
+\"/tmp/foo.tex\", then it is convenient to have quick ways to:
-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
+ c) compile \"foo.tex\" into a \"foo.pdf\",
+ d) display the resulting \"foo.pdf\",
+ e) jump to \"foo.tex\" from anywhere to edit it.
-python
-square = lambda x: x*x
-square(5)
+If our \"/tmp/foo.tex\" starts with these lines
+ % (defun c () (interactive) (find-sh \"cd /tmp/; pdflatex foo.tex\"))
+ % (defun d () (interactive) (find-xpdfpage \"/tmp/foo.pdf\"))
+ % (defun e () (interactive) (find-fline \"/tmp/foo.tex\"))
+and we execute these defuns, then from that point on `M-x c', `M-x d'
+and `M-x e' will do \"compile\", \"display\" and \"edit\" on \"foo.tex\", as
+described above.
-<M-F>: hyperlink to a file or a directory
-=========================================
-If you type <M-F> on the lines below,
+For more on `M-x', and on why the defuns above need the
+\"(interactive)\", see:
-/etc/
-/tmp/
-~/
-~/.emacs
+ (find-node \"(emacs)M-x\")
+ (find-node \"(emacs)Commands\")
+ (find-node \"(elisp)Defining Commands\")
-you get hyperlinks like these:
-# (find-fline \"/etc/\")
-# (find-fline \"/tmp/\")
-# (find-fline \"~/\")
-# (find-fline \"~/.emacs\")
+7.3. `find-latex-links'
+-----------------------
+The easiest way to put the three defuns of the last section in
+the header of a LaTeX file is with:
-<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-latex-links \"/tmp/foo\")
- # (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\")
+`find-latex-links' is just one of several template functions that
+generate commands with very short names. Here's how to use it -
+the other ones are similar.
-Try it here:
+ 1) Run `M-x find-latex-links'. You will get a buffer whose top
+ line is:
-dict smop
-dict 'minor detail'
+ # (find-latex-links \"{stem}\")
-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\".
+ 2) Edit that, and change the \"{stem}\" to \"/tmp/foo\".
- # (find-sh \"dict smop\")
- # (find-sh \"dict 'minor detail'\")
+ 3) Execute that top line, which is now:
+ # (find-latex-links \"/tmp/foo\")
+ You should get:
-<M-M>: hyperlink to a manpage
-=============================
-Try <M-M> here:
+ _____________________________________________________________________
+ |# (find-latex-links \"/tmp/foo\") |
+ |# (find-eev-quick-intro \"`find-latex-links'\") |
+ |# (ee-copy-rest 1 '(find-fline \"/tmp/foo.tex\")) |
+ | |
+ |% (defun c () (interactive) (find-sh \"pdflatex foo.tex\")) |
+ |% (defun d () (interactive) (find-pdf-page \"/tmp/foo.pdf\")) |
+ |% (defun e () (interactive) (find-fline \"/tmp/foo.tex\")) |
+ |% |
+ |\\documentclass{article} |
+ |\\begin{document} |
+ | |
+ |\\end{document} |
+ | |
+ | |
+ | -:**- *Elisp hyperlinks* All L1 (Fundamental) |
+ |_____________________________________________________________________|
-1 tac
+ 4) Execute the line with the \"(ee-copy-rest ...)\". You should get this -
+ the window on the right is visiting the file \"/tmp/foo.tex\":
+ ______________________________________________________________________
+ |# (find-latex-links \"/tmp/foo\") | |
+ |# (find-eev-quick-intro \"`find-lat| |
+ |# (ee-copy-rest 1 '(find-fline \"/t| |
+ | | |
+ |% (defun c () (interactive) (find-| |
+ |% (defun d () (interactive) (find-| |
+ |% (defun e () (interactive) (find-| |
+ |% | |
+ |\\documentclass{article} | |
+ |\\begin{document} | |
+ | | |
+ |\\end{document} | |
+ | | |
+ | | |
+ | -:**- *Elisp hyperlinks* All L| -:**- foo.tex All L9 |
+ |_(Copied 8 lines to the kill ring - use C-y to paste)________________|
-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/
+ 5) Go to the window on the right and type `M-y'. You should get this,
- (eek \"2*<down> M-D <down> ;;; Test eewrap-debian\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-debian\")
-bash
+ ______________________________________________________________________
+ |# (find-latex-links \"/tmp/foo\") |% (defun c () (interactive) (find-|
+ |# (find-eev-quick-intro \"`find-lat|% (defun d () (interactive) (find-|
+ |# (ee-copy-rest 1 '(find-fline \"/t|% (defun e () (interactive) (find-|
+ | |% |
+ |% (defun c () (interactive) (find-|\\documentclass{article} |
+ |% (defun d () (interactive) (find-|\\begin{document} |
+ |% (defun e () (interactive) (find-| |
+ |% |\\end{document} |
+ |\\documentclass{article} | |
+ |\\begin{document} | |
+ | | |
+ |\\end{document} | |
+ | | |
+ | | |
+ | -:**- *Elisp hyperlinks* All L| -:**- foo.tex All L9 |
+ |_____________________________________________________________________|
- (eek \"2*<down> M-F <down> ;;; Test eewrap-find-fline\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-find-fline\")
-/tmp/foobar/
+ and you can now save the file foo.tex (hint: use `C-x C-s'!),
+ execute the three defuns for `c', `d', and `e', and jump to
+ \"/tmp/foo.tex\" from anywhere with `M-x e'.
- (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/
+8. Anchors
+==========
- (eek \"2*<down> M-S <down> ;;; Test eewrap-sh\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-sh\")
-seq 1 20
+8.1. Introduction: `to'
+-----------------------
+A hyperlink like
- (eek \"2*<down> M-T <down> ;;; Test eewrap-eepitch\")
- Source: (find-eev \"eepitch.el\" \"eewrap-eepitch\")
-python
+ (to \"foo\")
- (eek \"2*<down> M-V <down> ;;; Test eewrap-audiovideo\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-audiovideo\")
-slimetutorial /tmp/slime-tutorial.mp4
+jumps to the first occurrence of the string \"�foo�\" in the
+current buffer. The function that wraps a string in `��'s is
+called `ee-format-as-anchor', and the sexp `(to \"foo\")'
+is equivalent the second sexp below:
- (eek \"2*<down> M-Z <down> ;;; Test eewrap-zsh\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-zsh\")
-echo $SHELL
+ (ee-format-as-anchor \"foo\")
+ (ee-goto-position (ee-format-as-anchor \"foo\"))
- (eek \"2*<down> <<eewrap-eewrap>> <down> ;;; Test eewrap-eewrap\")
- Source: (find-eev \"eev-wrap.el\" \"eewrap-eewrap\")
-U user-defined a b c
+We will call strings in `��'s _anchors_, and we will say
+that `(to \"foo\")' jumps \"to the anchor `foo'\". The string
+inside a `��'s is called a _tag_.
+In a situation like this,
+ �one� (to \"two\")
+ �two� (to \"three\")
+ �three� (to \"four\")
+ �four� (to \"one\")
+we have four anchors, and typing `M-e' at the line with the
+anchor \"one\" takes us to the line with the anchor \"two\",
+typing `M-e' at the line with the anchor \"two\" takes us to the
+line with the anchor \"three\", typing `M-e' again takes us to
+the line with the anchor \"four\", and typing `M-e' again takes
+us back to the line with the anchor \"one\". In a situation like
+this we say that the anchors \"one\", \"two\", \"three\", and
+\"four\" _point to one another_.
-Wrapping functions generate hyperlinks
-======================================
-...this is a slogan - a huge idea, in a very shortened form. In its
-full form, that would be:
+In a case like this,
- (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:
+ �.five� (to \"five\")
+ �five� (to \".five\")
- (find-links-intro \"Elisp hyperlinks buffers\")
+where the names of two anchors pointing to one another differ by
+an initial dot, we will say that the anchor \".five\" is the
+\"index anchor\", and the anchor \"five\" 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:
-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.
+ (find-eev \"eev-intro.el\" \".find-eev-intro\")
+8.2. Creating anchors by hand
+-----------------------------
+One way to type the chars `�' and `�' is with `C-x 8 <' and
+`C-x 8 >'. Try:
-# Local Variables:
-# coding: raw-text-unix
-# ee-anchor-format: \"�%s�\"
-# End:
-" rest)))
+ (eek \"RET C-x 8 < t a g C-x 8 >\")
-;; (find-wrap-intro)
+8.3. Creating index/section anchor pairs
+----------------------------------------
+Eev has several commands that transform the text in the current
+line into something more complex. They are all called
+`eewrap-(something)', and they are bound to
+meta-uppercase-letters. The simplest examples are `M-F', `M-S'
+and `M-M', that just \"wrap the text in the current line into an
+elisp hyperlink\" by adding a prefix and a suffix; if you run
+`M-F', `M-S' and `M-M' in the following lines
-;;; _ _ _
-;;; | (_)_ __ | | _____
-;;; | | | '_ \| |/ / __|
-;;; | | | | | | <\__ \
-;;; |_|_|_| |_|_|\_\___/
-;;;
-;; (find-intro-links "links")
-;; �find-links-intro� (to ".find-links-intro")
+/tmp/
+ls /tmp/
+ls
-(defun find-links-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-links-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-links-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-links-intro\")
-More intros: (find-eev-quick-intro)
- (find-eval-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
+they become this:
+# (find-fline \"/tmp/\")
+# (find-sh \"ls /tmp/\")
+# (find-man \"ls\")
+You can also try them by running the `eek' sexps below,
+\(eek \"<down> M-F\")
+/tmp/
-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:
+\(eek \"<down> M-S\")
+ls /tmp/
- (find-fline \"/tmp/\")
- (find-node \"(emacs)Lisp Eval\")
- (find-efunctiondescr 'find-file)
- (find-efunction 'find-file)
- (find-man \"cat\")
+\(eek \"<down> M-M\")
+ls
-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.
+HINT: sometimes the eewrap commands don't do exactly what we
+want, so learn how to use the \"undo\" command of Emacs. See:
-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:
+ (find-emacs-keys-intro \"5. Undoing\")
- (find-sh \"<code that deletes all your e-mails>\")
+The command `eewrap-anchor' (bound to `M-A') is similar to those
+above, but it parses the current line in a more complex way -
+everything between \"<>\" is the \"anchor\" and everything before
+the \"<\" is the \"comment prefix\" - and it converts the current
+line into two lines with `to's, each one pointing to the other
+one. For example, `M-A' in the line below
-but it is not possible to hide that action behind an
-innocent-looking button that says \"click for a larger image\".
+ # <first-test>
-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.
+yields this:
+ # �.first-test� (to \"first-test\")
+ # �first-test� (to \".first-test\")
+The line with the anchor \"�.first-test�\" is intended to be
+moved - by hand, with cut and paste - to the index section at the
+beginning of the file, as explained here:
+ (find-escripts-intro)
-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.
-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:
- \"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\")
+8.4. Creating e-script blocks
+-----------------------------
+The key `M-B' (`eewrap-escript-block') is a variant of `M-A' that
+converts the current line into seven (!) lines instead of two. If
+we type `M-B' on the line below
-`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:
+ second-test Long description
- ___________________________________________________________
- |# (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)--|
- |___________________________________________________________|
+it becomes this - the header of an \"e-script block\":
-What is that?...
+#####
+#
+# Long description
+# 2018may22
+#
+#####
+# �.second-test� (to \"second-test\")
+# �second-test� (to \".second-test\")
+where again the line with the anchor \"�.second-test�\" is
+intended to be moved to the index section at the beginning of the
+file. The use of these \"e-script blocks\" is explained bere:
+ (find-escripts-intro)
-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;
+8.5. Hyperlinks to anchors in other files
+-----------------------------------------
+`find-anchor' is like `find-fline', but it interprets the first
+argument after the file in a special way if it is present. These
+hyperlinks are all equivalent:
- 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,
+ (find-anchor \"~/eev2/eev-blinks.el\" \"find-wottb\")
+ (find-anchor \"~/eev2/eev-blinks.el\" (ee-format-as-anchor \"find-wottb\"))
+ (find-fline \"~/eev2/eev-blinks.el\" \"�find-wottb�\")
- (find-eval-intro \"Refining hyperlinks\")
+You can use this - or the shorter hyperlinks to anchors in
+section 9.3 - to point to anchors or to e-script blocks in your
+files.
- 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.
- 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-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:
+9. Shorter hyperlinks
+=====================
+See also: (find-code-c-d-intro)
- 6) The first line (the \"top sexp\") of an M-h buffer
- regenerates the buffer. And, at last,
+9.1. `code-c-d'
+---------------
+Sexps like
- 7) The elisp hyperlinks in M-h buffers are prefixed by the
- string in `ee-hyperlink-prefix'.
+ (find-eevfile \"\")
+ (find-eevfile \"eev-blinks.el\")
+ (find-eevfile \"eev-blinks.el\" \"�find-sh�\")
+ (find-udfile \"\")
+ (find-udfile \"lua5.1-doc/\")
+ (find-udfile \"lua5.1-doc/test/\")
+ (find-udfile \"lua5.1-doc/test/fib.lua\")
+ (find-udfile \"lua5.1-doc/test/fib.lua\" \"function fib(n)\")
+work as abbreviations for
+ (find-fline \"~/eev-current/\")
+ (find-fline \"~/eev-current/eev-blinks.el\")
+ (find-fline \"~/eev-current/eev-blinks.el\" \"�find-sh�\")
+ (find-fline \"/usr/share/doc/\")
+ (find-fline \"/usr/share/doc/lua5.1-doc/\")
+ (find-fline \"/usr/share/doc/lua5.1-doc/test/\")
+ (find-fline \"/usr/share/doc/lua5.1-doc/test/fib.lua\")
+ (find-fline \"/usr/share/doc/lua5.1-doc/test/fib.lua\" \"function fib(n)\")
-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_.
+They are \"mass-produced\", in the following sense. When we run this,
-`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,
+ (code-c-d \"ud\" \"/usr/share/doc/\")
- ____________________________________________________________
- |# See: |
- |# (find-links-intro \"`find-here-links'\") |
- |# (find-efunctiondescr 'eev-mode \"M-h M-h\") |
- | |
- |# (find-links-intro) |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
- |____________________________________________________________|
+the function `code-c-d' produces a big string using a template, and
+evaluates that big string; the \"{c}\"s in the template are replaced by
+the argument \"ud\" - called the \"code\" - and the \"{d}\"s in the template
+are replaced by \"/usr/share/doc/\" - called the \"directory\". If we add
+a \"find-\" before the `code-c-d', like this,
-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-code-c-d \"ud\" \"/usr/share/doc/\")
- (find-links-intro)
+we get a hyperlink to the code that `(code-c-d \"ud\" \"/usr/share/doc/\")'
+would execute - i.e., to the result of substiting the \"{c}\"s and
+\"{d}\"s in the template. This is useful for understanding how
+`code-c-d' works; each call to `code-c-d' defines lots of functions,
+some of them easier to explain, some harder. This, for example,
-can be \"refined\" to, for example,
+ (find-eevgrep \"grep --color -nH -e '(code-c-d ' *.el\")
- (find-links-intro \"which contains a 3-line header\")
+greps for all calls to \"code-c-d\" in the source of eev.
-using the tricks described in these sections:
+By default, eev runs these `code-c-d's:
- (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'\")
+ (find-eevfile \"eev-code.el\" \"code-c-d \\\"e\\\"\")
-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\".
+You can add many more of them to your .emacs file.
-`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:
+An introduction to the ideas, details, innards and technicalities of
+`code-c-d' can be found here:
- (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-code-c-d-intro)
- (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))
- (find-here-links-test '(find-man \"1 cat\"))
- [^ oops, this test doesn't work on multi-window settings...]
+9.2. Extra arguments to `code-c-d'
+----------------------------------
+If you compare the buffers generated by
-Each one of them tests a different case of `find-here-links',
-creating a window setup like this:
+ (find-code-c-d \"CODE\" \"/DIR/\")
+ (find-code-c-d \"CODE\" \"/DIR/\" :info \"INFO\")
+ (find-code-c-d-rest \"CODE\" \"/DIR/\" :info \"INFO\")
- ______________________________________
- | | |
- | | target of |
- | | sexp |
- | this |______________________|
- | intro | |
- | | result of running |
- | | find-here-links on |
- | | [target of sexp] |
- |_______________|______________________|
+you will see that the `:info \"INFO\"' part adds some code to the end of
+the generated string, and that the `find-code-c-d-rest' shows only
+this extra code.
-The cursor is kept at the left window (\"this intro\"), so you
-can compare the different cases using just <up>, <down>, and M-e.
+The most important extra arguments to `code-c-d' are:
+ 1) :info \"name-of-an-info-manual\"
+ 2) :gz
+ 3) :anchor
+If the first extra argument is a string then `ee-code-c-d' adds an
+`:info' before it, so these generate the same code:
+ (find-code-c-d \"CODE\" \"/DIR/\" \"INFO\")
+ (find-code-c-d \"CODE\" \"/DIR/\" :info \"INFO\")
-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]:
+The eev source has this (in the file \"eev-code.el\"),
- ______________________________________
- | | |
- | | something |
- | ==> interesting |
- | e-script |_________||___________|
- | | \\/ |
- | | result of running |
- | <== find-here-links on |
- | | [sthing intrstng] |
- |_______________|______________________|
+ (code-c-d \"e\" ee-emacs-lisp-directory :info \"emacs\" :gz)
+ (code-c-d \"eev\" ee-eev-source-directory :anchor)
-and this series of steps:
+and that code
- 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):
-
- 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) makes (find-enode \"\")
+ work as an abbreviation for (find-node \"(emacs)\")
-\[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]
+ 2) makes (find-efile \"files.el\")
+ run (find-efile \"files.el.gz\")
+ if the file \"files.el\" is not found,
+ 3) makes (find-eev \"eev-blinks.el\" \"find-wottb\")
+ run: (find-eevfile \"eev-blinks.el\" \"�find-wottb�\")
+ or actually: (find-anchor (ee-eevfile \"eev-blinks.el\") \"find-wottb\")
+Calls to `find-eev' are \"short hyperlinks to anchors\":
+ (find-eev \"eev-blinks.el\" \"find-wottb\")
+ (find-eev \"eev-blinks.el\" \"find-wottb\" \"defun find-wottb-call\")
-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?
+For the technical details of the implementation, see here:
-We can start by dividing the hyperlink functions into a fixed set
-of \"basic\" ones and an unbounded set of \"non-basic\" ones. In
-the buffer generated by
+ (find-code-c-d-intro \"Extra arguments to `code-c-d'\")
- (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))
+9.3. Hyperlinks to PDF files
+----------------------------
+If you run this e-script
-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,
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+# https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
+mkdir -p $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/
+cd $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/
+wget -nc https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
- (find-enode \"Command Index\" \"* find-file:\")
- (find-elnode \"Index\" \"* find-file:\")
+you will download a local copy of J.M. Coetzee's \"The Lives of
+Animals\" into this directory:
-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-fline \"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/\")
+ (find-fline \"~/snarf/https/tannerlectures.utah.edu/_documents/a-to-z/c/\")
- (find-code-c-d-intro)
- (find-pdf-like-intro)
- (find-audiovideo-intro)
+The full idea behind these \"local copies\" is explained here:
-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-psne-intro)
- (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\")
+If you have xpdf installed then the second sexp here,
-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.
+ (setq l-o-a
\"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf\")
+ (find-pdf-page l-o-a)
-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.
+should work as a \"hyperlink to the PDF\": it calls xpdf as
+external program to open that PDF file. The main keys of xpdf
+are:
-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.
+ q quit xpdf
+ alt-f toggle full-screen; use twice to fit document to page
+ PageDown scroll down/go to next page
+ PageUp scroll up/go to previous page
+ 0 set zoom to 125%
+ + zoom in one step
+ - zoom out out step
+ arrows scroll within the current page
+Also, if you have the program pdftotext installed (hint: apt-get
+install poppler-utils!) then this
+ (find-pdf-text l-o-a)
+should work as a \"hyperlink to the text of the PDF\".
-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.
+You can use these two sexps
-If you run `M-x ee-hyperlink-prefix' you should get a buffer like
-this:
+ (ee-find-pdf-text l-o-a)
+ (ee-find-pdf-page l-o-a)
- ___________________________________________________________
- |# (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)--|
- |___________________________________________________________|
+to see exactly how the `find-pdf-page' and the `find-pdf-text'
+sexps above invoke xpdf and pdftotext; note that `find-pdf-page'
+uses `find-bgprocess' and `find-pdf-text' uses `find-sh'.
-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:
+The functions above accept extra arguments, that are interpreted
+as a page number and as strings to look for, but it's easier to
+discuss them using shorter hyperlinks.
- (progn (setq ee-hyperlink-prefix \"# \") (ee-hyperlink-prefix))
- (progn (setq ee-hyperlink-prefix \"% \") (ee-hyperlink-prefix))
+9.4. Shorter hyperlinks to PDF files
+------------------------------------
+If you run these sexps
-8. The first line regenerates the buffer
-========================================
-\[To do: explain this convention with examples; explain the
-conventions for the \"variants of the first line\"\]
+ (code-pdf-page \"livesofanimals\" l-o-a)
+ (code-pdf-text \"livesofanimals\" l-o-a -110)
- (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\")
+then these hyperlinks should work:
+ (find-livesofanimalspage (+ -110 127) \"wrong thoughts\")
+ (find-livesofanimalstext (+ -110 127) \"wrong thoughts\")
+ (find-livesofanimalspage (+ -110 132) \"into the place of their victims\")
+ (find-livesofanimalstext (+ -110 132) \"into the place of their victims\")
+ (find-livesofanimalspage (+ -110 134) \"woke up haggard in the mornings\")
+ (find-livesofanimalstext (+ -110 134) \"woke up haggard in the mornings\")
+ (find-livesofanimalspage (+ -110 143) \"Babies have no self-consciousness\")
+ (find-livesofanimalstext (+ -110 143) \"Babies have no self-consciousness\")
+ (find-livesofanimalspage (+ -110 145) \"squirrel doing its thinking\")
+ (find-livesofanimalstext (+ -110 145) \"squirrel doing its thinking\")
+ (find-livesofanimalspage (+ -110 147) \"Rilke's panther\")
+ (find-livesofanimalstext (+ -110 147) \"Rilke's panther\")
+ (find-livesofanimalspage (+ -110 162) \"a grasp of the meaning\")
+ (find-livesofanimalstext (+ -110 162) \"a grasp of the meaning\")
+ (find-livesofanimalspage (+ -110 164) \"last common ground\")
+ (find-livesofanimalstext (+ -110 164) \"last common ground\")
+[To do: explain them]
-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 -
-\[To do: write this\]
- (find-efunctiondescr 'eev-mode)
- (find-efunctiondescr 'eev-mode \"M-h f\")
- (eek \"M-h M-i\")
+\(To be continued...)
+") pos-spec-list)))
- (find-enode \"Lisp Eval\")
- (progn (find-enode \"Lisp Eval\") (eek \"M-h M-i\"))
+;; end of defun
- (eek \"M-h f ;; find-file-links\")
- (eek \"M-h M-b ;; find-ebuffer-links\")
+;; (find-eev-quick-intro)
- 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 \"M-h M-i\")
- you should get something like this:
- ___________________________________________________________
- |# (find-einfo-links \"links\") |
- | |
- |[No \"*info*\" buffer] |
- | |
- |# (find-links-intro) |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
- |___________________________________________________________|
+;;; _
+;;; ___ _ __ ___ __ _ ___ ___ | | _____ _ _ ___
+;;; / _ \ '_ ` _ \ / _` |/ __/ __|_____| |/ / _ \ | | / __|
+;;; | __/ | | | | | (_| | (__\__ \_____| < __/ |_| \__ \
+;;; \___|_| |_| |_|\__,_|\___|___/ |_|\_\___|\__, |___/
+;;; |___/
+;;
+;; �find-emacs-keys-intro� (to ".find-emacs-keys-intro")
+;; (find-intro-links "emacs-keys")
+(defun find-emacs-keys-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-emacs-keys-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-emacs-keys-intro)
+Source code: (find-efunction 'find-emacs-keys-intro)
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
+The quickest way to open or recreate this is with `M-2 M-j'.
-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
+1. Basic keys (eev)
+===================
+The most basic keys of eev are:
+ M-e - to follow a hyperlink. Mnemonic: \"(e)valuate\"/\"(e)xecute\".
+ See: (find-eev-quick-intro \"2. Evaluating Lisp\")
+ (find-eev-quick-intro \"3. Elisp hyperlinks\")
+ M-k - to go back. Mnemonic: \"(k)ill buffer\".
+ See: (find-eev-quick-intro \"3. Elisp hyperlinks\" \"M-k\")
+ M-j - to jump to certain predefined places - in particular,
+ `M-j' takes you to the list of jump targets.
+ `M-2 M-j' takes you to this help page.
+ `M-5 M-j' takes you to: (find-eev-quick-intro)
+ <f8> - See: (find-eev-quick-intro \"6. Controlling shell-like programs\")
+ M-T - See: (find-eev-quick-intro \"6.3. Creating eepitch blocks: `M-T'\")
- (find-eev-update-links)
+The keys for creating \"hyperlinks to here\" and refining them are:
+ M-h M-h - `find-here-links'. See: (find-eev-quick-intro \"`M-h M-h'\")
+ M-h M-2 - `ee-duplicate-this-line'. See: (find-eval-intro \"M-h M-2\")
+ M-h M-y - `ee-yank-pos-spec'. See: (find-eval-intro \"M-h M-y\")
-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:
- ____________________________________________________________
- |# (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)---|
- |____________________________________________________________|
+2. Key sequences and how to abort them
+======================================
+See: (find-enode \"Keys\" \"key sequence\")
+ (find-enode \"User Input\" \"`Control-a'\" \"usually written `C-a'\")
+ (find-enode \"User Input\" \"<META> key\")
+ (find-enode \"Completion\" \"<TAB>\")
-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:
+<ESC> <ESC> <ESC> (find-enode \"Quitting\")
+C-g keyboard-quit (find-enode \"Quitting\" \"`C-g'\")
+M-x execute-extended-command (find-enode \"M-x\" \"Running Commands by
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.
+More about the minibuffer: (find-enode \"Minibuffer\")
+More about TAB - for completion: (find-enode \"Completion\")
+ for indentation: (find-enode \"Indentation\")
+ in programming modes: (find-enode \"Basic Indent\")
+More about modes: (find-enode \"Major Modes\")
+ (find-enode \"Minor Modes\")
+ (find-enode \"Dired\")
-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. Cutting & pasting
+====================
+The \"region\" where cut & copy operate is always what is between
+the \"point\" and the \"mark\":
- 3) it runs CODE to open its target in a window at the right
- side (like as with `M-3 M-e')
+ (find-enode \"Point\")
+ (find-enode \"Mark\")
-\[To do: add examples - including examples that let us create Lua
-scripts etc\]
+You can do cut, copy and paste by using the icons in the toolbar
+or by using the menu bar (the relevant options are under
+\"Edit\"), but the keys are worth learning:
+ C-SPC -- set-mark-command (find-enode \"Setting Mark\")
+ C-x C-x -- exchange-point-and-mark (find-enode \"Setting Mark\" \"C-x
C-x\")
+ C-w -- kill-region (cut) (find-enode \"Other Kill Commands\")
+ M-w -- kill-ring-save (copy) (find-enode \"Kill Ring\")
+ C-y -- yank (paste) (find-enode \"Kill Ring\")
-" rest)))
+See: (find-enode \"Tool Bars\")
+ (find-enode \"Menu Bar\")
-;; (find-links-intro)
-;; (find-eevfile "eev-template.el" "defun find-efunction-links")
+4. Moving point
+===============
+C-a -- beginning-of-line (find-enode \"Moving Point\")
+C-e -- end-of-line (find-enode \"Moving Point\")
+M-< -- beginning-of-buffer (find-enode \"Moving Point\")
+M-> -- end-of-buffer (find-enode \"Moving Point\")
+5. Undoing
+==========
+C-/ -- undo (find-enode \"Basic Undo\")
+C-_ -- undo (find-enode \"Basic Undo\")
+ (find-enode \"Undo\")
-;;; _ _ _ _
-;;; ___ ___ __| | ___ ___ __| | (_)_ __ | |_ _ __ ___
-;;; / __/ _ \ / _` |/ _ \_____ / __|____ / _` |_____| | '_ \| __| '__/ _ \
-;;; | (_| (_) | (_| | __/_____| (_|_____| (_| |_____| | | | | |_| | | (_) |
-;;; \___\___/ \__,_|\___| \___| \__,_| |_|_| |_|\__|_| \___/
-;;;
-;; �find-code-c-d-intro� (to ".find-code-c-d-intro")
-(defun find-code-c-d-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-code-c-d-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-code-c-d-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-code-c-d-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.
+6. Windows
+==========
+See: (find-enode \"Windows\")
+ (find-enode \"Frames\")
+C-x o -- other-window (find-enode \"Other Window\")
+C-x 0 -- delete-window (find-enode \"Change Window\")
+C-x 1 -- delete-other-windows (\"1 window\") (find-enode \"Change
Window\")
+C-x 2 -- split-window-vertically (Above/Below) (find-enode \"Split Window\")
+C-x 3 -- split-window-horizontally (L|R) (find-enode \"Split Window\")
-This intro has been mostly superseded by:
-(find-eev-quick-intro \"9.1. `code-c-d'\")
+7. Files and buffers
+====================
+C-x C-f -- find-file (find-enode \"Visiting\")
+C-x C-s -- save-buffer (find-enode \"Saving\")
+C-x C-c -- save-buffers-kill-emacs (find-enode \"Saving\")
+C-x b -- switch-to-buffer (find-enode \"Select Buffer\")
+C-x k -- kill-buffer (find-enode \"Kill Buffer\")
+ (find-enode \"Dired\")
-Avoiding full path names
-========================
-Suppose that you have downloaded (\"psne\"-ed) this URL,
+8. Search and replace
+=====================
+C-s -- isearch-forward (find-enode \"Incremental Search\")
+C-r -- isearch-backward (find-enode \"Incremental Search\")
+M-C-s -- isearch-forward-regexp (find-enode \"Regexp Search\")
+M-C-r -- isearch-backward-regexp (find-enode \"Regexp Search\")
+M-% -- query-replace (find-enode \"Replace\")
- http://www.lua.org/ftp/lua-5.1.4.tar.gz
-with `M-x brep' - see:
- (find-psne-intro)
+9. Macros
+=========
+C-x ( -- start-kbd-macro (find-enode \"Keyboard Macros\")
+C-x ) -- end-kbd-macro (find-enode \"Keyboard Macros\")
+C-x e -- call-last-kbd-macro (find-enode \"Keyboard Macros\")
-and you unpacked that tarball into the directory ~/usrc/ (I
-prefer to use that instead of /usr/src/) with:
- tar -C ~/usrc/ -xvzf $S/http/www.lua.org/ftp/lua-5.1.4.tar.gz
-Now you can access some directories and files of the unpacked
-tarball with:
+10. Other keys (Emacs)
+======================
+M-q -- fill-paragraph (find-enode \"Fill Commands\")
+C-x r <SPC> <char> -- point-to-register (find-enode \"Position
Registers\")
+C-x r j <char> -- jump-to-register (find-enode \"Position
Registers\")
- (find-fline \"~/usrc/lua-5.1.4/\")
- (find-fline \"~/usrc/lua-5.1.4/src/\")
- (find-fline \"~/usrc/lua-5.1.4/src/lstrlib.c\")
- (find-fline \"~/usrc/lua-5.1.4/test/\")
- (find-fline \"~/usrc/lua-5.1.4/test/README\")
- (find-fline \"~/usrc/lua-5.1.4/doc/\")
- (find-w3m \"~/usrc/lua-5.1.4/doc/contents.html\")
-but it's a bit clumsy to have to use the \"~/usrc/lua-5.1.4/\"
-every time, so eev provides a nice way to define shorthands. We
-want to be able to write just this instead of the sexps above,
- (find-lua51file \"\")
- (find-lua51file \"src/\")
- (find-lua51file \"src/lstrlib.c\")
- (find-lua51file \"test/\")
- (find-lua51file \"test/README\")
- (find-lua51file \"doc/\")
- (find-lua51w3m \"doc/contents.html\")
+11. Other keys (eev)
+====================
+M-F -- eewrap-find-fline (find-eev-quick-intro \"`M-F'\")
+M-M -- eewrap-man (find-eev-quick-intro \"`M-M'\")
+M-S -- eewrap-sh (find-eev-quick-intro \"`M-S'\")
+M-A -- eewrap-anchor (find-eev-quick-intro \"`M-A'\")
+M-B -- eewrap-escript-block (find-eev-quick-intro \"`M-B'\")
+" pos-spec-list)))
-and here the directory \"~/usrc/lua-5.1.4/\" became a mnemonic
-\"lua51\" in the middle of the names of some functions.
+;; (find-emacs-keys-intro)
-We will call these sexps with \"lua51\" \"shorter hyperlinks\".
-Shorter hyperlinks
-==================
-How can we generate the definitions for `find-lua51file' and
-`find-lua51w3m' from just the strings \"lua51\" and
-\"~/usrc/lua-5.1.4/\"? Try this:
+;;; _ _ _ _
+;;; (_)_ __ ___| |_ __ _| | |
+;;; | | '_ \/ __| __/ _` | | |
+;;; | | | | \__ \ || (_| | | |
+;;; |_|_| |_|___/\__\__,_|_|_|
+;;;
- (find-code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")
+;; �find-eev-install-intro� (to ".find-eev-install-intro")
+;; (find-intro-links "eev-install")
-you will get a temporary buffer with a lot of Lisp code -
-including a definition for `find-lua51file' and another one for
-`find-lua51w3m'. That Lisp code has not been executed yet; the
-function `find-code-c-d' is just for debugging, and we can regard
-it as a hyperlink to the code that this sexp would execute:
+(defun find-eev-install-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-eev-install-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-eev-install-intro)
+Source code: (find-efunction 'find-eev-install-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.
- (code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")
-
-So, to define a family of functions including `find-lua51file'
-and `find-lua51w3m', for a given \"mnemonic\" - \"lua51\" in this
-case - and a given \"directory\" - \"~/usrc/lua-5.1.4/\" - we run
-this:
- (code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")
-which generates a block of Lisp code, as a string, and evaluates
-it. Note: the original (and rather confusing) terminology for the
-\"mnemonic\" was \"code\"; that's why the \"c\" in `code-c-d'.
+The installation instructions in
+ (find-eev-quick-intro \"1. Installing eev\")
+describe a way to install eev that uses the directory \"~/eev2/\" for
+elisp files and that creates a secript \"~/eev\" that starts Emacs,
+loads eev, and runs `(find-eev-quick-intro)'. Here we describe several
+ways to install eev in other places and how to change your .emacs to
+make it load eev at startup.
-Extra arguments to `code-c-d'
-=============================
-`code-c-d' supports extra arguments - for example, this works:
- (find-code-c-d \"el\" \"~/usrc/emacs/lisp/\" :info \"elisp\")
-Look at the end of the generated code and you will see that it
-has a definition for `find-elnode' - such that
+1. Running `(find-eev-install-links)'
+=====================================
+The shell commands in
- (find-elnode \"Constant Variables\")
+ (find-eev-quick-intro \"1. Installing eev\")
-is a shorthand (a \"shorter hyperlink\") for:
+can be obtained by running `find-eev-install-links' with these
+arguments:
- (find-node \"(elisp)Constant Variables\")
+ (find-eev-install-links \"~/eev2/\" \"~/eev\")
-What is important to understand here is how these definitions
-with extra arguments are structured - so that you will be able to
-understand the source code when you need to. Both `code-c-d' and
-`find-code-c-d' are defined with a `&rest' in their argument
-lists, like this (NOTE: do not execute these defuns!):
+Note that `(find-eev-install-links)' is somehow similar to this,
- (defun code-c-d (c d &rest rest) ...)
- (defun find-code-c-d (c d &rest rest) ...)
+ (find-eev-quick-intro \"7.3. `find-latex-links'\")
-and they both invoke `ee-code-c-d', which does all the template
-work and returns a big string; `ee-code-c-d' passes its `rest'
-argument to a recursive function called `ee-code-c-d-rest', and
-for each one of the suported keywords there is a corresponding
-function, also recursive; for `:info' it is called
-`ee-code-c-d-:info'. Their specifications are like this:
-
- (defun ee-code-c-d (c d &rest rest) ...)
- (defun ee-code-c-d-rest (rest) ...)
- (defun ee-code-c-d-:info (manual &rest rest) ...)
+and follows most of the same conventions.
-and one very non-obvious trick is used to make the code short.
-When `ee-code-c-d-rest' and `ee-code-c-d-:info' are run they can
-access the values the `c' and the `d' that were passed to
-`ee-code-c-d' (due to dynamic scoping), so `c' and `d' do not
-need to be passed down explicitly as arguments.
+If you want to install eev in a more permanent place the default
+way is to run `(find-eev-install-links)' with these arguments,
-Try:
+ (find-eev-install-links \"~/eev2/\" \"~/eev\" \"#\")
- (find-code-c-d \"CODE\" \"/DIR/\" :info \"INFO\")
+and execute its eepitch block.
-Other similar functions
+2. Changing your .emacs
=======================
-See: (find-brxxx-intro)
- (find-pdf-like-intro)
- (find-audiovideo-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)
-
-
+See:
+ (find-elnode \"Init File\" \".emacs\")
+ (find-elnode \"Init Examples\")
+ (find-elnode \"Init File Examples\")
+ (find-eev-install-links \"~/eev2/\" \"~/eev\" \"\" 2 \".emacs\")
-;;; _ _
-;;; _ __ ___ _ __ ___ (_)_ __ | |_ _ __ ___
-;;; | '_ \/ __| '_ \ / _ \_____| | '_ \| __| '__/ _ \
-;;; | |_) \__ \ | | | __/_____| | | | | |_| | | (_) |
-;;; | .__/|___/_| |_|\___| |_|_| |_|\__|_| \___/
-;;; |_|
-;;
-;; �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.
+3. Using the git repository
+===========================
+Eev has a git repository at:
+ https://github.com/edrx/eev.git
+All recent changes are being made at the \"UTF-8\" branch and I
+haven't learned yet how to make the master branch point to
+UTF-8... so if you clone the repository you'll have to do a
+\"checkout UTF-8\" the go to the most recent version.
-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
+Try 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
+rm -Rfv /tmp/eev2
+mkdir /tmp/eev2/
+cd /tmp/eev2/ && git clone https://github.com/edrx/eev.git .
+cd /tmp/eev2/
+git checkout UTF-8
+# (find-gitk \"/tmp/eev2/\")
+{
+ echo '#!/bin/sh'
+ echo 'cd /tmp/eev2/ && emacs -l eev-readme.el
--eval=\"(find-eev-quick-intro)\"'
+} > /tmp/eev
+chmod 755 /tmp/eev
- # (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
- # (find-w3m \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
+and run the script in /tmp/eev if you want to.
-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.
+Note the \"cd ... && git clone URL .\". This is needed because if
+we don't specify a directory after the URL in \"git clone\" then
+git will create a directory /tmp/eev/, and that would be
+incompatible with our convention of creating a script called
+\"eev\" (\"/tmp/eev\" in this case).
-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
+4. Eev as an ELPA package
+=========================
+I started to make an Emacs \"package\" for eev but I did not go
+very far. See:
-would run the `mkdir', the `cd', the `wget' and the `echo' above.
+ (find-enode \"Packages\")
+ (find-elnode \"Packaging\")
+ (find-efaqnode \"Packages that do not come with Emacs\")
-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.
+Help would be greatly appreciated!
-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\".
+" pos-spec-list)))
+;; (find-eev-install-intro)
+;; (find-eev "eev-tlinks.el" "find-eev-update-links")
+;; (find-eev "eev-tlinks.el" "find-eev-install-links")
+;; (find-eev-update-links)
-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.
+;;; _ _
+;;; ___ _____ __ (_)_ __ | |_ _ __ ___
+;;; / _ \/ _ \ \ / /____| | '_ \| __| '__/ _ \
+;;; | __/ __/\ V /_____| | | | | |_| | | (_) |
+;;; \___|\___| \_/ |_|_| |_|\__|_| \___/
+;;;
+;; This works as an index.
+;; (find-intro-links "eev")
+;; �find-eev-intro� (to ".find-eev-intro")
+(defun find-eev-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-eev-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-eev-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-eev-intro\")
+Main intros: (find-eev-quick-intro)
+ (find-emacs-keys-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+ (find-wrap-intro)
+ (find-eev-intro)
+Index to the source files: (find-eev \"eev-load.el\")
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
-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
+Here is a list of all the available sandbox-y tutorials that
+explain parts and concepts of eev, listed in (a kind of)
+recommended reading order:
- (find-bgprocess \"xterm\")
- (find-bgprocess \"gnome-terminal\")
- (find-bgprocess \"eterm\")
+ 0. (find-eev-quick-intro)
+ 1. (find-emacs-keys-intro)
+ 2. (find-eev-install-intro)
+ 3. (find-eev-intro)
+ 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)
+ 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)
-will then inherit that value. Try it:
+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
+these ideas pervasive.
- (getenv \"S\")
- (find-sh0 \"echo $S\")
+The last item above is an index of the video tutorials, with
+scripts for downloading local copies of them and links to
+important positions in the videos.
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-echo $S
+There are also these two, ahem, \"things\", that I use in
+workshops, but that are not very eev-specific:
-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.
+ A. (find-emacs-intro)
+ B. (find-defun-intro)
+ C. (find-eev-quick-intro)
-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
+To toggle eev-mode on and off, use `M-x eev-mode'.
-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.
+The keybindings
+===============
+`eev-mode' defines its own meanings for lots of meta-shift-letter
+key combinations - which are not normally used by Emacs - and,
+besides that, only for:
-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:
+ `M-e' (find-eval-intro \"`M-e'\")
+ `M-k' (find-eval-intro \"`M-k'\")
+ `M-j' (find-eejump-intro \"\\neejump\\n\")
+ `M-h' (find-links-intro \"Elisp hyperlinks buffers\")
+ `<f8>' (find-eepitch-intro \"The main key: <F8>\")
- http://www.gnu.org/software/emacs/emacs-paper.html
- (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
+For the full lists of keybindings, see:
-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:
+ (find-efunctiondescr 'eev-mode)
+ (find-eminormodekeymapdescr 'eev-mode)
+ (find-efunctiondescr 'eev-avadj-mode)
+ (find-eminormodekeymapdescr 'eev-avadj-mode)
+" rest)))
- \"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.
+;; (find-eev-intro)
-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-psne-intro)
+;;; _
+;;; _____ ____ _| |
+;;; / _ \ \ / / _` | |
+;;; | __/\ V / (_| | |
+;;; \___| \_/ \__,_|_|
+;;;
+;; �find-eval-intro� (to ".find-eval-intro")
+;; (find-intro-links "eval")
+;; (find-TH "eev-article" "hyperlinks")
+;; 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-brxxx-intro� (to ".find-brxxx-intro")
-(defun find-brxxx-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-brxxx-intro)*"))
+(defun find-eval-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-eval-intro)*"))
(apply 'find-estring "\
-\(Re)generate: (find-brxxx-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-brxxx-intro\")
+\(Re)generate: (find-eval-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-eval-intro\")
More intros: (find-eev-quick-intro)
- (find-eval-intro)
(find-eepitch-intro)
+ (find-eev-intro)
This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
-
+It 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\")
+Note: most of this material was copied to
+ (find-eev-quick-intro \"2. Evaluating Lisp\")
+but some sections are more detailed here...
-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.
+1. The standard way to evaluate Lisp: `C-x C-e'
+===============================================
+The most important idea in Emacs is that Lisp code can appear
+anywhere, and you can evaluate a Lisp expression (a \"sexp\") by
+placing the cursor (the \"point\") just after it and typing `C-x
+C-e'; the result is then displayed in the echo area. Try it in
+the line below, with the point in the three different indicated
+positions - you should get different results.
+ (+ (* 2 3) (* 4 5))
+ ^ ^^
+ | | \\
+ 6 20 26
-2. A first example
-==================
-Let's define two trivial base functions, one that expects a URL,
-and another one that expects a file name:
+2. The end of line and `M-e'
+============================
+A common operation is to move the point to the end of the current
+line, then run `C-x C-e'. That can be done with `C-e C-x C-e',
+but eev-mode implements a shorthand for it: `M-e'. Try it here:
- (defun foo-url (url) (format \"Got URL: %s\" url))
- (defun foo-file (filename) (format \"Got filename: %s\" filename))
+ (+ (* 2 3)
+ (* 4 5)
+ )
-Note that they don't do much - they just return explanatory
-strings.
+`M-e' accepts several different numeric prefixes that alter its
+behavior. We are only interested in one of them now - `M-0 M-e'
+highlights the sexp for a fraction of a second insted of
+executing it. Try it above.
-These two calls,
+In some rare occasions we might want to run something like `M-e'
+but without moving to the end of the line first. Eev-mode
+implements a key binding for that: `M-E' (meta-shift-e). As an
+exercise, try to use `M-0 M-E' at several positions below, to
+hightlight the subsexps `(* 2 3)', `(* 4 5)', and `4'.
- (code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
- (code-brfile 'foo-file :local 'brshowfl)
+ (+ (* 2 3) (* 4 5))
-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\"
+3. What to execute, and in what order
+=====================================
+Note that the order of evaluation may be important:
- (brshowu \"http://a/b\";)
- => `(foo-url \"http://a/b\";) -> \"Got URL: http://a/b\";'
+ (setq a 5)
+ (setq a 6)
+ (* a a)
- (brshowul \"http://a/b\";)
- => `(foo-url \"file:///home/edrx/snarf/http/a/b\") ->
- \"Got URL: file:///home/edrx/snarf/http/a/b\"'
+By executing `(setq a 5)' and then `(* a a)' above we get 25,
+by executing `(setq a 6)' and then `(* a a)' we get 36 - the
+current value of `a' is the one of the last `setq' executed.
- (brshowfl \"http://a/b\";)
- => `(foo-file \"/home/edrx/snarf/http/a/b\") ->
- \"Got filename: /home/edrx/snarf/http/a/b\"'
+An exercise: edit the three sexps above to introduce a
+`(setq a 22)', then use that sexp and the `(* a a)' to calculate
+the square of 22.
-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':
+Another exercise: just as `setq' sets variables and can override
+their previous values, `defun' defines, and redefines, functions.
+Execute the sexps below in different orders to obtain the results
+25, 36, 50, and 60.
- http://a/b
+ (setq a 5)
+ (setq a 6)
+ (defun f (x) (* x x))
+ (defun f (x) (* x 10))
+ (f a)
-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.
+MORAL: Elisp code can appear anywhere in any Emacs buffer, but it
+is _passive by default_. It only gets executed if we move the
+point to the right positions and type `C-x C-e', `M-e', or
+similar keys. Sexps can be executed any number of times, in any
+order, and can be edited and modified.
-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:
+4. Elisp hyperlinks
+===================
+Some Emacs functions can be used as hyperlinks. When sexps like
- http://a/b -> $S/http/a/b -> file:///home/edrx/snarf/http/a/b
- /tmp/c -> file:///tmp/c
+ (find-file \"/tmp/\")
+ (info \"(emacs)Lisp Eval\")
+ (describe-function 'find-file)
+ (find-function 'find-file)
+ (man \"cat\")
-try:
+are executed they \"open a new page\" - actually, they create a
+new buffer, or reuse it if it already exists - and it is usually
+possible to \"go back\" by killing the new buffer. However for
+some functions, like `man', which by default open a manpage in
+another window, \"going back\" would mean something different.
- (ee-url-to-fname \"http://a/b\";)
- (ee-fname-to-url \"/tmp/c\")
- (ee-url-to-local-url \"http://a/b\";)
+Eev defines several functions to let us use sexps as hyperlinks.
+The main conventions on these functions are:
-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:
+ 1) their names start with \"find-\",
- (find-code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
- (find-code-brfile 'foo-file :local 'brshowfl)
+ 2) calls to them can be \"refined\" with a pos-spec (this will
+ be discussed below),
+ 3) they open the new buffer in the current window (to make it
+ easier to \"go back\" after following them - see the next
+ section),
+ 4) they don't display much output in the echo area,
+ 5) when they create temporary buffers with lots of sexps then:
+ a) the first sexp in that buffer is one that can regenerate
+ that buffer when executed,
+ b) all the sexps are prefixed with the string stored in the
+ variable `ee-hyperlink-prefix', to let these sexps be
+ pasted into scripts as comments (see below).
-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:
+Note that sometimes the most obvious name for a hyperlink
+function starting with `find-' is already taken by Emacs - for
+example, `find-file' and `find-function'. In those cases eev use
+other names: `find-fline', `find-efunction', etc. Here are the
+eev versions of the links above:
- \"\" - use the URL without changes
- \"l\" - use the local copy
- \"d\" - dired variation (see below)
+ (find-fline \"/tmp/\")
+ (find-node \"(emacs)Lisp Eval\")
+ (find-efunctiondescr 'find-file)
+ (find-efunction 'find-file)
+ (find-man \"cat\")
-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\"
-In our example with `foo-url' and `foo-file' we had:
- Base function receives stem
- ------------- -------- ----
- foo-url URL showu
- foo-file file name showf
+5. Going back
+=============
+Web browsers let you follow a hyperlink and then \"go back\".
+There are different ways of going back - if you opened the new
+page on a new window or tab, then going back means deleting the
+new window or tab (or just switching to the old window/tab); if
+you opened the new page on the same window/tab, then you need to
+use the \"back\" button.
+Eev-mode defines two keys for \"going back\": `M-k', that kills
+the current buffer, and `M-K', that just hides it (\"buries\" it
+in the bottom of the list of all buffers). Try following the link
+below by <M-e>, then deleting its buffer with `M-k' to go back:
+ (find-node \"(emacs)Shell\")
+In some cases we know that we may want to go \"forward\" again
+after going back, and we may not want to delete the target buffer
+- for example, because it would take a while to rebuild it again,
+or because we would lose the position of the point there. Most
+hyperlink functions in eev are able to reuse a buffer that
+\"looks like\" the desired target buffer; the test for
+lookalikeness is based on the name of the buffer only. Try to
+follow the links below with `M-e', then come back to this buffer
+with `M-k', then follow them again. Then try the same thing with
+`M-K' instead of `M-k', to see the difference - in the `find-sh'
+example below the \"sleep\" takes one second to run, so
+revisiting the existing output buffer after a `M-K' is much
+quicker than recreating it anew.
-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
-
- (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-man \"1 bash\")
+ (find-sh \"sleep 1; echo 'This was run at:'; date\")
- (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\")
-6. The dired variation
+6. Refining hyperlinks
======================
+Most hyperlinks functions defined by eev can be \"refined\" by
+the addition of extra arguments. These extra arguments are called
+a \"pos-spec\" (or a \"pos-spec-list\") and they specify a
+position in the target buffer. The first argument means a certain
+line number, when it is a number, or the first occurrence of a
+certain string, when it is a string. Try:
-In dired mode each line corresponds to a file
+ (find-node \"(emacs)Command Index\")
+ (find-node \"(emacs)Command Index\" \"eval-last-sexp\")
+Further arguments mean either \"move down n lines\" or \"search
+for the next occurrence of a string\", depending on whether they
+are numbers or strings. Try:
-" rest)))
+ (find-sh \"seq 2095 2115\")
+ (find-sh \"seq 2095 2115\" \"2100\")
+ (find-sh \"seq 2095 2115\" \"2100\" \"9\")
+ (find-sh \"seq 2095 2115\" \"2100\" 2)
-;; (find-brxxx-intro)
+7. Pos-spec-lists
+===---===========
+The optional arguments that refine a hyperlink form what we call
+a \"pos-spec-list\". For example, the pos-spec-list here has two
+elements,
+ (find-sh \"seq 2095 2115\" \"2100\" \"9\")
-;;; _
-;;; ___ ___ (_)_ _ _ __ ___ _ __
-;;; / _ \/ _ \| | | | | '_ ` _ \| '_ \
-;;; | __/ __/| | |_| | | | | | | |_) |
-;;; \___|\___|/ |\__,_|_| |_| |_| .__/
-;;; |__/ |_|
-;;
-;; (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 in most cases an empty pos-spec-list, like this,
-(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-sh \"seq 2095 2115\")
+means: \"if the target buffer already exists then just open it\"
+- so that following that hyperlink would jump to the current
+position of the point in that buffer.
+Pos-spec-lists are usually interpreted by the function
+`ee-goto-position'. The first argument is interpreted in a
+special way, according to its type:
-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,
+ string -> jump to the first occurrence of
+ that string in the buffer
+ number -> jump to the n-th line
- 1) we want our list of files to be preserved between one Emacs
- session and another,
+and the other arguments are interpreted (recursively) by
+`ee-goto-rest':
- 2) we know that each \"visit a file\" command will correspond
- to an elisp hyperlink.
+ string -> jump to the next occurence of that string
+ number -> move down n lines
+ list -> evaluate the list
-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':
+If you want to add support for more complex pos-spec-lists, just
+replace `ee-goto-rest' with your own extended version.
- (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,
+8. Anchors and pages
+====================
+\[See:\] (find-anchors-intro)
- 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,
+Some hyperlink functions, like `find-efunction' and
+`find-evariable', jump to specific positions in buffers - the
+beginning of the definition of a function or a variable in the
+source code - even when their pos-spec-lists are empty, so they
+process all their extra arguments with just `ee-goto-rest'.
- 5) the list should be easy to modify,
+Other hyperlink functions transform the first argument of a
+pos-spec-list in a special way it if is a string - for example,
+in `find-available', which is based on `find-Package',
- 6) it should be possible to assign shorter key sequences to
- files we visit more often,
+ (find-available \"bash\")
+ (find-available \"bash\" \"bash-doc\")
- 7) the source code must be very simple.
+the argument \"bash\" is converted to \"\\nPackage: bash\\n\",
+and the two hyperlinks above jump to the description of the
+package \"bash\" in the list of the available packages in a
+Debian system.
+The functions based on `find-anchor' transform an initial string
+argument in the pos-spec-list by running `ee-format-as-anchor' on
+it [TODO: document this], and the ones based on
+`ee-goto-position-page' jump to the n-th \"page\" of a buffer if
+the first argument of the pos-spec-list is a number, n; for
+exemple, if n is 234 that will jump to the 233-th formfeed (233
+and not 234 because the page 1 is before the first formfeed). For
+more on \"pages\", see:
-
-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-pdf-like-intro \"PDF-like documents as text\")
- ;; 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))))
-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...
+9. Producing and refining hyperlinks
+====================================
+If you are on an Info page, typing `M-h M-i' will create a
+temporary buffer containing a header - which we will discuss
+later - and several (possibly equivalent) links to that info
+page. Something like this:
+ ________________________________________________________
+ |;; (find-einfo-links) |
+ | |
+ |;; (info \"(emacs)Misc Buffer\") |
+ |;; (find-node \"(emacs)Misc Buffer\") |
+ |;; (find-enode \"Misc Buffer\") |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental)---|
+ |________________________________________________________|
+These links are meant to be cut & pasted - possibly after
+refining them to make them more precise. Let's look first at the
+two key sequences that make refining much easier. Remember that
+`M-w' (`kill-ring-save') is roughly correspondent to what is
+called \"copy\" is most modern interfaces, and `C-y' (`yank') is
+roughly correspondent to \"paste\". Both `M-w' and `C-y' operate
+on Emacs's \"kill ring\", and to make our examples trivial to
+follow we will first put a string on the kill ring:
+ (kill-new \"C-y\")
+ (car kill-ring)
-Families
-========
-Let's use a shorthand for key sequences: for example, `M-123j'
-instead of `M-1 M-2 M-3 M-j'.
+Now let's see how refine hyperlinks quickly. `M-h M-2' duplicates
+the current line; we will use that to refine a copy of a working
+hyperlink, instead of working directly on the original, and
+risking breaking it. And `M-h M-y' refines the hyperlink on the
+current line by adding a string - the top element in the kill
+ring - to its sexp. Try this below; you should be able to convert
-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.
+ (find-enode \"Kill Ring\")
+ (find-enode \"Yanking\")
-The definition of `eejump-simplified' given above does not
-satisfy these two (new!) wishlist items:
+into
- 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,
+ (find-enode \"Kill Ring\")
+ (find-enode \"Kill Ring\" \"C-y\")
+ (find-enode \"Yanking\")
+ (find-enode \"Yanking\" \"C-y\")
- 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).
+with few keystrokes, as you can leave the Meta key pressed. The
+full key sequence for duplicating and refining is `M-h M-2 M-h
+M-y', but we can think of it as `M-h2hy'.
+Now try a more serious exercise: follow the `(find-enode ...)'
+hyperlink below, copy a word or two from its contents to the kill
+ring with `M-w', then generate the temporary buffer with
+hyperlinks to that Info page with `M-h M-i', then duplicate one
+of its hyperlinks with `M-h M-2', refine it with `M-h M-y', and
+copy the result to this sandbox with `M-w' (or `C-w') and `C-y'.
+As this is a long sequence of instructions, it is better to run
+`C-x 1 C-x 2' or `C-x 1 C-x 3' before following the hyperlink, to
+keep the instructions visible.
+ (find-enode \"Command Index\")
-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)\".
+What else?
+==========
+Eev-mode defines several other key sequences similar to `M-h
+M-i'. You can get the full list here:
- (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*)
+ (find-efunctiondescr 'eev-mode)
+ (find-efunctiondescr 'eev-mode \"M-h f\")
-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\"...
+Try also this:
+ (find-efunction-links 'eev-mode)
+and for other tutorials like this one, try:
-eejump blocks
-=============
-Let's a call a sequence of defuns for eejumps with the same
-prefix, like this, starting with a `(defun eejump-<prefix>* ...)',
+ (find-wrap-intro)
+ (find-eepitch-intro)
- (defun eejump-99* () (find-efunction 'eejump-99*))
- (defun eejump-991 () (message \"M-991j\"))
- (defun eejump-992 () (message \"M-992j\"))
+\[To do: explain M-x ee-hyperlink prefix and how to embed
+hyperlinks in scripts]
+" rest)))
-an \"eejump block\".
+;; (find-eval-intro)
-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.
+;;; _ _ _ _ _
+;;; ___ ___ _ __ (_) |_ ___| |__ (_)_ __ | |_ _ __ ___
+;;; / _ \/ _ \ '_ \| | __/ __| '_ \ _____| | '_ \| __| '__/ _ \
+;;; | __/ __/ |_) | | || (__| | | |_____| | | | | |_| | | (_) |
+;;; \___|\___| .__/|_|\__\___|_| |_| |_|_| |_|\__|_| \___/
+;;; |_|
+;;
+;; �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-eepitch-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-eepitch-intro\")
+More intros: (find-eev-quick-intro)
+ (find-eval-intro)
+ (find-wrap-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial (for eepitch) and a sandbox.
-Making an `eejump-nn*' work
-===========================
-If you execute a line like
+For an introduction to the ideas here, see:
+ (find-eev-quick-intro \"6. Controlling shell-like programs\")
- (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!),
+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.
- b) the buffer with the definition is associated to a file; see
- these two pages of the Emacs manuals
+The two usual ways to interact with a shell are:
- (find-enode \"Buffers\" \"visiting\")
- (find-elnode \"Buffer File Name\")
+ 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,
- if that concept is not totally familiar to you.
+ 2) _interactively_, by typing the commands one by one on a
+ shell prompt.
-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:
+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:
- (find-elnode \"Where Defined\")
+ 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.
+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.
-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:
+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.
- 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.
+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 |
+ |_________|_________|
- a b c d
- a b c
- a b
- a
+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>.
+Here's what <F8> does:
+ 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.
-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'.
+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)\"
-# Local Variables:
-# coding: raw-text-unix
-# ee-anchor-format: \"%s\"
-# End:
-" rest)))
-;; (find-eejump-intro)
+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
+print(square(5))
+ We can use several targets at the time, alternating between them.
+ For example:
-;;; _ __ _ _ _
-;;; _ __ __| |/ _| | (_) | _____
-;;; | '_ \ / _` | |_ _____| | | |/ / _ \
-;;; | |_) | (_| | _|_____| | | < __/
-;;; | .__/ \__,_|_| |_|_|_|\_\___|
-;;; |_|
-;;
-;; �find-pdf-like-intro� (to ".find-pdf-like-intro")
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+echo Hello... > /tmp/o
-(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.
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
+ (eepitch-shell)
+echo ...and bye >> /tmp/o
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
-PDF-like documents
-==================
-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,
+ There is a (much) more advanced example of working with several
+ targets here:
- (find-enode \"Document View\")
+ (find-prepared-intro \"An `ee' for Python\")
-but we will see a more eev-like way of pointing to pages of
-PDF-like documents.
-Two test documents
-==================
-The following script creates two PDF-like documents - a DVI and a
-PDF - that we will use in the examples below.
+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-shell)
+ (eepitch-python)
(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
+ (eepitch-python)
-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:
+and:
- 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
+ (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.
-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':
- (find-bgprocess '(\"xdvi\" \"+4\" \"/tmp/foo.dvi\"))
- (find-bgprocess '(\"xpdf\" \"/tmp/foo.pdf\" \"4\"))
+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.
-Alternatively, we can invoke these viewers like this,
+shell
+pwd
+cd /tmp/
+pwd
- (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\".
+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'.
-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\".
+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)
-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:
+;; (find-pytutnode "Methods of File Objects")
- (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',
-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\".
+;;; _ _
+;;; __ ___ __ __ _ _ __ (_)_ __ | |_ _ __ ___
+;;; \ \ /\ / / '__/ _` | '_ \ _____| | '_ \| __| '__/ _ \
+;;; \ 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.
-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
+For an introduction to the ideas here, see:
+ (find-eev-quick-intro \"6. Controlling shell-like programs\")
-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)
-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').
+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!!!
-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:
+<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:
- (find-pdf-text \"/tmp/foo.pdf\")
- (find-djvu-text \"/tmp/foo.djvu\")
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
-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:
+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>):
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+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
-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:
+python
+square = lambda x: x*x
+square(5)
- (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))
+<M-F>: hyperlink to a file or a directory
+=========================================
+If you type <M-F> on the lines below,
-to this:
+/etc/
+/tmp/
+~/
+~/.emacs
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
- (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+you get hyperlinks like these:
-is a special case of \"refining hyperlinks\", an idea that we saw
-in:
+# (find-fline \"/etc/\")
+# (find-fline \"/tmp/\")
+# (find-fline \"~/\")
+# (find-fline \"~/.emacs\")
- (find-eval-intro \"Refining hyperlinks\")
+<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\")
-High-level hyperlinks to pdf-like documents
-===========================================
-By executing
+Try it here:
- (code-pdf \"fp\" \"/tmp/foo.pdf\")
- (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+dict smop
+dict 'minor detail'
-we can use shorter hyperlinks, like
+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-fppage (+ 3 1) \"Chapter 1\")
- (find-fptext (+ 3 1) \"Chapter 1\")
+ # (find-sh \"dict smop\")
+ # (find-sh \"dict 'minor detail'\")
-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:
+<M-M>: hyperlink to a manpage
+=============================
+Try <M-M> here:
- (find-code-pdf \"fp\" \"/tmp/foo.pdf\")
- (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+1 tac
-There is a wrapping comand for producing these
-`code-pdf'/`code-pdf-text' pairs quickly - `M-P'. Try it here:
- fp /tmp/foo.pdf
+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/
-Producing and refining hyperlinks to pages
-==========================================
-We also have something like this
+ (eek \"2*<down> M-D <down> ;;; Test eewrap-debian\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-debian\")
+bash
- (find-eval-intro \"Producing and refining hyperlinks\")
+ (eek \"2*<down> M-F <down> ;;; Test eewrap-find-fline\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-find-fline\")
+/tmp/foobar/
-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.
+ (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
+422 (find-eev-intro \"find-wrap-intro\")
-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:
+ (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
+42
- (find-code-pdf \"fp\" \"/tmp/foo.pdf\")
- (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+ (eek \"2*<down> M-M <down> ;;; Test eewrap-man\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-man\")
+1 tac
-Here's how these variables are used. Try this:
+ (eek \"2*<down> M-P <down> ;;; Test eewrap-pdflike\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-pdflike\")
+foopdf $S/http/foo.org/bar.pdf
- (code-pdf \"fp\" \"/tmp/foo.pdf\")
- (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
- (kill-new \"Two\")
- (eek \"M-h M-p\")
+ (eek \"2*<down> M-R <down> ;;; Test eewrap-rm/mkdir/cd\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-rm/mkdir/cd\")
+/tmp/foo/
-You should get a page with several hyperlinks to the \"current
-page\" of the current pdf-like document, including some like
-these:
+ (eek \"2*<down> M-S <down> ;;; Test eewrap-sh\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-sh\")
+seq 1 20
- (find-fppage 1)
- (find-fptext 1)
- (find-fppage (+ 3 -2))
- (find-fptext (+ 3 -2))
+ (eek \"2*<down> M-T <down> ;;; Test eewrap-eepitch\")
+ Source: (find-eev \"eepitch.el\" \"eewrap-eepitch\")
+python
- (find-fppage 1 \"Two\")
- (find-fptext 1 \"Two\")
- (find-fppage (+ 3 -2) \"Two\")
- (find-fptext (+ 3 -2) \"Two\")
+ (eek \"2*<down> M-V <down> ;;; Test eewrap-audiovideo\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-audiovideo\")
+slimetutorial /tmp/slime-tutorial.mp4
-Where did the \"fp\", the \"1\", the \"3\", the \"-2\" and the
-\"Two\" above come from?
+ (eek \"2*<down> M-Z <down> ;;; Test eewrap-zsh\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-zsh\")
+echo $SHELL
-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'.
+ (eek \"2*<down> <<eewrap-eewrap>> <down> ;;; Test eewrap-eewrap\")
+ Source: (find-eev \"eev-wrap.el\" \"eewrap-eewrap\")
+U user-defined a b c
-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
-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
+Wrapping functions generate hyperlinks
+======================================
+...this is a slogan - a huge idea, in a very shortened form. In its
+full form, that would be:
- (find-debttext 7 \"Contents\")
+ (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:
-with a bit of fiddling by hand and keyboard macros. Keyboard
-macros are VERY useful; if you don't use them yet, see:
+ (find-links-intro \"Elisp hyperlinks buffers\")
- (find-enode \"Keyboard Macros\")
+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.
+
+
+
+
+# Local Variables:
+# coding: raw-text-unix
+# ee-anchor-format: \"�%s�\"
+# End:
" rest)))
-;; (find-pdf-like-intro)
+;; (find-wrap-intro)
-;;; _ _ __ _ _
-;;; __ _ _ _ __| (_) ___ / /_ _(_) __| | ___ ___
-;;; / _` | | | |/ _` | |/ _ \ / /\ \ / / |/ _` |/ _ \/ _ \
-;;; | (_| | |_| | (_| | | (_) / / \ V /| | (_| | __/ (_) |
-;;; \__,_|\__,_|\__,_|_|\___/_/ \_/ |_|\__,_|\___|\___/
-;;;
-;; �find-audiovideo-intro� (to ".find-audiovideo-intro")
-;; (find-intro-links "audiovideo")
+;;; _ _ _
+;;; | (_)_ __ | | _____
+;;; | | | '_ \| |/ / __|
+;;; | | | | | | <\__ \
+;;; |_|_|_| |_|_|\_\___/
+;;;
+;; (find-intro-links "links")
+;; �find-links-intro� (to ".find-links-intro")
-(defun find-audiovideo-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-audiovideo-intro)*"))
+(defun find-links-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-links-intro)*"))
(apply 'find-estring "\
-\(Re)generate: (find-audiovideo-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-audiovideo-intro\")
+\(Re)generate: (find-links-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-links-intro\")
More intros: (find-eev-quick-intro)
- (find-eev-intro)
(find-eval-intro)
(find-eepitch-intro)
This buffer is _temporary_ and _editable_.
@@ -2967,428 +2576,551 @@ Is is meant as both a tutorial and a sandbox.
-Time offsets
-============
-Links to audio and video files are similar to links to pdf-like
-documents, but instead of page numbers we use \"time offsets\" to
-refer to positions. Time offsets are strings like 1:23, 12:34, or
-1:23:45. The sexp hyperlinks below should all work if you have the
-files that they refer to:
-
- (find-audio \"/tmp/mysong.mp3\")
- (find-audio \"/tmp/mysong.mp3\" \"1:23\")
- (find-audio \"/tmp/mysong.mp3\" \"1:23\" \"comment are ignored\")
- (find-video \"/tmp/myvideo.mp4\")
- (find-video \"/tmp/myvideo.mp4\" \"1:23\")
- (find-video \"/tmp/myvideo.mp4\" \"1:23\" \"comment are ignored\")
-Note that they work by invoking an external player - mplayer, by
-default - and its error messages appear here:
+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-ebuffer \"*Messages*\")
+ (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:
+ (find-sh \"<code that deletes all your e-mails>\")
-Shorter hyperlinks to audio and video files
-===========================================
-If you type `M-V' (`eewrap-audiovideo') on a line containing a
-shorthand word and a file name of an audio or video file, for
-example, here,
+but it is not possible to hide that action behind an
+innocent-looking button that says \"click for a larger image\".
- sunwillset ~/Zoe_Keating/Sun_Will_Set.ogg
+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.
-you will get something like this:
- ;; (find-fline \"~/Zoe_Keating/\")
- (code-audio \"sunwillset\" \"~/Zoe_Keating/Sun_Will_Set.ogg\")
- (code-video \"sunwillset\" \"~/Zoe_Keating/Sun_Will_Set.ogg\")
- ;; (find-sunwillset)
- ;; (find-sunwillset \"0:00\")
-you should delete the line with the wrong sexp by hand - in this
-case the wrong one is the one with `code-video', as we are
-working with a sound file - and execute the other one; this will
-define a function called `find-sunwillset', that plays the audio
-file with `find-audio'. Run this this sexp to inspect its code:
- (find-code-audio \"sunwillset\" \"/tmp/Zoe_Keating__Sun_Will_Set.ogg\")
+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.
-you will notice that running `find-sunwillset' sets a variable,
-with:
+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:
- (setq ee-audiovideo-last 'find-sunwillset)
+ \"C-h f find-file\" -> (find-efunctiondescr 'find-file)
+ \"M-h M-f find-file\" -> (find-efunction-links 'find-file)
-As we shall see soon, some operations play again the default
-audio or video file, starting from some given time offset. The
-default is always what is stored in `ee-audiovideo-last', and
-each call to a short hyperlink of the form `find-xxxaudio' or
-`find-xxxvideo' sets that variable.
+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\")
+`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:
-Passing options to mplayer
-==========================
-By default mplayer is called with just a few command-line options,
-besides the ones that tell it at what position to start playing -
-typically just these for videos,
+ ___________________________________________________________
+ |# (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)--|
+ |___________________________________________________________|
- -fs -osdlevel 2
+What is that?...
-to make it run in full-screen mode with an on-screen display
-showing the current position, and no options for audio.
-If you want to change this you should redefine these functions:
- (ee-mplayer-video-options)
- (ee-mplayer-audio-options)
-
-
+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\";
-`eev-avadj-mode'
-================
-\"avadj-mode\" is a shorthand for \"audio/video adjust mode\".
-When `eev-avadj-mode' is active we get keys for adjusting time
-offsets quickly and for playing again the default audio or video
-file at a given time offset, all of this without moving the
-point. The keys are:
+ 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;
- M-- decrease the time offset by one second
- M-+ increase the time offset by one second
- M-= same as M-+, for convenience
- M-p play the default audio/video file at a time offset
+ 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,
-You can toggle eev-avadj-mode on and off with `M-x
-eev-avadj-mode', or with this sexp:
+ (find-eval-intro \"Refining hyperlinks\")
- (eev-avadj-mode)
+ 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.
-When it is on you will see an \"avadj\" at the mode line. Let's
-examine `M--' and `M-+' first. With eev-avadj-mode on, try typing
-several `M--'s and `M-+'s (or `M-='s) on the line below:
+ 5) C-h buffers are _readable_, while
+ M-h buffers may look like (technical) gibberish.
- This time offset - 9:59 - will change
+ 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:
-Now, as an exercise, try to use `M--'s and `M-+'s/`M-='s, plus
-`M-h M-2' (`ee-duplicate-this-line') and other more standard
-editing commands, to convert this line
+ (find-find-links-links)
- (find-exampleaudio \"0:00\")
+ Most `find-*-links' were created from that template - and it
+ should be easy to create other ones.
-into:
+ 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:
- (find-exampleaudio \"0:00\")
- (find-exampleaudio \"0:12\" \"blah\")
- (find-exampleaudio \"0:30\" \"bleh\")
+ 6) The first line (the \"top sexp\") of an M-h buffer
+ regenerates the buffer. And, at last,
-That should give you an idea of how to index audio or video files
-- by creating elisp hyperlinks, with comments, to specific
-positions in them. Of course in a real-world situation we would
-execute these sexps occasionally to check if they are really
-pointing to the right places, and then make further adjustments;
-we are not doing that yet.
+ 7) The elisp hyperlinks in M-h buffers are prefixed by the
+ string in `ee-hyperlink-prefix'.
-The time-from-bol
-=================
-All the keys in eev-avadj-mode operate on the \"time-from-bol\"
-of the current line: the first occurrence, in the current line,
-of a string that looks like a time offset. Note that the search
-starts from the beginning of the line (\"-from-bol\"), and if
-there are several possibilities, the first one is chosen.
+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_.
-Remember that `M-e' has a variant that just highlights what would
-be executed, instead of evaluating a sexp:
+`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,
- (find-eval-intro \"`M-0 M-e'\")
+ ____________________________________________________________
+ |# See: |
+ |# (find-links-intro \"`find-here-links'\") |
+ |# (find-efunctiondescr 'eev-mode \"M-h M-h\") |
+ | |
+ |# (find-links-intro) |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
+ |____________________________________________________________|
-`M-p' also has something like this: `M-0 M-p' highlights the
-time-from-bol and displays in the echo area the sexp that it
-would execute to invoke a player - instead of running that sexp.
-Try to evaluate these sexps:
+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
- (code-audio \"sunwillset\" \"~/Zoe_Keating/Sun_Will_Set.ogg\")
- (find-sunwillset)
- ;; ^ don't worry if this fails - we are only calling it
- ;; to set `ee-audiovideo-last'
+ (find-links-intro)
-and now try `M-0 M-p' on these lines:
+can be \"refined\" to, for example,
- ;; 4:19 blah
- ;; 2:19
+ (find-links-intro \"which contains a 3-line header\")
-For more realistic examples, see:
+using the tricks described in these sections:
- (find-videos-intro)
+ (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:
+ (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))
-Youtube-dl
-==========
-Videos at Youtube are identified by unique 11-char codes that are
-assigned to them when they are uploaded. We will call those 11-char
-codes \"hashes\", even though the term is not totally adequade in this
-case, and we will explain the main ideas considering the case of an
-imaginary video whose title is just TITLE, and whose hash is
-\"abcdefghijk\". The URL to access that video at Youtube would be this:
+ (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))
- http://www.youtube.com/watch?v=abcdefghijk
- \\---------/
- its hash
+ (find-here-links-test '(find-ecolors \"\\nred\"))
+ (find-here-links-test '(find-efaces \"eepitch-star-face\"))
+ (find-here-links-test '(find-customizegroup 'rcirc))
-If we execute this on a shell,
+ (find-here-links-test '(find-man \"1 cat\"))
+ [^ oops, this test doesn't work on multi-window settings...]
- cd /tmp/
- youtube-dl -t 'http://www.youtube.com/watch?v=abcdefghijk'
+Each one of them tests a different case of `find-here-links',
+creating a window setup like this:
-then youtube-dl would download a local copy of the video; due to the
-option \"-t\" (\"--title\"), the name of the local copy would have both
-the title of the video and its hash, and, if the video is in MP4
-format, that would be
+ ______________________________________
+ | | |
+ | | target of |
+ | | sexp |
+ | this |______________________|
+ | intro | |
+ | | result of running |
+ | | find-here-links on |
+ | | [target of sexp] |
+ |_______________|______________________|
- /tmp/TITLE-abcdefghijk.mp4.part
+The cursor is kept at the left window (\"this intro\"), so you
+can compare the different cases using just <up>, <down>, and M-e.
-during the download, and would be renamed to
- /tmp/TITLE-abcdefghijk.mp4
-as soon as the download is finished.
+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:
-Downloading a local copy
-========================
-Place the point at hash in the URL below,
+ 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.
- http://www.youtube.com/watch?v=abcdefghijk
+At (8) we are essentially back to (1), but we have added to our
+e-script buffer a link to \"something interesting\".
-and run `M-x find-youtubedl-links'; `find-youtubedl-links' will use
-the hash at point as a default for one of its arguments, will run
-something equivalent to this sexp,
+Note that to add refining we need to add a step before (2) and
+another one after (3):
- (find-youtubedl-links nil nil \"abcdefghijk\")
+ 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)
-and will create a buffer like this:
+\[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]
- ___________________________________________________________________________
- |# (find-youtubedl-links \"/tmp/\" \"{title}\" \"abcdefghijk\" \"{ext-}\"
\"{stem}\") |
- |# (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
|
- | |
- |# (find-youtubedl-links \"~/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
|
- |# (find-youtubedl-links \"~/videos/tech/\" nil \"abcdefghijk\" nil
\"{stem}\") |
- |# (find-youtubedl-links \"/tmp/videos/\" nil \"abcdefghijk\" nil
\"{stem}\") |
- |# (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
|
- |# (find-efunction 'find-youtubedl-links) |
- | |
- | (eepitch-shell2) |
- | (eepitch-kill) |
- | (eepitch-shell2) |
- |# http://www.youtube.com/watch?v=abcdefghijk |
- |# http://www.youtube.com/watch?v=abcdefghijk#t=0m00s |
- |# http://www.youtube.com/watch?v=abcdefghijk#t=0h00m00s |
- |cd /tmp/ |
- |youtube-dl -t 'http://www.youtube.com/watch?v=abcdefghijk' |
- | |
- |# youtube-dl -t -F 'http://www.youtube.com/watch?v=abcdefghijk' |
- |# youtube-dl -t -f 18 'http://www.youtube.com/watch?v=abcdefghijk' |
- | |
- |# (find-es \"video\" \"youtube-dl\")
|
- |# (find-fline \"/tmp/\" \"abcdefghijk\")
|
- |# (find-fline \"/tmp/\" \"{title}-abcdefghijk\")
|
- |# (find-fline \"/tmp/\" \"{title}-abcdefghijk{ext-}\")
|
- |# (find-video \"/tmp/{title}-abcdefghijk{ext-}\")
|
- |# (find-video \"/tmp/{title}-abcdefghijk{ext-}.part\")
|
- |# (code-video \"{stem}video\" \"/tmp/{title}-abcdefghijk{ext-}\")
|
- |# (code-video \"{stem}video\" \"/tmp/{title}-abcdefghijk{ext-}.part\")
|
- |# (find-{stem}video) |
- |# (find-{stem}video \"0:00\")
|
- | |
- |# Error messages (for the player): |
- |# (find-ebuffer \"*Messages*\")
|
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental)----------------------|
- |___________________________________________________________________________|
-which has LOTS of things... the part
- (eepitch-shell2)
- (eepitch-kill)
- (eepitch-shell2)
- cd /tmp/
- youtube-dl -t 'http://www.youtube.com/watch?v=abcdefghijk'
-is obvious: it is an eepitch script that downloads a local copy
-of the video from Youtube.
+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?
+We can start by dividing the hyperlink functions into a fixed set
+of \"basic\" ones and an unbounded set of \"non-basic\" ones. In
+the buffer generated by
+ (find-efunction-links 'find-file)
+these hyperlinks
-Guessing the title and extension
-================================
-Let's simulate what would happen after the eepitch script above -
-Execute this:
+ (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))
- (find-sh0 \"rm -v /tmp/TITLE-abcdefghijk*\")
- (find-sh0 \"echo > /tmp/TITLE-abcdefghijk.mp4.part\")
+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,
-Now use `M-2 M-e' to compare the buffers generated by two calls
-to `find-youtubedl-links' below:
+ (find-enode \"Command Index\" \"* find-file:\")
+ (find-elnode \"Index\" \"* find-file:\")
- (find-youtubedl-links nil nil \"abcdefghijk\")
- (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\")
+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:
-In the second one we get a buffer where all occurrences
-of \"{title}\" have been substituted by \"TITLE\", and all
-occurrences of \"{ext-}\" by \".mp4\". What happenned was that
+ (find-code-c-d-intro)
+ (find-pdf-like-intro)
+ (find-audiovideo-intro)
- (ee-youtubedl-guess* \"/tmp/\" \"abcdefghijk\")
- --> (\"/tmp/TITLE-abcdefghijk.mp4.part\")
+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:
-did find files what that hash string in their names in the
-directory \"/tmp/\", and the function `ee-youtubedl-split' has
-picked up the first of these file names and has split it into
-components:
+ (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\")
- (ee-youtubedl-split \"/tmp/TITLE-abcdefghijk.mp4.part\")
- --> (\"/tmp/\" \"TITLE\" \"abcdefghijk\" \".mp4\" \".mp4.part\")
+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.
-The last of these components is what we will call the \"ext\" -
-the \"full extension\" - and the previous one is the \"ext-\" -
-the \"extension minus its optional `.part'\". The first three
-components are the \"dir\", the \"title\", and the \"hash\".
+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.
-The first lines regenerate the buffer
-=====================================
-The arguments to `find-youtubedl-links' are:
- (find-youtubedl-links DIR TITLE HASH EXT- STEM)
+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.
-and we just saw how `ee-youtubedl-guess*' and
-`ee-youtubedl-split' can be used to guess TITLE, EXT and EXT-
-from DIR and HASH.
+If you run `M-x ee-hyperlink-prefix' you should get a buffer like
+this:
-All the arguments to `find-youtubedl-links' have defaults,
-that are used when the received arguments are nil:
+ ___________________________________________________________
+ |# (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)--|
+ |___________________________________________________________|
- * when HASH is nil, use the youtube hash around point,
- or \"{hash}\" if none;
- * when DIR is nil, use the value of `ee-youtubedl-dir',
- or \"{dir}\" if none;
- * when TITLE or EXT- are nil use the guessing method described
- above, and when they fail use \"{title}\" or \"{ext-}\";
- * when STEM is nil, use \"{stem}\".
+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:
-The first two lines in a `find-youtubedl-links' regenerate the
-buffer, and are usually equivalent to one another. In the buffer
-generated by:
+ (progn (setq ee-hyperlink-prefix \"# \") (ee-hyperlink-prefix))
+ (progn (setq ee-hyperlink-prefix \"% \") (ee-hyperlink-prefix))
- (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\")
-they are:
- (find-youtubedl-links \"/tmp/\" \"TITLE\" \"abcdefghijk\" \".mp4\"
\"{stem}\")
- (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
-The first one has only non-nil arguments - all the rules for
-guesses and defaults have been applied - where in the second one
-TITLE and EXT- are made nil.
+8. The first line regenerates the buffer
+========================================
+\[To do: explain this convention with examples; explain the
+conventions for the \"variants of the first line\"\]
+ (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\")
-Selecting a directory
-=====================
-The second block of lines in the `find-youtubedl-links' buffer
-are used to let we switch the directory quickly. If we just
-execute `M-x find-youtubedl-links' with the point on our example
-hash, or, equivalently, if we do this,
- (find-youtubedl-links nil nil \"abcdefghijk\")
+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 -
-you will see that the first two lines will be:
+\[To do: write this\]
- (find-youtubedl-links \"~/videos/\" \"{title}\" \"abcdefghijk\" \"{ext-}\"
\"{stem}\")
- (find-youtubedl-links \"~/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
+ (find-efunctiondescr 'eev-mode)
+ (find-efunctiondescr 'eev-mode \"M-h f\")
-which means that the guessing process didn't find a downloaded
-copy, as TITLE is \"{title}\" and EXT- is \"{ext-}\". That's because
-we are using \"~/videos/\" as the DIR, and our file
+ (eek \"M-h M-i\")
- /tmp/TITLE-abcdefghijk.mp4.part
+ (find-enode \"Lisp Eval\")
+ (progn (find-enode \"Lisp Eval\") (eek \"M-h M-i\"))
-is elsewhere, and the guessing functions only search in one
-directory...
+ (eek \"M-h f ;; find-file-links\")
+ (eek \"M-h M-b ;; find-ebuffer-links\")
-The second block contains these sexps,
+ 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:
- (find-youtubedl-links \"~/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
- (find-youtubedl-links \"~/videos/tech/\" nil \"abcdefghijk\" nil \"{stem}\")
- (find-youtubedl-links \"/tmp/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
- (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
+ (eek \"M-h M-i\")
-and if we execute the last one we set DIR to \"/tmp/\".
+ you should get something like this:
-To change the dir strings \"~/videos/\", \"~/videos/tech/\", \"/tmp/videos/\",
-\"/tmp/\", that appear in the second block of `find-youtubedl-links'
-buffers, change the variables `ee-youtubedl-dir', `ee-youtubedl-dir2',
-`ee-youtubedl-dir3', `ee-youtubedl-dir4.'
+ ___________________________________________________________
+ |# (find-einfo-links \"links\") |
+ | |
+ |[No \"*info*\" buffer] |
+ | |
+ |# (find-links-intro) |
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
+ |___________________________________________________________|
-How to download
-===============
+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)
-Test the download
-=================
+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:
+ ____________________________________________________________
+ |# (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)---|
+ |____________________________________________________________|
-Create short links
-==================
+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:
+ 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.
+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'),
- (find-youtubedl-links \"/tmp/\" \"TITLE\" \"abcdefghijk\" \".mp4\"
\"{stem}\")
- (find-youtubedl-links nil nil \"abcdefghijk\")
+ 2) it copies the rest of the buffer to the kill ring (like as
+ with `M-w'),
- (find-eev \"eev-audiovideo.el\")
- (find-eev \"eev-audiovideo.el\" \"eev-avadj-mode\")
+ 3) it runs CODE to open its target in a window at the right
+ side (like as with `M-3 M-e')
-" pos-spec-list)))
+\[To do: add examples - including examples that let us create Lua
+scripts etc\]
-;; (find-audiovideo-intro)
+" rest)))
+;; (find-links-intro)
+;; (find-eevfile "eev-template.el" "defun find-efunction-links")
-;;; _ _ _ _ _
-;;; _ __ ___ _ _| | |_(_)_ _(_)_ __ __| | _____ __
-;;; | '_ ` _ \| | | | | __| \ \ /\ / / | '_ \ / _` |/ _ \ \ /\ / /
-;;; | | | | | | |_| | | |_| |\ V V /| | | | | (_| | (_) \ V V /
-;;; |_| |_| |_|\__,_|_|\__|_| \_/\_/ |_|_| |_|\__,_|\___/ \_/\_/
-;;;
-;; �find-multiwindow-intro� (to ".find-multiwindow-intro")
-;; (find-intro-links "multiwindow")
-(defun find-multiwindow-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-multiwindow-intro)*"))
+
+
+;;; _ _ _ _
+;;; ___ ___ __| | ___ ___ __| | (_)_ __ | |_ _ __ ___
+;;; / __/ _ \ / _` |/ _ \_____ / __|____ / _` |_____| | '_ \| __| '__/ _ \
+;;; | (_| (_) | (_| | __/_____| (_|_____| (_| |_____| | | | | |_| | | (_) |
+;;; \___\___/ \__,_|\___| \___| \__,_| |_|_| |_|\__|_| \___/
+;;;
+;; �find-code-c-d-intro� (to ".find-code-c-d-intro")
+
+(defun find-code-c-d-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-code-c-d-intro)*"))
(apply 'find-estring "\
-\(Re)generate: (find-multiwindow-intro)
-Source code: (find-efunction 'find-multiwindow-intro)
+\(Re)generate: (find-code-c-d-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-code-c-d-intro\")
More intros: (find-eev-quick-intro)
- (find-eev-intro)
(find-eval-intro)
(find-eepitch-intro)
This buffer is _temporary_ and _editable_.
@@ -3396,433 +3128,356 @@ 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'\")
-1. Introduction
-===============
-In many situations - for example, when we want to script a
-debugger, or to test programs that have to talk to one another,
-or to control several external machines simultaneously - the
-default window setup for eepitch, which is this,
- ____________________
- | | |
- | | |
- | script | shell |
- | | |
- | | |
- |__________|_________|
-is not enough; other setups, like these,
+Avoiding full path names
+========================
+Suppose that you have downloaded (\"psne\"-ed) this URL,
- ______________________
- | | | _________________________
- | | shell A | | | |
- | |___________| | script | GDB |
- | script | | | | |
- | | shell B | |____________|____________|
- | |___________| | | |
- | | | | program | program |
- | | shell C | | I/O | source |
- |__________|___________| |____________|____________|
+ http://www.lua.org/ftp/lua-5.1.4.tar.gz
-may be necessary. Eev comes with a few _low-level_ tools for
-creating these setups; they are not very smart, but they should
-be easy to understand and to tweak - and I have the impression
-that ideas for good high-level tools will only come from
-practical experimentation.
+with `M-x brep' - see:
+ (find-psne-intro)
+and you unpacked that tarball into the directory ~/usrc/ (I
+prefer to use that instead of /usr/src/) with:
-2. `find-wset'
-==============
-Suppose that we are in a buffer A, and we want to create a window
-configuration with A at the left, and with the buffers B and C
-stacked on one another at the right. That is:
+ tar -C ~/usrc/ -xvzf $S/http/www.lua.org/ftp/lua-5.1.4.tar.gz
- ___________ ___________
- | | | | |
- | | | | B |
- | A | --> | A |_____|
- | | | | |
- | | | | C |
- |___________| |_____|_____|
+Now you can access some directories and files of the unpacked
+tarball with:
-To do that from the keyboard we could type this:
+ (find-fline \"~/usrc/lua-5.1.4/\")
+ (find-fline \"~/usrc/lua-5.1.4/src/\")
+ (find-fline \"~/usrc/lua-5.1.4/src/lstrlib.c\")
+ (find-fline \"~/usrc/lua-5.1.4/test/\")
+ (find-fline \"~/usrc/lua-5.1.4/test/README\")
+ (find-fline \"~/usrc/lua-5.1.4/doc/\")
+ (find-w3m \"~/usrc/lua-5.1.4/doc/contents.html\")
- C-x 3 C-x o C-x b B RET C-x 2 C-x o C-x b C RET
+but it's a bit clumsy to have to use the \"~/usrc/lua-5.1.4/\"
+every time, so eev provides a nice way to define shorthands. We
+want to be able to write just this instead of the sexps above,
-You can try that here (the initial `C-x 1' is an extra, for
-convenience):
+ (find-lua51file \"\")
+ (find-lua51file \"src/\")
+ (find-lua51file \"src/lstrlib.c\")
+ (find-lua51file \"test/\")
+ (find-lua51file \"test/README\")
+ (find-lua51file \"doc/\")
+ (find-lua51w3m \"doc/contents.html\")
- (eek \"C-x 1 ;; delete-other-windows
- C-x 3 ;; split-window-horizontally (left/right)
- C-x o ;; other-window (-> right)
- C-x b B RET ;; switch to the buffer `B'
- C-x 2 ;; split-window-vertically (upper/lower)
- C-x o ;; other-window (-> lower right)
- C-x b C RET ;; switch to the buffer `C'
- \")
-
-We can write something equivalent to that as a `progn', in a way
-that makes it easy to replace later the `C-x b B RET' and the
-`C-x b C RET' by arbitrary sexp hyperlinks. We get:
-
- (progn (eek \"C-x 1 C-x 3 C-x o\")
- (find-ebuffer \"B\")
- (eek \"C-x 2 C-x o\")
- (find-ebuffer \"C\")
- (eek \"C-x o\")
- )
-
-When I started to rewrite my window configurations into that form
-I realized that the `eek's were being used in a very limited way
-- they only invoked a very small repertoire of window commands,
-all of them starting with `C-x'. So maybe I should have an
-interpreter for a simple language of window commands and sexp
-hyperlinks, in the which window setup above could be expressed
-like this:
-
- `(\"13o\"
- (find-ebuffer \"B\")
- \"2o\"
- (find-ebuffer \"C\")
- \"o\"
- )
-
-`find-wset' supports something like that, but with all the window
-command strings collapsed into a single one, with \"_\"s meaning
-\"execute the next sexp from the sexp list\". The corresponding
-call to `find-wset' is:
+and here the directory \"~/usrc/lua-5.1.4/\" became a mnemonic
+\"lua51\" in the middle of the names of some functions.
- (find-wset \"13o_2o_o\" '(find-ebuffer \"B\") '(find-ebuffer \"C\"))
+We will call these sexps with \"lua51\" \"shorter hyperlinks\".
-For the full list of supported window command characters - and
-how to extend it - see the source:
- (find-eev \"eev-multiwindow.el\")
+Shorter hyperlinks
+==================
+How can we generate the definitions for `find-lua51file' and
+`find-lua51w3m' from just the strings \"lua51\" and
+\"~/usrc/lua-5.1.4/\"? Try this:
+ (find-code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")
+you will get a temporary buffer with a lot of Lisp code -
+including a definition for `find-lua51file' and another one for
+`find-lua51w3m'. That Lisp code has not been executed yet; the
+function `find-code-c-d' is just for debugging, and we can regard
+it as a hyperlink to the code that this sexp would execute:
-3. High-level words
-===================
-Very often we want to create window setups like
+ (code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")
+
+So, to define a family of functions including `find-lua51file'
+and `find-lua51w3m', for a given \"mnemonic\" - \"lua51\" in this
+case - and a given \"directory\" - \"~/usrc/lua-5.1.4/\" - we run
+this:
- _______________ _______________
- | | | | | |
- | | | | | B |
- | A | B | or | A |_______| ;
- | | | | | |
- | | | | | C |
- |_______|_______| |_______|_______|
+ (code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")
-there are shorthands for that. If you run
+which generates a block of Lisp code, as a string, and evaluates
+it. Note: the original (and rather confusing) terminology for the
+\"mnemonic\" was \"code\"; that's why the \"c\" in `code-c-d'.
- (find-2a sexpA sexpB)
-that will create a window setting like the one at the left above,
-initially with two copies of the current buffer, then will run
-sexpA at the window \"A\" and sexpB at the window \"B\", and
-finally will select the window \"A\", i.e., leave the cursor at
-the window at the left; this
- (find-2b sexpA sexpB)
+Extra arguments to `code-c-d'
+=============================
+`code-c-d' supports extra arguments - for example, this works:
-will do exactly the same as the `(find-2a ...)' above, but will
-select the window \"B\" - the one at the right - at the end of
-the process. For three-window settings we have these:
+ (find-code-c-d \"el\" \"~/usrc/emacs/lisp/\" :info \"elisp\")
- (find-3a sexpA sexpB sexpC)
- (find-3b sexpA sexpB sexpC)
- (find-3c sexpA sexpB sexpC)
+Look at the end of the generated code and you will see that it
+has a definition for `find-elnode' - such that
-all three create the three-window setting at the right above,
-initially with all three windows displaying the current buffer,
-then run sexpA at the window \"A\", sexpB at the window \"B\",
-and sexpC at the window \"C\"; the difference is that find-3a
-selects the window \"A\", find-3b the window \"B\", find-3c the
-window \"C\".
+ (find-elnode \"Constant Variables\")
+is a shorthand (a \"shorter hyperlink\") for:
+ (find-node \"(elisp)Constant Variables\")
+What is important to understand here is how these definitions
+with extra arguments are structured - so that you will be able to
+understand the source code when you need to. Both `code-c-d' and
+`find-code-c-d' are defined with a `&rest' in their argument
+lists, like this (NOTE: do not execute these defuns!):
-4. Several eepitch targets
-==========================
-If we try to build a window setup like this one, with two eepitch
-targets, with just `find-wset', we will run into problems -
+ (defun code-c-d (c d &rest rest) ...)
+ (defun find-code-c-d (c d &rest rest) ...)
- ________________________
- | | |
- | | *shell* |
- | script |_____________|
- | | |
- | | *shell 2* |
- |__________|_____________|
+and they both invoke `ee-code-c-d', which does all the template
+work and returns a big string; `ee-code-c-d' passes its `rest'
+argument to a recursive function called `ee-code-c-d-rest', and
+for each one of the suported keywords there is a corresponding
+function, also recursive; for `:info' it is called
+`ee-code-c-d-:info'. Their specifications are like this:
-because `(eepitch-shell)' and `(eepitch-shell2)' try to create a
-shell buffer and put it in an _another_ window, not the one we
-are in... one solution is to call the `(eepitch-*)' sexps inside
-an `ee-here', like this:
+ (defun ee-code-c-d (c d &rest rest) ...)
+ (defun ee-code-c-d-rest (rest) ...)
+ (defun ee-code-c-d-:info (manual &rest rest) ...)
- (ee-here '(eepitch-shell))
- (ee-here '(eepitch-shell2))
+and one very non-obvious trick is used to make the code short.
+When `ee-code-c-d-rest' and `ee-code-c-d-:info' are run they can
+access the values the `c' and the `d' that were passed to
+`ee-code-c-d' (due to dynamic scoping), so `c' and `d' do not
+need to be passed down explicitly as arguments.
-where `ee-here' is a hack that runs a sexp in a way that
-preserves the current window configuration, then switches the
-buffer in the current selected window to the current eepitch
-target. We can use this to create the window setting above,
+Try:
- (find-wset \"13o2_o_o\"
- ' (ee-here '(eepitch-shell))
- ' (ee-here '(eepitch-shell2))
- )
+ (find-code-c-d \"CODE\" \"/DIR/\" :info \"INFO\")
-This is too long - and would make a very bad one-liner - but
-there are two shorthands. First, \"e\" is a variant of \"_\" that
-runs its sexp inside an `(ee-here ...) - so this is equivalent
-the thing above,
- (find-wset \"13o2eoeo\"
- '(eepitch-shell)
- '(eepitch-shell2)
- )
-Second, these things are useful enough to deserve a high-level
-word, so this is equivalent to:
- (find-3ee '(eepitch-shell) '(eepitch-shell2))
+Other similar functions
+=======================
+See: (find-brxxx-intro)
+ (find-pdf-like-intro)
+ (find-audiovideo-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)
-5. Restarting eepitch targets
-=============================
-Sometimes we want to do the same as above, but restarting both
-eepitch targets, i.e., something like this:
- (find-3ee '(progn (eepitch-shell) (eepitch-kill) (eepitch-shell))
- '(progn (eepitch-shell2) (eepitch-kill) (eepitch-shell2))
- )
-There's a variant of `ee-here' that does that: `ee-here-reset'.
-For example,
- (ee-here-reset '(eepitch-shell2))
+;;; _ _
+;;; _ __ ___ _ __ ___ (_)_ __ | |_ _ __ ___
+;;; | '_ \/ __| '_ \ / _ \_____| | '_ \| __| '__/ _ \
+;;; | |_) \__ \ | | | __/_____| | | | | |_| | | (_) |
+;;; | .__/|___/_| |_|\___| |_|_| |_|\__|_| \___/
+;;; |_|
+;;
+;; �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")
-is equivalent to:
+(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.
- (ee-here '(progn (eepitch-shell2) (eepitch-kill) (eepitch-shell2)))
-and the letter \"E\" is a variant of \"e\" that uses
-`ee-here-reset' instead of `ee-here'; also, `find-3EE' is a
-variant of `find-3ee' that restarts both targets. Let's adapt
-this example,
- (find-eepitch-intro \"Other targets\")
-to make it show the two eepitch targets at once in a three-window
-settings. It becomes:
+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-3EE '(eepitch-shell) '(eepitch-python))
(eepitch-shell)
-echo Hello... > /tmp/o
- (eepitch-python)
-print(open(\"/tmp/o\").read())
+ (eepitch-kill)
(eepitch-shell)
-echo ...and bye >> /tmp/o
- (eepitch-python)
-print(open(\"/tmp/o\").read())
+ 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
- Now compare:
- (eek \"C-x 1\")
- (find-3ee '(eepitch-shell) '(eepitch-python))
- (find-3EE '(eepitch-shell) '(eepitch-python))
+ # (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.
-6. Non-trivial examples
-========================
-See:
- (find-prepared-intro \"An `ee' for Python\")
- (find-rcirc-intro \"The server buffer and the channel buffers\")
+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.
-7. Eepitch blocks for two targets
-=================================
-An eepitch script with two targets uses several different kinds
-of red star lines - `(eepitch-target1)', `(eepitch-target2)',
-`(find-3EE ...)', `(find-3ee ...)', etc. We don't want to have to
-type all those by hand, so there is a hack similar to `M-T' that
-generates all those kinds from just \"target1\" and \"target2\"
-to let us just copy around the sexps we need. It is bound to
-`meta-shift-3', which Emacs sees as `M-#'. Compare the result of
-typing `M-T' here,
+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.
-python
+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\".
-with the result of typing `M-#' on this line,
-shell python
-which yield this:
- (find-3EE '(eepitch-shell) '(eepitch-python))
- (find-3ee '(eepitch-shell) '(eepitch-python))
- (eepitch-shell)
- (eepitch-python)
+The new way: M-x brep
+=====================
+Try to run this:
-Note that we use to `find-3EE' to restart targets instead of
-`eepitch-kill' (this is non-trivial - think about it =/)...
+ (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
-8. Adding support for new characters in `find-wset'
-===================================================
-The standard characters supported by `find-wset' are these:
+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.
- char action key
- ---- ---------------------------- ---------
- `1' `delete-other-windows' (C-x C-1)
- `2' `split-window-vertically' (C-x C-2)
- `3' `split-window-horizontally' (C-x C-3)
- `s' `split-window-sensibly'
- `o' `other-window' (C-x o)
- `+' `balance-windows' (C-x +)
- `_' execute the next sexp
-but the action of each one is defined in a different function,
-and to add support for a new character, say, `=', we just need to
-define a function with the right name - in this case,
-`find-wset-='.
-The source code is simple enough, so take a look:
+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-eev \"eev-multiwindow.el\" \"find-wset-_\")
- (find-eev \"eev-multiwindow.el\" \"find-wset-=\")
- (find-eev \"eev-multiwindow.el\" \"find-wset-!\")
+ (find-bgprocess \"xterm\")
+ (find-bgprocess \"gnome-terminal\")
+ (find-bgprocess \"eterm\")
-Note that `find-wset-!' restarts an eepitch target, while
-`find-wset-=' will reuse an eepitch target if its buffer already
-exists. [Obs: \"=\" and \"!\" have been mostly superseded by
-\"e\" and \"E\"... to do: explain this]
+will then inherit that value. Try it:
+ (getenv \"S\")
+ (find-sh0 \"echo $S\")
-See: (find-prepared-intro)
+ (eepitch-shell)
+ (eepitch-kill)
+ (eepitch-shell)
+echo $S
- [Example at find-prepared-intro]
+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.
-9. Executing key sequences at other windows
-===========================================
-It is possible to use multi-window settings, together with the
-trick that `<f8>' on a red star line executes it as Lisp and
-moves down, to create tutorials for Emacs modes. An example:
+`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
-10. A tutorial for Info mode
-============================
-Here's a mini-tutorial for Info mode, demonstrating how to
-navigate in Info using the usual movement keys, plus TAB,
-<backtab>, RET, l (last), u (up), n (next), p (prev), q (quit),
-C-h i, and the digits 1-9. Note that the display in Info mode is
-like this:
+and then run `M-x browse-url' on it.
- ____________________________________________
- |Next: Nonincremental Search, Up: Search | <- next/prev/up
- | (emacs)Top > Search > Incremental Search | <- breadcrumbs
- | |
- | 19.1 Incremental Search | <- section number /
- | | node name (long)
- | (...) |
- | |
- |--:%%- *info* (emacs) Incremental Search |
- |____________________________________________|
+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:
-Here:
+ http://www.gnu.org/software/emacs/emacs-paper.html
+ (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
- Define some hacks
- (defun ow (n) (other-window n))
- (defun eeoe (code) (ow 1) (prog1 (eval code) (ow -1)))
- (defun eeok (keystr) (eeoe `(eek ,keystr)))
-
- Prepare the windows
- (ee-kill-buffer \"*info*\")
- (find-wset \"1so_o\" '(find-enode \"Search\"))
-
- The arrows (and other movent keys) work as expected.
- Watch the cursor in the Info window...
- (eeok \"3*<down>\")
- (eeok \"10*<right>\")
-
- TAB and <backtab> move to the next and to the previous link.
- Note that they consider all the links in a page, not only
- the ones in menus - including the breadcrumb links at the top.
- (eeok \"TAB ;; Info-next-reference\")
- (eeok \"TAB ;; Info-next-reference\")
- (eeok \"TAB ;; Info-next-reference\")
- (eeok \"TAB ;; Info-next-reference\")
- (eeok \"TAB ;; Info-next-reference\")
- (eeok \"<backtab> ;; Info-prev-reference\")
- (eeok \"<backtab> ;; Info-prev-reference\")
- (eeok \"<backtab> ;; Info-prev-reference\")
- (eeok \"<backtab> ;; Info-prev-reference\")
-
- RET follows a link, l (last) goes back.
- Watch the section number: 19 -> 32.3.6 -> 19.
- (eeok \"RET ;; Info-follow-nearest-node\")
- (eeok \"l ;; Info-history-back\")
-
- The digits 1-9 can be used to go straight to subsections.
- For example, a `4' would follow the 4th _menu_ link -
- ignoring the non-menu links.
- Watch the section number: 19 -> 19.1 -> 19.1.1.
- (eeok \"1 ;; Info-nth-menu-item\")
- (eeok \"1 ;; Info-nth-menu-item\")
-
- The keys `u', `n', `p' (up, next, and prev) move through the
- tree structure. Watch the section number:
- 19.1.1 -u-> 19.1 -u-> 19 -n-> 20 -n-> 21 -p-> 20 -p-> 19
- (eeok \"u ;; Info-up\")
- (eeok \"u ;; Info-up\")
- (eeok \"n ;; Info-next\")
- (eeok \"n ;; Info-next\")
- (eeok \"p ;; Info-prev\")
- (eeok \"p ;; Info-prev\")
-
- `q' leaves Info mode - more precisely, it buries the info buffer.
- `C-h i' goes back to the Info buffer (or restarts info).
- (eeok \"q ;; Info-exit\")
- (eeok \"C-h i ;; info\")
+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:
-" pos-spec-list)))
+ \"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.
-;; (find-multiwindow-intro)
+The details on how to create these \"brxxx functions\" are here:
+ (find-brxxx-intro)
+" rest)))
-;;; _
-;;; _ __ ___(_)_ __ ___
-;;; | '__/ __| | '__/ __|
-;;; | | | (__| | | | (__
-;;; |_| \___|_|_| \___|
-;;;
-;; �find-rcirc-intro� (to ".find-rcirc-intro")
-;; (find-intro-links "rcirc")
+;; (find-enode "Command Index" "browse-url")
+;; (find-efunction 'browse-url)
+;; (find-elnode "System Environment")
+;; (find-enode "Environment")
+;; (find-eevfile \"eev.el\" \"$HOME/snarf\")
-(defun find-rcirc-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-rcirc-intro)*"))
+;; (find-psne-intro)
+
+
+
+
+;;; _ _ _
+;;; | |__ _ ____ ____ ____ __ (_)_ __ | |_ _ __ ___
+;;; | '_ \| '__\ \/ /\ \/ /\ \/ /____| | '_ \| __| '__/ _ \
+;;; | |_) | | > < > < > <_____| | | | | |_| | | (_) |
+;;; |_.__/|_| /_/\_\/_/\_\/_/\_\ |_|_| |_|\__|_| \___/
+;;;
+;; �find-brxxx-intro� (to ".find-brxxx-intro")
+
+(defun find-brxxx-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-brxxx-intro)*"))
(apply 'find-estring "\
-\(Re)generate: (find-rcirc-intro)
-Source code: (find-efunction 'find-rcirc-intro)
+\(Re)generate: (find-brxxx-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-brxxx-intro\")
More intros: (find-eev-quick-intro)
- (find-eev-intro)
(find-eval-intro)
(find-eepitch-intro)
This buffer is _temporary_ and _editable_.
@@ -3830,266 +3485,217 @@ Is is meant as both a tutorial and a sandbox.
-Recent versions with Emacs come with two IRC clients built-in:
-Rcirc and ERC. I never understood ERC well enough, and I found
-Rcirc quite easy to understand and to hack, so eev has some
-support for Rcirc (and no support for ERC).
-
+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\")
-The server buffer and the channel buffers
-=========================================
-If you type `M-6 M-6 M-j' - or `M-e' on the line below - then eev
-runs this,
+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:
- (find-freenode-3a \"#eev\")
+ brxxx-function base function
+ -------------- -------------
+ brep find-psne-links
+ brfl find-fline
-which tells Emacs to connect to Freenode and to the channel #eev,
-using this window setting:
+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.
- _________________________
- | | |
- | | Freenode |
- | | server |
- | | messages |
- | current |_____________|
- | buffer | |
- | | #eev |
- | | channel |
- | | |
- |___________|_____________|
-You will then be able to watch the process of connecting to
-Freenode, which takes about 20s on my machine, by the messages
-that will appear at the Freenode server buffer; at some point
-rcirc will be allowed by the server to connect to channels, it
-will request to connect to the channel #eev, and some login
-messages, plus at list of all users connected to #eev and a
-prompt, will appear at the #eev channel buffer.
-`M-66j' is mostly for establishing a connection to an IRC server
-and watching if any errors occur; once we know that we are
-connected we can use `M-6j' - with just one `M-6' - which just
-takes us to the #eev channel without changing the current window
-configuration. A mnemonic: `M-66j', which is one keypress longer,
-is to be used less often - essentially only once per session, or
-when we want to check the status of our connection to Freenode.
+2. A first example
+==================
+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.
-Messages and commands
-=====================
-IRC is a command-line-ish protocol, in which lines starting with
-\"/\" are treated as commands and other lines as messages. A
-message typed at the #eev channel buffer is broadcast to all
-other users also connected to #eev; some commands, like
+These two calls,
- /join #emacs
+ (code-brurl 'foo-url :remote 'brshowu :local 'brshowul)
+ (code-brfile 'foo-file :local 'brshowfl)
-work in the same way no matter where they are typed, while
-others, like for example \"/part\", work differently when typed
-in #eev than when in #emacs. See:
+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-rcircnode \"rcirc commands\" \"/join #emacs\")
- (find-rcircnode \"rcirc commands\" \"/part\")
+ (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\";
-Other channels
-==============
+ (foo-file \"/c/d/e/f\")
+ => \"Got filename: /c/d/e/f\"
-where `find-freenode-3a' is based on `find-3a', described here:
+ (brshowu \"http://a/b\";)
+ => `(foo-url \"http://a/b\";) -> \"Got URL: http://a/b\";'
- (find-multiwindow-intro \"High-level words\")
+ (brshowul \"http://a/b\";)
+ => `(foo-url \"file:///home/edrx/snarf/http/a/b\") ->
+ \"Got URL: file:///home/edrx/snarf/http/a/b\"'
- (find-eev \"eev-rcirc.el\")
+ (brshowfl \"http://a/b\";)
+ => `(foo-file \"/home/edrx/snarf/http/a/b\") ->
+ \"Got filename: /home/edrx/snarf/http/a/b\"'
-If you are new to IRC
-=====================
-Most of the discussions between Free Software developers still
-happen in IRC channels, and mostly at Freenode. The best way to
-understand what IRC is - for modern people, I mean - is probably
-to try this first:
+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://webchat.freenode.net/
+ http://a/b
-IRC is a command-line-ish protocol, in which lines starting with
-\"/\" are treated as commands and other lines are messages to be
-broadcast. Try to \"/join\" the channels \"#emacs\" and \"#eev\",
-with \"/join #emacs\" and \"/join #eev\"; in that webchat, try to
-switch between the channels you're connected to by clicking on
-the tabs at the top - and note that there is also a tab for a
-channel-ish thing that has only messages from the server. Try
-also to leave these channels with \"/part\", \"/part #emacs\",
-\"/part #eev\".
+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.
-In Rcirc each one of these channels, including the server
-channel, becomes an Emacs buffer. The names of these buffers will
-be:
- *irc.freenode.net*
- address@hidden
- address@hidden
- (defun eejump-66 () (find-freenode-3a \"#eev\"))
-For more information see:
+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:
- (find-node \"(rcirc)Top\")
- (find-node \"(rcirc)Internet Relay Chat\")
- (find-node \"(rcirc)rcirc commands\")
- http://www.emacswiki.org/emacs/RcIrc
- http://www.irchelp.org/
+ http://a/b -> $S/http/a/b -> file:///home/edrx/snarf/http/a/b
+ /tmp/c -> file:///tmp/c
- (find-node \"(erc)Top\")
- http://www.emacswiki.org/emacs/ErC
+try:
-" pos-spec-list)))
+ (ee-url-to-fname \"http://a/b\";)
+ (ee-fname-to-url \"/tmp/c\")
+ (ee-url-to-local-url \"http://a/b\";)
-;; (find-rcirc-intro)
+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)
-;;; _ _ _
-;;; | |_ ___ _ __ ___ _ __ | | __ _| |_ ___ ___
-;;; | __/ _ \ '_ ` _ \| '_ \| |/ _` | __/ _ \/ __|
-;;; | || __/ | | | | | |_) | | (_| | || __/\__ \
-;;; \__\___|_| |_| |_| .__/|_|\__,_|\__\___||___/
-;;; |_|
-;;
-;; �find-templates-intro� (to ".find-templates-intro")
-;; (find-intro-links "templates")
-(defun find-templates-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-templates-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-templates-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-templates-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.
+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:
-`ee-template0'
-==============
-\(find-efunctiondescr 'ee-template0)
-\(find-efunction 'ee-template0)
+ \"\" - 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:
-`ee-H', `ee-S', `ee-HS'
-=======================
+ 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\"
+In our example with `foo-url' and `foo-file' we had:
+ Base function receives stem
+ ------------- -------- ----
+ foo-url URL showu
+ foo-file file name showf
-`find-find-links-links'
-=======================
-\(find-links-intro)
-\(find-find-links-links)
-\(find-efunction 'ee-stuff-around-point)
-interactive
-`find-elinks'
-=============
-\(find-efunction 'find-elinks)
+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
- (find-intro-links)
-\(find-eev \"eev-tlinks.el\" \"find-intro-links\")
-\(find-eevfile \"eev-tlinks.el\")
+ (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 innards: templates
-======================
-Several functions in eev besides `code-c-d' work by replacing
-some substrings in \"templates\"; they all involve calls to
-either the function `ee-template0', which is simpler, or to
-`ee-template', which is much more complex.
-The function `ee-template0' receives a single argument - a
-string, in which each substring surrounded by `{...}'s is to be
-replaced, and replaces each `{...}' by the result of evaluating
-the `...' in it. For example:
- (ee-template0 \"a{(+ 2 3)}b\")
- --> \"a5b\"
+6. The dired variation
+======================
-Usually the contents of each `{...}' is the name of a variable,
-and when the result of evaluating a `{...}' is a string the
-replacement does not get `\"\"'s.
+In dired mode each line corresponds to a file
-The function `ee-template' receives two arguments, a list and a
-template string, and the list describes which `{...}' are to be
-replaced in the template string, and by what. For example, here,
- (let ((a \"AA\")
- (b \"BB\"))
- (ee-template '(a
- b
- (c \"CC\"))
- \"_{a}_{b}_{c}_{d}_\"))
-
- --> \"_AA_BB_CC_{d}_\"
-
-the \"{d}\" is not replaced. Note that the list (a b (c \"CC\"))
-contains some variables - which get replaced by their values -
-and a pair, that specifies explicitly that every \"{c}\" should
-be replaced by \"CC\".
-
-
-
-
-Templated buffers
-=================
-Introduction
-Conventions:
- the first line regenerates the buffer,
- buffer names with \"**\"s,
- (find-evariable 'ee-buffer-name)
- code
-
-`find-elinks'
-=============
-Variant: `find-elinks-elisp'
-
-`find-e*-links'
-===============
-\(find-eev \"eev-elinks.el\")
-
-`find-*-intro'
-==============
-
-`eewrap-*'
-==========
-
-Experiments
-===========
-\(find-efunction 'find-youtubedl-links)
-\(find-efunction 'ee-hyperlinks-prefix)
-\(find-efunction 'find-newhost-links)
-\(find-efunction 'find-eface-links)
- Note that there is no undo.
" rest)))
-;; (find-templates-intro)
+;; (find-brxxx-intro)
-;; �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\")
+;;; _
+;;; ___ ___ (_)_ _ _ __ ___ _ __
+;;; / _ \/ _ \| | | | | '_ ` _ \| '_ \
+;;; | __/ __/| | |_| | | | | | | |_) |
+;;; \___|\___|/ |\__,_|_| |_| |_| .__/
+;;; |__/ |_|
+;;
+;; (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)
@@ -4098,3066 +3704,3410 @@ Is is meant as both a tutorial and a sandbox.
-NOTE: This has been mostly superseded by:
-(find-eev-quick-intro \"8. Anchors\")
+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,
+ 1) we want our list of files to be preserved between one Emacs
+ session and another,
+ 2) we know that each \"visit a file\" command will correspond
+ to an elisp hyperlink.
-Introduction: `ee-anchor-format' and `to'
-=========================================
-A hyperlink like
+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':
- (to \"foo\")
+ (find-efunction 'find-efunction)
+ (eek \"M-h M-f find-efunction\")
-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:
+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:
- ee-anchor-format
- (format ee-anchor-format \"foo\")
- (ee-goto-position (format ee-anchor-format \"foo\"))
+ 3) it should be possible to jump straight to any of the files
+ in the list, and with very few keystrokes,
-We will call strings in `��'s _anchors_, and we will say
-that `(to \"foo\")' jumps \"to the anchor `foo'\".
+ 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,
-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.
+ 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.
-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\")
+
+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):
-For historical reasons, the glyphs for `�' and `�' defined in
+ ;; 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))))
- (find-eev \"eev-anchors.el\")
+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...
-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�\".
+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...
-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,
+Families
+========
+Let's use a shorthand for key sequences: for example, `M-123j'
+instead of `M-1 M-2 M-3 M-j'.
- �one� (to \"two\")
- �two� (to \"one\")
+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.
-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_.
+The definition of `eejump-simplified' given above does not
+satisfy these two (new!) wishlist items:
-In a case like this,
+ 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,
- �.three� (to \"three\")
- �three� (to \".three\")
+ 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).
-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\")
+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.
-Creating index/section anchor pairs
-===================================
-Use `M-A' (`eewrap-anchor'). Note that this has been briefly
-mentioned here:
+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-wrap-intro \"All wrapping functions\")
+ (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*)
-It will convert a line with a syntax like
-
- comment-prefix <anchor-name>
+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\"...
-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.
+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\".
-find-anchor
-===========
-\(find-eev \"eev-anchors.el\")
-\(find-eev \"eev-anchors.el\" \"find-anchor\")
+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*\")
-code-c-d and :anchor
-====================
-\(find-eev \"eev-code.el\" \"ee-code-c-d-:anchor\")
+You should probably copy them to your .emacs, and then start
+modifying them.
-
-# Local Variables:
-# coding: raw-text-unix
-# ee-anchor-format: \"�%s�\"
-# End:
-" rest)))
-;; (find-anchors-intro)
+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:
-;;; _
-;;; _ __ _ __ ___ _ __ __ _ _ __ ___ __| |
-;;; | '_ \| '__/ _ \ '_ \ / _` | '__/ _ \/ _` |
-;;; | |_) | | | __/ |_) | (_| | | | __/ (_| |
-;;; | .__/|_| \___| .__/ \__,_|_| \___|\__,_|
-;;; |_| |_|
-;;
-;; �find-prepared-intro� (to ".find-prepared-intro")
-;; (find-eev "eev-bounded.el")
+ 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!),
-(defun find-prepared-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-prepared-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-prepared-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-prepared-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.
+ 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\")
-Prepared shells
-===============
-Long before eepitch had been created, eev had another way -
-technically much simpler, but clumsier from the user's point of
-view - to send commands to external shells (and other shell-like
-programs; but to simplify we will say just \"shells\"). Here is
-an overview of how it worked: if the user marked the three lines
-below,
+ if that concept is not totally familiar to you.
- rm -Rv /tmp/foo
- mkdir /tmp/foo/
- cd /tmp/foo/
+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:
-and typed `M-x eev' (which stood for \"Emacs-execute-verbosely\")
-then Emacs would save those three lines into a temporary script
-file, usually \"~/.eev/ee.sh\"; that would be just half of
-\"sending commands to an external shell\", and for the other half
-the user would have to go to an external prepared shell - that
-would usually be running in an xterm, and totally independent
-from Emacs - and type \"ee\" there. The shell had to be
-\"prepared\" in the sense that it would understand the \"ee\"
-command correctly, as meaning: \"execute the commands in the
-temporary script as if the user were typing them at the prompt\".
-Technically, that would mean that instead of calling
-\"~/.eev/ee.sh\" as a shell script its contents would be
-\"sourced\" - i.e., executed in the current shell context - and
-in verbose mode.
+ (find-elnode \"Where Defined\")
-Usually we would prepare bash by patching the file ~/.bashrc and
-putting the definition for \"ee\" there. We will discuss how to
-do that later; now let's test a simple environment in which `M-x
-eev' and \"ee\" work. First execute these two sexps:
- (make-directory \"~/.eev/\" 'force)
- (eev \"rm -Rv /tmp/foo\\nmkdir /tmp/foo/\\ncd /tmp/foo/\\n\")
-Now run this script
+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:
- (eepitch-bash)
- (eepitch-kill)
- (eepitch-bash)
-export PS1='$PWD# '
-function ee () { set -v; . ~/.eev/ee.sh; set +v; }
+ 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.
-`ee'
-====
-\[Explain how several interpreters can be programmed to accept
-an `ee' command to execute temporary scripts\]
+ a b c d
+ a b c
+ a b
+ a
- http://angg.twu.net/eev-article.html#making-progs-receive-cmds
- (find-eev \"eev-langs.el\")
- (find-eev \"eev-bounded.el\")
- (find-eev \"eev-rctool\")
+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'.
-An `ee' for Python
-==================
-Here is a simple way to make Python execute commands saved in a
-temporary script when the user types `ee()' (note that it is not
-just `ee' - the `()' is needed). We will show first an example in
-which the temporary script is prepared by running \"cat\" from a
-shell - then we will explain a more user-friendly way to save a
-region from the current buffer as the temporary script.
-Note that the demo below uses `find-wset', which is an
-advanced (i.e., hackish) feature explained here:
- (find-multiwindow-intro \"Several eepitch targets\")
+# Local Variables:
+# coding: raw-text-unix
+# ee-anchor-format: \"%s\"
+# End:
+" rest)))
- (find-3EE '(eepitch-shell) '(eepitch-python))
- (find-3ee '(eepitch-shell) '(eepitch-python))
- (eepitch-python)
-import os
-def ee():
- execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())
+;; (find-eejump-intro)
- (eepitch-shell)
-cat > ~/.eev/ee.py <<'%%%'
-print(1+2)
-%%%
- (eepitch-python)
-ee()
- (eepitch-shell)
-cat > ~/.eev/ee.py <<'%%%'
-def foo (x):
- return x*x
-print foo(5)
-%%%
+;;; _ __ _ _ _
+;;; _ __ __| |/ _| | (_) | _____
+;;; | '_ \ / _` | |_ _____| | | |/ / _ \
+;;; | |_) | (_| | _|_____| | | < __/
+;;; | .__/ \__,_|_| |_|_|_|\_\___|
+;;; |_|
+;;
+;; �find-pdf-like-intro� (to ".find-pdf-like-intro")
- (eepitch-python)
-ee()
-print(foo(6))
+(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.
-`eepy'
-======
-The function `eev' receives three parameters, called `s', `e', and
-`altfile'; `e' and `altfile' are optional, and `s' should be either a
-string or a number. When `s' is a string, then the commands to be
-saved into the temporary script are taken from `s'; the numeric case
-will be discussed later.
-A call to
+PDF-like documents
+==================
+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,
- (eev \"print(1+2)\" nil \"~/.eev/ee.py\")
+ (find-enode \"Document View\")
-writes \"print(1+2)\" (with an added trailing newline, but that's
-a technical detail) into the \"alternative file\"
-\"~/.eev/ee.py\" - the default would be \"~/.eev/ee.sh\". We can
-that to simplify our demo a bit:
+but we will see a more eev-like way of pointing to pages of
+PDF-like documents.
- (eek \"C-x 1\")
- (eepitch-python)
- (eepitch-kill)
- (eepitch-python)
-import os
-def ee():
- execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())
- (eev \"print(1+2)\" nil \"~/.eev/ee.py\")
-ee()
- (eev \"def foo (x):\\n return x*x\\n\\nprint foo(5)\" nil
\"~/.eev/ee.py\")
-ee()
-print(foo(6))
- In the example below the first line defines a `eepy' in a
- simplistic way:
+Two test documents
+==================
+The following script creates two PDF-like documents - a DVI and a
+PDF - that we will use in the examples below.
- (defun eepy (s &optional e) (eev s e \"~/.eev/ee.py\"))
- (eek \"C-x 1\")
- (eepitch-python)
+ (eepitch-shell)
(eepitch-kill)
- (eepitch-python)
-import os
-def ee():
- execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())
-
- (eepy \"print(1+2)\")
-ee()
- (eepy \"def foo (x):\\n return x*x\\n\\nprint foo(5)\")
-ee()
-print(foo(6))
+ (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
-`M-x eepy' and `M-x eev'
-========================
-Now let's define a more realistic `eepy' - one that can also be
-called interactively. We want `M-x eepy' to save the current
-_region_ into the temporary script; `eepy' has to be a _command_,
-and we will use the argument \"r\" to its `interactive' clause,
-to make the function `eepy' receive two numbers - the start and
-the end of the region - and it will pass these two numbers to
-`eev'.
- (defun eepy (s &optional e)
- \"Save the region between S and E (or the string S) into ~/.eev/ee.py .\"
- (interactive \"r\")
- (eev s e \"~/.eev/ee.py\"))
-When the first argument, `s', to `eev', is a number, not a
-string, then `eev' expects the second argument, `e', to also be a
-number - and then `s' and `e' are considered as the extremities
-of a region of text in the current buffer. This idea - that the
-first argument can be either a string or a number - comes from:
+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':
- (find-efunctiondescr 'write-region \"If START is a string\")
+ (find-bgprocess '(\"xdvi\" \"+4\" \"/tmp/foo.dvi\"))
+ (find-bgprocess '(\"xpdf\" \"/tmp/foo.pdf\" \"4\"))
-But try these:
+Alternatively, we can invoke these viewers like this,
- (ee-se-to-string \"foo\" nil)
- (ee-se-to-string-with-nl \"foo\" nil)
- (ee-se-to-string \"foo\\n\" nil)
- (ee-se-to-string-with-nl \"foo\\n\" nil)
- (ee-se-to-string (- (point) 5) (point))
- (ee-se-to-string-with-nl (- (point) 5) (point))
- (ee-se-to-string (point) (- (point) 5))
- (ee-se-to-string-with-nl (point) (- (point) 5))
+ (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\".
-\[Garbage:\]
+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\".
- (find-elnode \"Defining Commands\")
- (find-defun-intro \"\\ninteractive\\n\")
- (find-efunction 'eev)
-" rest)))
-;; (find-prepared-intro)
-;; (find-bashnode "Bourne Shell Builtins" "current shell context")
+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',
+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\".
-;;; _ _ _
-;;; | |__ ___ _ _ _ __ __| | ___ __| |
-;;; | '_ \ / _ \| | | | '_ \ / _` |/ _ \/ _` |
-;;; | |_) | (_) | |_| | | | | (_| | __/ (_| |
-;;; |_.__/ \___/ \__,_|_| |_|\__,_|\___|\__,_|
-;;;
-;; �find-bounded-intro� (to ".find-bounded-intro")
-;; (find-intro-links "bounded")
-(defun find-bounded-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-bounded-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-bounded-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-bounded-intro\")
-More intros: (find-eev-quick-intro)
- (find-eev-intro)
- (find-eval-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
-Note that you need to understand the concept of \"prepared
-shells\" quite well to be able to use this... see:
+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:
- (find-prepared-intro)
+ 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)
-Bad news: I've been using this feature very little, and I have
-not yet adapted the old, crappy docs to the new \"intro\"
-format... =\\ So this is just a bunch of notes!
+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').
-Source code: \(find-eev \"eev-bounded.el\")
-Obsolete related code: \(find-eev \"eev-langs.el\")
-Old mentions to this: \(find-TH \"eev-article\" \"delimited-regions\")
- http://angg.twu.net/eev-article.html#delimited-regions
+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:
-Delimited (\"bounded\") regions
-===============================
-Try:
+ (find-pdftotext-text \"/tmp/foo.pdf\")
+ (find-djvutxt-text \"/tmp/foo.djvu\")
-#
-# (eev-bounded)
-cd
-echo At: $PWD
-cd /tmp/
-echo At: $PWD
+We can also use the correspondent generic medium-level words,
+that are aliases to the default converters:
-#
-%
-% (eelatex-bounded)
+ (find-pdf-text \"/tmp/foo.pdf\")
+ (find-djvu-text \"/tmp/foo.djvu\")
-Hello
+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\")
+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:
-Defining new bounded functions
-==============================
-Try:
+ (find-pdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
- (find-code-bounded 'eev-bounded 'eev \"\\n#\\n\")
- (find-code-bounded 'eev-bounded 'eev 'ee-delimiter-hash)
+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:
-as usual, when we remove the \"find-\"s the generated code is
-executed instead of displayed.
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
+to this:
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
+ (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+is a special case of \"refining hyperlinks\", an idea that we saw
+in:
-The default bounded function
-============================
-...is stored in the variable `ee-bounded-function', and can be
-re-run with `M-x ee-bounded-function' (i.e., there's a function
-with the same name as the variable). I used to bind `f3' to that,
-but in modern Emacsen this is bound to a macro key:
+ (find-eval-intro \"Refining hyperlinks\")
- (find-enode \"Basic Keyboard Macro\" \"<F3>\")
-so you should do something like this, but for your favourite key:
- (define-key eev-mode-map [f3] 'ee-bounded-function)
-" pos-spec-list)))
-;; (find-bounded-intro)
+High-level hyperlinks to pdf-like documents
+===========================================
+By executing
+ (code-pdf \"fp\" \"/tmp/foo.pdf\")
+ (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+we can use shorter hyperlinks, like
+ (find-fppage (+ 3 1) \"Chapter 1\")
+ (find-fptext (+ 3 1) \"Chapter 1\")
-;;; _ _
-;;; ___| |__ __ _ _ __ _ __ ___| |___
-;;; / __| '_ \ / _` | '_ \| '_ \ / _ \ / __|
-;;; | (__| | | | (_| | | | | | | | __/ \__ \
-;;; \___|_| |_|\__,_|_| |_|_| |_|\___|_|___/
-;;;
-;; �find-channels-intro� (to ".find-channels-intro")
-;; (find-intro-links "channels")
+instead of the longer forms with `find-pdf-page' and
+`find-pdf-text'. This works exactly like `code-c-d', as explained
+here:
-(defun find-channels-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-channels-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-channels-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-channels-intro\")
-More intros: (find-eev-quick-intro)
- (find-eev-intro)
- (find-eval-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
+ (find-code-c-d-intro)
+Try these sexps to see the code that the `code-pdf' and the
+`code-pdf-text' above execute:
+ (find-code-pdf \"fp\" \"/tmp/foo.pdf\")
+ (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
-Introduction
-============
-Before eepitch had been invented, eev had two other ways to send
-commands to external shell-like programs. The first way,
-described here,
+There is a wrapping comand for producing these
+`code-pdf'/`code-pdf-text' pairs quickly - `M-P'. Try it here:
- (find-prepared-intro \"\\n`ee'\\n\")
+ fp /tmp/foo.pdf
-was technically very simple: running `M-x eev' would save a
-series of commands - usually the contents of the region - into a
-temporary script file, and then the user would type something
-like `ee' at the prompt of a (\"prepared\") shell; that would
-make it read the saved commands and execute them.
-Here we will describe the second of the Old Ways - one in which
-the target program, which is usually a shell running in an xterm,
-is sent a signal saying \"execute the command NOW\" as soon as a
-command is saved into a temporary file by Emacs. The difficulty
-is that this requires not only a directory for temporary files,
-but also an Expect script, which acts as an intermediary that
-listens to signals and handles them pretending that the saved
-commands came from the keyboard... and, as some people have said,
-this is \"a nightmare to set up\".
-Here we explain the protocol - which can be adapted to other
-cases too, like, for example, to make Emacs talk to SmallTalk
-environments and to computer algebra systems with GUIs - and we
-will present several tests that should help with troubleshooting.
+Producing and refining hyperlinks to pages
+==========================================
+We also have something like this
+ (find-eval-intro \"Producing and refining hyperlinks\")
-The innards
-===========
-Let's start with a detailed low-level view of of what we have
-just summarized as to \"save a command into a temporary file,
-then send a signal to the external program etc etc\".
+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.
-Warning: this document is still VERY INCOMPLETE, and some parts
-of it are just notes, drafts, and links that may not work for
-you... =(
+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-eev \"eegchannel\")
- (find-eev \"anim/\")
- (find-eev \"anim/channels.anim\")
- http://angg.twu.net/eev-current/eegchannel.html
+ (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:
+ (code-pdf \"fp\" \"/tmp/foo.pdf\")
+ (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+ (kill-new \"Two\")
+ (eek \"M-h M-p\")
+You should get a page with several hyperlinks to the \"current
+page\" of the current pdf-like document, including some like
+these:
+ (find-fppage 1)
+ (find-fptext 1)
+ (find-fppage (+ 3 -2))
+ (find-fptext (+ 3 -2))
-The protocol, in diagrams
-=========================
-Here's a diagram that shows roughly what we have when X is
-running both an Emacs and an xterm, each in a separate window.
-Many details have been omitted - for examples, the real
-communication happens through fifos and ptys, that are not shown
-- but it's easy to build a complete diagram from this. The arrows
-indicate flow of information.
+ (find-fppage 1 \"Two\")
+ (find-fptext 1 \"Two\")
+ (find-fppage (+ 3 -2) \"Two\")
+ (find-fptext (+ 3 -2) \"Two\")
- keyboard mouse display
- | | ^
- v v |
- +----------------------------+
- | |
- | X |
- | |
- +----------------------------+
- key/mouse | ^ display key/mouse | ^ display
- events v | commands events v | commands
- +---------+ +---------+
- | | | |
- | emacs | | xterm |
- | | | |
- +---------+ +---------+
- chars and | ^ chars and
- signals v | signals
- +---------+
- | |
- | sh |
- | |
- +---------+
+Where did the \"fp\", the \"1\", the \"3\", the \"-2\" and the
+\"Two\" above come from?
-To make the external shell at the right able to receive commands
-from Emacs we will insert a program between the \"xterm\" and the
-\"sh\" boxes - an Expect script called eechannel, that will
-usually be totally transparent, in the sense that it will let all
-the chars and signals that it receives pass through it without
-changes.
+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 trick is that \"eechannel\" will also be \"listening to
-commands from the outside\", according to the following protocol:
+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.
- 1) each instance of eechannel \"listens\" to a fixed, named
- \"channel\"; for simplicity, let's suppose that this name is
- \"A\".
+ (code-pdf \"debt\" \"~/books/graeber__debt.pdf\")
+ (code-pdf-text \"debt\" \"~/books/graeber__debt.pdf\" 8)
- 2) When an eechannel receives a signal SIGUSR1 it reads a
- string from the file \"eech.A.str\" and sends that to the
- shell, as if the user had typed that.
+ 1 1 On The Experience of Moral Confusion
+ 21 2 The Myth of Barter
+ 43 3 Primordial Debts
+ 73 4 Cruelty and Redemption
- 3) To make it simpler to send the signal, when eechannel starts
- up it saves its pid into the file \"eech.A.pid\".
+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
-That protocol can be depicted as the four horizontal arrows
-below; the temporal order is from top to bottom.
+ (find-debttext 7 \"Contents\")
- +-------------+
- | |
- | xterm |
- | |
- +-------------+
- +-----------+ | ^
- | | --> eeg.A.str v |
- | emacs | <-- eeg.A.pid +-------------+
- | | -----------------> | |
- +-----------+ eeg.A.str ---> | eechannel A |
- | |
- +-------------+
- | ^
- v |
- +-------------+
- | |
- | sh |
- | |
- +-------------+
+with a bit of fiddling by hand and keyboard macros. Keyboard
+macros are VERY useful; if you don't use them yet, see:
-When Emacs wants to send a line, say, \"cd /tmp/\", to eechannel,
-it does this:
+ (find-enode \"Keyboard Macros\")
+" rest)))
- 1) \"--> eeg.A.str \" writes \"cd /tmp/\" into eech.A.str,
- 2) \"<-- eeg.A.pid \" reads eechannel's pid from eech.B.str,
- 3) \"----------------->\" sends a signal SIGUSR1 to that pid,
- 4) \" eeg.A.str --->\" ...and when eechannel receives a SIGUSR1
- it reads the contents of eech.A.str and
- sends that to its spawned shell.
+;; (find-pdf-like-intro)
-Actually there's something else - how these programs are started.
-If we run just \"xterm\", it behaves in its default way, and runs
-a shell. But if we run
- \"xterm -e eechannel A /bin/sh\"
-then xterm runs \"eechannel A /bin/sh\" instead of just
-\"/bin/sh\"; and \"eechannel A /bin/sh\" runs \"/bin/sh\".
-Also, evaluating this
+;;; _ _ __ _ _
+;;; __ _ _ _ __| (_) ___ / /_ _(_) __| | ___ ___
+;;; / _` | | | |/ _` | |/ _ \ / /\ \ / / |/ _` |/ _ \/ _ \
+;;; | (_| | |_| | (_| | | (_) / / \ V /| | (_| | __/ (_) |
+;;; \__,_|\__,_|\__,_|_|\___/_/ \_/ |_|\__,_|\___|\___/
+;;;
+;; �find-audiovideo-intro� (to ".find-audiovideo-intro")
+;; (find-intro-links "audiovideo")
- (find-bgprocess \"xterm\")
+(defun find-audiovideo-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-audiovideo-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-audiovideo-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-audiovideo-intro\")
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
-from Emacs runs an xterm, which runs a shell; evaluating either
-of these sexps,
- (find-bgprocess \"xterm -e eechannel A /bin/sh\")
- (find-bgprocess \"xterm -e eechannel A $SHELL\")
-runs an xterm, which runs the \"eechannel\" script, which runs a
-shell. The sexp
+Time offsets
+============
+Links to audio and video files are similar to links to pdf-like
+documents, but instead of page numbers we use \"time offsets\" to
+refer to positions. Time offsets are strings like 1:23, 12:34, or
+1:23:45. The sexp hyperlinks below should all work if you have the
+files that they refer to:
- (eexterm \"A\")
+ (find-audio \"/tmp/mysong.mp3\")
+ (find-audio \"/tmp/mysong.mp3\" \"1:23\")
+ (find-audio \"/tmp/mysong.mp3\" \"1:23\" \"comment are ignored\")
+ (find-video \"/tmp/myvideo.mp4\")
+ (find-video \"/tmp/myvideo.mp4\" \"1:23\")
+ (find-video \"/tmp/myvideo.mp4\" \"1:23\" \"comment are ignored\")
-is a shorthand for the one using \"$SHELL\". Also, note that
-\"eechannel A ...\" saves its pid into \"eech.A.pid\".
+Note that they work by invoking an external player - mplayer, by
+default - and its error messages appear here:
-The diagram that shows what happens when we run `(eexterm \"A\")'
-is this one, below - note that the four arrows of the sending
-protocol are not shown.
+ (find-ebuffer \"*Messages*\")
- +------------+
- | |
- | X |
- | |
- +------------+
- / ^ \\ ^
- v / v \\
- +-----------+ +-------------+
- | | initiates | |
- | emacs |:::::::::::>| xterm |
- | | | |
- +-----------+ +-------------+
- :: | ^
- \\/ v |
- +-------------+
- | |
- eeg.A.pid <-- | eechannel A |
- | |
- +-------------+
- :: | ^
- \\/ v |
- +-------------+
- | |
- | sh |
- | |
- +-------------+
-Downloading and testing eechannel
-=================================
-Here I'll suppose that the directory \"~/bin/\" exists and is in
-your PATH. Run this to download the \"eechannel\" script and make
-it executable:
+Shorter hyperlinks to audio and video files
+===========================================
+If you type `M-V' (`eewrap-audiovideo') on a line containing a
+shorthand word and a file name of an audio or video file, for
+example, here,
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-cd ~/bin/
-# See: http://angg.twu.net/bin/eechannel.html
-wget -n http://angg.twu.net/bin/eechannel
-chmod 755 eechannel
+ sunwillset ~/Zoe_Keating/Sun_Will_Set.ogg
-Now let's test - from Emacs - if a local copy of \"eechannel\"
-exists, is in your PATH, and can be executed (remember that it
-needs Expect). Calling \"eechannel\" with not enough arguments
-should yield a nice error message.
+you will get something like this:
- (find-fline \"~/bin/eechannel\")
- (find-sh \"~/bin/eechannel\")
- (find-sh \"eechannel\")
+ ;; (find-fline \"~/Zoe_Keating/\")
+ (code-audio \"sunwillset\" \"~/Zoe_Keating/Sun_Will_Set.ogg\")
+ (code-video \"sunwillset\" \"~/Zoe_Keating/Sun_Will_Set.ogg\")
+ ;; (find-sunwillset)
+ ;; (find-sunwillset \"0:00\")
-It uses the environment variable EEVTMPDIR to decide where the
-temporary files - ee.CHANNELAME.pid, ee.CHANNELNAME.str - will
-be, so let's check that this directory exists:
+you should delete the line with the wrong sexp by hand - in this
+case the wrong one is the one with `code-video', as we are
+working with a sound file - and execute the other one; this will
+define a function called `find-sunwillset', that plays the audio
+file with `find-audio'. Run this this sexp to inspect its code:
- (getenv \"EEVTMPDIR\")
- (find-fline \"$EEVTMPDIR/\")
+ (find-code-audio \"sunwillset\" \"/tmp/Zoe_Keating__Sun_Will_Set.ogg\")
-Running eechannel with a first argument \"-v\" should show a lot
-of info, and then save the pid at eech.CHANNELAME.pid and run the
-given command. Let's try with a command that exits immediately.
+you will notice that running `find-sunwillset' sets a variable,
+with:
- (find-sh \"eechannel -v A /bin/true\")
- (find-fline \"$EEVTMPDIR/\" \"eech.A.pid\")
+ (setq ee-audiovideo-last 'find-sunwillset)
-Now let's verify - using just eepitch, without xterm at this
-moment - whether eechannel is being able to receive signals. In
-the eepitch script below, two `(find-sh0 \"kill ...\")'s should
-each make the controlled program receive a command - at the first
-\"kill\" an \"echo 2\", at the second an \"echo 3\".
+As we shall see soon, some operations play again the default
+audio or video file, starting from some given time offset. The
+default is always what is stored in `ee-audiovideo-last', and
+each call to a short hyperlink of the form `find-xxxaudio' or
+`find-xxxvideo' sets that variable.
- (eepitch-comint \"A\" \"eechannel -v A /bin/sh\")
- (eepitch-kill)
- (eepitch-comint \"A\" \"eechannel -v A /bin/sh\")
-echo 1
- (find-sh0 \" cat $EEVTMPDIR/eech.A.pid\")
- (find-sh0 \"echo 'echo 2' > $EEVTMPDIR/eech.A.str\")
- (find-sh0 \" cat $EEVTMPDIR/eech.A.str\")
- (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
-
- (find-sh0 \"echo 'echo 3' > $EEVTMPDIR/eech.A.str\")
- (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
-echo 4
-If the eepitched shell did run \"echo 1\", \"echo 2\", \"echo
-3\", \"echo 4\", then things are working - \"echo 1\" and \"echo
-4\" were sent through eepitch, but \"echo 3\" and \"echo 4\" were
-sent though channels.
+Passing options to mplayer
+==========================
+By default mplayer is called with just a few command-line options,
+besides the ones that tell it at what position to start playing -
+typically just these for videos,
-Now let's check if we can run an xterm, and if it can run an
-eechannel-ed shell instead of a plain shell. Check if the second
-sexp above starts an xterm, displays the info from \"eechannel
--v\", and then runs a shell:
+ -fs -osdlevel 2
- (find-bgprocess \"xterm\")
- (find-bgprocess \"xterm -e eechannel -v A $SHELL\")
- (find-bgprocess \"xterm -e eechannel A $SHELL\")
+to make it run in full-screen mode with an on-screen display
+showing the current position, and no options for audio.
-if that worked, run the four sexps below with <f8>,
+If you want to change this you should redefine these functions:
- (find-sh0 \"echo 'echo 1' > $EEVTMPDIR/eech.A.str\")
- (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
- (find-sh0 \"echo 'echo 2' > $EEVTMPDIR/eech.A.str\")
- (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
+ (ee-mplayer-video-options)
+ (ee-mplayer-audio-options)
-and check if the eechannel-ed shell in the xterm has received the
-commands \"echo 1\" and \"echo 2\". If it did, try the
-higher-level version below - but use <f9>s on each line instead
-of the <f8>s:
+
+
- (eexterm \"A\")
-echo 3
-echo 4
-If that worked, we're done. =)
+`eev-avadj-mode'
+================
+\"avadj-mode\" is a shorthand for \"audio/video adjust mode\".
+When `eev-avadj-mode' is active we get keys for adjusting time
+offsets quickly and for playing again the default audio or video
+file at a given time offset, all of this without moving the
+point. The keys are:
+ M-- decrease the time offset by one second
+ M-+ increase the time offset by one second
+ M-= same as M-+, for convenience
+ M-p play the default audio/video file at a time offset
-Several xterms
-==============
-http://angg.twu.net/eev-current/anim/channels.anim.html
+You can toggle eev-avadj-mode on and off with `M-x
+eev-avadj-mode', or with this sexp:
- (eexterm \"A\")
- (eexterm \"B\")
-# listen on port 1234
-netcat -l -p 1234
+ (eev-avadj-mode)
- (eexterm \"A\")
-# Send things to port 1234 (on localhost)
-{
- echo hi
- sleep 1
- echo bye
- sleep 1
-} | netcat -q O localhost 1234
+When it is on you will see an \"avadj\" at the mode line. Let's
+examine `M--' and `M-+' first. With eev-avadj-mode on, try typing
+several `M--'s and `M-+'s (or `M-='s) on the line below:
+ This time offset - 9:59 - will change
+Now, as an exercise, try to use `M--'s and `M-+'s/`M-='s, plus
+`M-h M-2' (`ee-duplicate-this-line') and other more standard
+editing commands, to convert this line
+ (find-exampleaudio \"0:00\")
+into:
+ (find-exampleaudio \"0:00\")
+ (find-exampleaudio \"0:12\" \"blah\")
+ (find-exampleaudio \"0:30\" \"bleh\")
-\[NOT DONE YET. The rest is (recyclable) garbage.\]
+That should give you an idea of how to index audio or video files
+- by creating elisp hyperlinks, with comments, to specific
+positions in them. Of course in a real-world situation we would
+execute these sexps occasionally to check if they are really
+pointing to the right places, and then make further adjustments;
+we are not doing that yet.
+The time-from-bol
+=================
+All the keys in eev-avadj-mode operate on the \"time-from-bol\"
+of the current line: the first occurrence, in the current line,
+of a string that looks like a time offset. Note that the search
+starts from the beginning of the line (\"-from-bol\"), and if
+there are several possibilities, the first one is chosen.
+Remember that `M-e' has a variant that just highlights what would
+be executed, instead of evaluating a sexp:
+ (find-eval-intro \"`M-0 M-e'\")
-\(Old stuff:)
+`M-p' also has something like this: `M-0 M-p' highlights the
+time-from-bol and displays in the echo area the sexp that it
+would execute to invoke a player - instead of running that sexp.
+Try to evaluate these sexps:
- emacs runs: (find-bgprocess \"xterm -T 'channel A' -e eegchannel A /bin/sh\")
- xterm runs: eegchannel A /bin/sh
- eegchannel saves its pid at ~/.eev/eeg.A.pid and runs: /bin/sh
+ (code-audio \"sunwillset\" \"~/Zoe_Keating/Sun_Will_Set.ogg\")
+ (find-sunwillset)
+ ;; ^ don't worry if this fails - we are only calling it
+ ;; to set `ee-audiovideo-last'
-At this point the xterm is running a shell that is \"listening on
-channel A\"; eegchannel pretends to be transparent and passes all
-characters and signals in the vertical arrows transparently - but when
-it receives a certain signal (a SIGUSR1) it reads the contents from
-the file ~/.eev/eeg.A.str and passes it to the shell, as if those
-characters were coming from the xterm - i.e., as if the used had typed
-them.
+and now try `M-0 M-p' on these lines:
-Here are the details of this \"protocol\":
-when we type F9 on a line containing \"echo foo\",
+ ;; 4:19 blah
+ ;; 2:19
- emacs saves the string \"echo foo\\n\" into ~/.eev/A.str,
- emacs reads the pid of eegchannel from ~/.eev/eeg.A.pid (say, \"1022\"),
- emacs runs \"kill -USR1 1022\",
- eegchannel reads the string from ~/.eev/A.str, and sends it to the shell.
+For more realistic examples, see:
-NOTE: one frequent question is: \"why are you using two normal files
-and SIGUSR1s for the communication between emacs and eegchannel,
-instead of making them talk through a fifo?\" - the answer is: try to
-explain the details of fifos - including creation - to someone who
-knows little about the inner workings of a *NIX kernel and who is
-uncomfortable to accept another kind of black box... The way with two
-files and SIGUSR1s is simpler, works well enough, and I've been able
-to write all the code for it in a few hours - and I still don't know
-enough about fifos to implement a fifo version of this.
+ (find-videos-intro)
-and another one, that was mostly used to control external
-programs running in dedicated xterms. You can see an animation
-demonstrating it - and an explanation of what each line does -
-here:
- http://angg.twu.net/eev-current/anim/channels.anim.html
- http://angg.twu.net/eev-current/doc/shot-f9.png
+Youtube-dl
+==========
+Videos at Youtube are identified by unique 11-char codes that are
+assigned to them when they are uploaded. We will call those 11-char
+codes \"hashes\", even though the term is not totally adequade in this
+case, and we will explain the main ideas considering the case of an
+imaginary video whose title is just TITLE, and whose hash is
+\"abcdefghijk\". The URL to access that video at Youtube would be this:
-How to set it up
-================
-\[To be written\]
+ http://www.youtube.com/watch?v=abcdefghijk
+ \\---------/
+ its hash
- ssh address@hidden
- eegchannel A ssh address@hidden
- (find-prepared-intro \"\\n`ee'\\n\")
- (find-eev \"anim/channels.anim\")
-" pos-spec-list)))
+If we execute this on a shell,
-;; (find-channels-intro)
+ cd /tmp/
+ youtube-dl -t 'http://www.youtube.com/watch?v=abcdefghijk'
+then youtube-dl would download a local copy of the video; due to the
+option \"-t\" (\"--title\"), the name of the local copy would have both
+the title of the video and its hash, and, if the video is in MP4
+format, that would be
+ /tmp/TITLE-abcdefghijk.mp4.part
+during the download, and would be renamed to
+ /tmp/TITLE-abcdefghijk.mp4
-;;; _ _
-;;; __ _(_) __| | ___ ___ ___
-;;; \ \ / / |/ _` |/ _ \/ _ \/ __|
-;;; \ V /| | (_| | __/ (_) \__ \
-;;; \_/ |_|\__,_|\___|\___/|___/
-;;;
-;; �find-videos-intro� (to ".find-videos-intro")
-;; (find-intro-links "videos")
+as soon as the download is finished.
-(defun find-videos-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-videos-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-videos-intro)
-Source code: (find-efunction 'find-videos-intro)
-More intros: (find-eev-quick-intro)
- (find-eev-intro)
- (find-eval-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
-What we have now
-================
-I am producing a series of videos about eev - but at this moment
-only two very broad introductions are ready 8-(. I have plans for
-several short videos about specific usage patterns, but don't
-hold your breath yet... also, these are my first videos EVER - so
-please excuse any stutterings, hesitations and false starts...
+Downloading a local copy
+========================
+Place the point at hash in the URL below,
-The videos are uploaded to Youtube to make them very easy to
-find, but Youtube reduces the resolution of the original videos
-and makes them blurry and almost unreadable - so the best way to
-watch them is to fetch local copies of the high-res .mp4 files.
+ http://www.youtube.com/watch?v=abcdefghijk
+and run `M-x find-youtubedl-links'; `find-youtubedl-links' will use
+the hash at point as a default for one of its arguments, will run
+something equivalent to this sexp,
+ (find-youtubedl-links nil nil \"abcdefghijk\")
-Downloading local copies
-========================
-Here are direct links to both the low-res versions at Youtube
-and to the corresponding high-res \".mp4\"s:
+and will create a buffer like this:
- Eepitch: a way to control shell-like programs from Emacs
- http://www.youtube.com/watch?v=Lj_zKC5BR64
- http://angg.twu.net/eev-videos/video4-eepitch.mp4
+ ___________________________________________________________________________
+ |# (find-youtubedl-links \"/tmp/\" \"{title}\" \"abcdefghijk\" \"{ext-}\"
\"{stem}\") |
+ |# (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
|
+ | |
+ |# (find-youtubedl-links \"~/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
|
+ |# (find-youtubedl-links \"~/videos/tech/\" nil \"abcdefghijk\" nil
\"{stem}\") |
+ |# (find-youtubedl-links \"/tmp/videos/\" nil \"abcdefghijk\" nil
\"{stem}\") |
+ |# (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
|
+ |# (find-efunction 'find-youtubedl-links) |
+ | |
+ | (eepitch-shell2) |
+ | (eepitch-kill) |
+ | (eepitch-shell2) |
+ |# http://www.youtube.com/watch?v=abcdefghijk |
+ |# http://www.youtube.com/watch?v=abcdefghijk#t=0m00s |
+ |# http://www.youtube.com/watch?v=abcdefghijk#t=0h00m00s |
+ |cd /tmp/ |
+ |youtube-dl -t 'http://www.youtube.com/watch?v=abcdefghijk' |
+ | |
+ |# youtube-dl -t -F 'http://www.youtube.com/watch?v=abcdefghijk' |
+ |# youtube-dl -t -f 18 'http://www.youtube.com/watch?v=abcdefghijk' |
+ | |
+ |# (find-es \"video\" \"youtube-dl\")
|
+ |# (find-fline \"/tmp/\" \"abcdefghijk\")
|
+ |# (find-fline \"/tmp/\" \"{title}-abcdefghijk\")
|
+ |# (find-fline \"/tmp/\" \"{title}-abcdefghijk{ext-}\")
|
+ |# (find-video \"/tmp/{title}-abcdefghijk{ext-}\")
|
+ |# (find-video \"/tmp/{title}-abcdefghijk{ext-}.part\")
|
+ |# (code-video \"{stem}video\" \"/tmp/{title}-abcdefghijk{ext-}\")
|
+ |# (code-video \"{stem}video\" \"/tmp/{title}-abcdefghijk{ext-}.part\")
|
+ |# (find-{stem}video) |
+ |# (find-{stem}video \"0:00\")
|
+ | |
+ |# Error messages (for the player): |
+ |# (find-ebuffer \"*Messages*\")
|
+ | |
+ | |
+ |--:**- *Elisp hyperlinks* All L1 (Fundamental)----------------------|
+ |___________________________________________________________________________|
- An introduction to eev2 (2012nov11)
- http://www.youtube.com/watch?v=doeyn5MOaB8
- http://angg.twu.net/eev-videos/video2.mp4
+which has LOTS of things... the part
-\(The video about eepitch is shorter and far better than the
-other one - please start by it.)
+ (eepitch-shell2)
+ (eepitch-kill)
+ (eepitch-shell2)
+ cd /tmp/
+ youtube-dl -t 'http://www.youtube.com/watch?v=abcdefghijk'
-The ideas behind \"local copies\" are here:
+is obvious: it is an eepitch script that downloads a local copy
+of the video from Youtube.
- (find-psne-intro)
-These sexps generate the download scripts in temporary buffers:
- (find-eev-video-links \"eepitchvideo\" \"video4-eepitch\" \"Lj_zKC5BR64\")
- (find-eev-video-links \"eevvideo\" \"video2\" \"doeyn5MOaB8\")
+Guessing the title and extension
+================================
+Let's simulate what would happen after the eepitch script above -
+Execute this:
+ (find-sh0 \"rm -v /tmp/TITLE-abcdefghijk*\")
+ (find-sh0 \"echo > /tmp/TITLE-abcdefghijk.mp4.part\")
+Now use `M-2 M-e' to compare the buffers generated by two calls
+to `find-youtubedl-links' below:
-Hyperlinks to the local copies of the videos
-============================================
-Notice that the download scripts above contain these sexps:
+ (find-youtubedl-links nil nil \"abcdefghijk\")
+ (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\")
-\(code-video \"eepitchvideo\"
\"$S/http/angg.twu.net/eev-videos/video4-eepitch.mp4\")
-\(code-video \"eevvideo\" \"$S/http/angg.twu.net/eev-videos/video2.mp4\")
+In the second one we get a buffer where all occurrences
+of \"{title}\" have been substituted by \"TITLE\", and all
+occurrences of \"{ext-}\" by \".mp4\". What happenned was that
-After you execute them hyperlinks like these should work:
+ (ee-youtubedl-guess* \"/tmp/\" \"abcdefghijk\")
+ --> (\"/tmp/TITLE-abcdefghijk.mp4.part\")
- (find-eepitchvideo)
- (find-eevvideo)
+did find files what that hash string in their names in the
+directory \"/tmp/\", and the function `ee-youtubedl-split' has
+picked up the first of these file names and has split it into
+components:
-Note that they use mplayer to display the videos, and if you
-don't have mplayer - or if you haven't downloaded the \".mp4\"s -
-then you will get error messages in the \"*Messages*\" buffer.
-You can inspect them with `C-x b *Messages*' or with:
+ (ee-youtubedl-split \"/tmp/TITLE-abcdefghijk.mp4.part\")
+ --> (\"/tmp/\" \"TITLE\" \"abcdefghijk\" \".mp4\" \".mp4.part\")
- (find-ebuffer \"*Messages*\")
+The last of these components is what we will call the \"ext\" -
+the \"full extension\" - and the previous one is the \"ext-\" -
+the \"extension minus its optional `.part'\". The first three
+components are the \"dir\", the \"title\", and the \"hash\".
-Hyperlinks to positions
-=======================
-The first argument to `find-eepitchvideo' and to other similar
-functions is a time offset; it is optional, and it defaults to
-\"0:00\". Any further arguments are ignored, and this allows us
-to use them as comments. So these two sexps are equivalent:
+The first lines regenerate the buffer
+=====================================
+The arguments to `find-youtubedl-links' are:
- (find-eepitchvideo \"0:16\")
- (find-eepitchvideo \"0:16\" \"the eepitch-to-shell-and-python example\")
+ (find-youtubedl-links DIR TITLE HASH EXT- STEM)
-We could use a series of `find-eepitchvideo' sexps to create a
-\"table of contents\" for a video, similarly to what we do for
-written documents...
+and we just saw how `ee-youtubedl-guess*' and
+`ee-youtubedl-split' can be used to guess TITLE, EXT and EXT-
+from DIR and HASH.
+All the arguments to `find-youtubedl-links' have defaults,
+that are used when the received arguments are nil:
+ * when HASH is nil, use the youtube hash around point,
+ or \"{hash}\" if none;
+ * when DIR is nil, use the value of `ee-youtubedl-dir',
+ or \"{dir}\" if none;
+ * when TITLE or EXT- are nil use the guessing method described
+ above, and when they fail use \"{title}\" or \"{ext-}\";
+ * when STEM is nil, use \"{stem}\".
-Time offsets as hyperlinks to positions
-=======================================
-In some cases using sexps creates too much visual clutter, and we
-would like to be able to create an index or table of contents
-writing lines just like this,
+The first two lines in a `find-youtubedl-links' regenerate the
+buffer, and are usually equivalent to one another. In the buffer
+generated by:
- 0:16 the eepitch-to-shell-and-python example
+ (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\")
-instead of using explicit elisp hyperlinks.
+they are:
-There is a way to do this, but it is tricky. It involves
-activating a mode, called `eev-avadj-mode', in which `M-p' is
-bound to a command that locates the first thing looking like a
-time offset in the current line, and calls the video player to
-make it play the *current default video* starting from that time
-offset; a sexp like
+ (find-youtubedl-links \"/tmp/\" \"TITLE\" \"abcdefghijk\" \".mp4\"
\"{stem}\")
+ (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
- (find-eepitchvideo t)
+The first one has only non-nil arguments - all the rules for
+guesses and defaults have been applied - where in the second one
+TITLE and EXT- are made nil.
-just sets the current default video, but does not invoke the
-player. All this is explained here:
- (find-audiovideo-intro \"The time-from-bol\")
+Selecting a directory
+=====================
+The second block of lines in the `find-youtubedl-links' buffer
+are used to let we switch the directory quickly. If we just
+execute `M-x find-youtubedl-links' with the point on our example
+hash, or, equivalently, if we do this,
+ (find-youtubedl-links nil nil \"abcdefghijk\")
+you will see that the first two lines will be:
-Eepitch video: table of contents
-================================
-\(eev-avadj-mode 1)
-\(find-eepitchvideo t)
+ (find-youtubedl-links \"~/videos/\" \"{title}\" \"abcdefghijk\" \"{ext-}\"
\"{stem}\")
+ (find-youtubedl-links \"~/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
-0:16 the eepitch-to-shell-and-python example, very quickly
-1:18 executing eepitch scripts with `f8's; f8 on red star lines and normal
lines
-2:33 the eepitch-to-shell-and-python example - what each line does
-3:15 the first three lines use advanced features
-3:52 eepitch scripts are made to be executed interactively
-5:25 the eepitch-to-shell-and-python example again, more slowly
+which means that the guessing process didn't find a downloaded
+copy, as TITLE is \"{title}\" and EXT- is \"{ext-}\". That's because
+we are using \"~/videos/\" as the DIR, and our file
-5:58 what happens when the eepitch target is being shown
-7:13 the default is to use two windows
-7:33 what happens when the target does not exist
-8:25 how to send commands to a new shell
-8:54 how an eepitch block (like eepitch-shell/kill/shell) works
+ /tmp/TITLE-abcdefghijk.mp4.part
-9:38 an example with shell comments (which eev uses as hyperlinks)
-12:35 refining hyperlinks
-12:35 converting shell commands into hyperlinks (by wrapping - by hand)
-13:04 wrapping commands - bound to meta-uppercase-letters
-13:53 M-M wraps the current line into a hyperlink to a manpage
-14:12 demonstrating M-M, M-S and M-T with eek sexps
-14:40 M-T wraps the current linto an eepitch-xxx/kill/xxx triple
-15:47 introduction to the sandboxed tutorials and to M-j (eejump)
-16:17 the default numeric arguments for eejump
-16:35 M-5 M-j jumps to the index for the documentation for eev
-17:15 temp. eev buffers usually start with a sexp that regenerates the buffer
-18:23 where the eepitch-to-shell-and-python example is in the documentation
+is elsewhere, and the guessing functions only search in one
+directory...
-18:58 Other examples
-19:07 pdf-like documents
-20:43 a tutorial for Lua based on eepitch
-22:26 that's it - last comments, where to find more info, how to get in touch
+The second block contains these sexps,
+ (find-youtubedl-links \"~/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
+ (find-youtubedl-links \"~/videos/tech/\" nil \"abcdefghijk\" nil \"{stem}\")
+ (find-youtubedl-links \"/tmp/videos/\" nil \"abcdefghijk\" nil \"{stem}\")
+ (find-youtubedl-links \"/tmp/\" nil \"abcdefghijk\" nil \"{stem}\")
+and if we execute the last one we set DIR to \"/tmp/\".
-Eev video: table of contents
-============================
-\(eev-avadj-mode 1)
-\(find-eevvideo t)
-
- 0:00 introduction
- 2:45 unpack the tarball and invoke Emacs
- 5:07 and make the cursor stop blinking
+To change the dir strings \"~/videos/\", \"~/videos/tech/\", \"/tmp/videos/\",
+\"/tmp/\", that appear in the second block of `find-youtubedl-links'
+buffers, change the variables `ee-youtubedl-dir', `ee-youtubedl-dir2',
+`ee-youtubedl-dir3', `ee-youtubedl-dir4.'
- 5:11 Emacs as a Lisp environment
-11:48 Open the file \"VERSION\" (TAB completes)
-12:15 (eek \"C-x C-f VERSION\") is not very readable
-12:35 (find-file \".../VERSION\") is more readable
-12:43 to follow it we type M-e, and M-k to go back
-14:00 parts for humans and more or less for humans; passive sexps
-14:34 variations of M-e that split the screen
-15:09 left side is \"before\", right side is \"after\"
-16:00 help on a key sequence
-16:28 C-h k gives us help on a key sequence
-17:46 (eek \"C-h k C-x C-f\") is an unreadble way to get help on a key
-17:55 (describe-function 'find-file) is even messier
-18:28 (find-efunctiondescr 'find-file) is cleaner - and why
-20:14 introduction the eev documentation in \"intro\"s
-22:30 (eek \"M-h M-k C-x C-f\") generates a list of hyperlinks
-24:15 the first line regenerates the buffer
-24:40 the intros are temporary buffers
-25:07 we can play without destroying the documentation of eev
-25:40 we can copy the hyperlinks to intros to other places
+How to download
+===============
-25:53 introduction to eejump
-26:44 a plain M-j goes to the index of eejumps
-28:00 M-5 M-j goes to the top level of the documentation in intros
-28:22 M-2 M-j goes to (find-emacs-intro)
-28:36 ...which has lots of links to the emacs manuals
-28:54 (find-eev-update-links)
-29:47 I could have done that with just instructions in English
-30:01 ...but it was more interesting to do that in an executable way.
-30:21 remember that the first line regenerates the buffer...
-31:07 we use that to select a directory for installation.
-31:40 an eepitch block
-31:53 emacs is made to handle anyting that looks like text...
-32:38 running terminals inside Emacs
-32:52 the best of both worlds
-33:50 f8
-35:48 [oops - I forgot to unpack]
+Test the download
+=================
+Create short links
+==================
-In Portuguese
-=============
- (find-eev-video-links \"eevvideopt\" \"video2pt\" \"yztYD9Y7Iz4\")
- (code-video \"eevvideopt\" \"$S/http/angg.twu.net/eev-videos/video2pt.mp4\")
- (eev-avadj-mode 1)
- (find-eevvideopt t)
-;; (find-eepitchvideo)
-;; (find-eevvideo)
-;; (find-eevvideopt)
+ (find-youtubedl-links \"/tmp/\" \"TITLE\" \"abcdefghijk\" \".mp4\"
\"{stem}\")
+ (find-youtubedl-links nil nil \"abcdefghijk\")
+ (find-eev \"eev-audiovideo.el\")
+ (find-eev \"eev-audiovideo.el\" \"eev-avadj-mode\")
+" pos-spec-list)))
-Comparison with youtube
-=======================
-Note that Youtube has a trick that lets we use URLs that point to
-specific positions in videos. For example, this,
+;; (find-audiovideo-intro)
- http://www.youtube.com/watch?v=Lj_zKC5BR64&t=0m16s
-makes the video about eepitch start at 0:16 instead of from the
-beginning. Also, each video at Youtube can have uploader comments
-and a discussion, and in the text of these comments things like
-\"12:34\" become links that make the current video skip to that
-position.
- (find-audiovideo-intro)
-Video2pt: Uma introducao ao eev2 (2012nov15)
-=============================================
-This is a version in Portuguese of the video above.
-It is slightly longer than the version in English because it's
-intended mostly for non-Emacsers, so some things are explained
-\(much) more slowly...
-At youtube: http://www.youtube.com/watch?v=yztYD9Y7Iz4
- http://www.youtube.com/watch?v=yztYD9Y7Iz4&t=1h07m40s
-Hi-res mp4: http://angg.twu.net/eev-videos/video2pt.mp4
- (128228339 bytes, 122MB. Duration: 1:09:42)
+;;; _ _ _ _ _
+;;; _ __ ___ _ _| | |_(_)_ _(_)_ __ __| | _____ __
+;;; | '_ ` _ \| | | | | __| \ \ /\ / / | '_ \ / _` |/ _ \ \ /\ / /
+;;; | | | | | | |_| | | |_| |\ V V /| | | | | (_| | (_) \ V V /
+;;; |_| |_| |_|\__,_|_|\__|_| \_/\_/ |_|_| |_|\__,_|\___/ \_/\_/
+;;;
+;; �find-multiwindow-intro� (to ".find-multiwindow-intro")
+;; (find-intro-links "multiwindow")
-# (find-eevvideopt)
-# (find-eevvideopt \"1:07:40\" \"eepitch pro shell e pro Python\")
+(defun find-multiwindow-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-multiwindow-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-multiwindow-intro)
+Source code: (find-efunction 'find-multiwindow-intro)
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
-Long story short
-================
-You may want to copy the block of elisp below to your .emacs. You can
-use this sexp to help you:
+1. Introduction
+===============
+In many situations - for example, when we want to script a
+debugger, or to test programs that have to talk to one another,
+or to control several external machines simultaneously - the
+default window setup for eepitch, which is this,
- (ee-copy-rest 0 '(find-fline \"~/.emacs\"))
+ ____________________
+ | | |
+ | | |
+ | script | shell |
+ | | |
+ | | |
+ |__________|_________|
-;; Hyperlinks to videos about eev.
-;; See: (find-videos-intro)
-;; (find-eev-video-links \"eepitchvideo\" \"video4-eepitch\" \"Lj_zKC5BR64\")
-;; (find-eev-video-links \"eevvideo\" \"video2\" \"doeyn5MOaB8\")
-;; (find-eev-video-links \"eevvideopt\" \"video2pt\" \"yztYD9Y7Iz4\")
-\(code-video \"eepitchvideo\"
\"$S/http/angg.twu.net/eev-videos/video4-eepitch.mp4\")
-\(code-video \"eevvideo\" \"$S/http/angg.twu.net/eev-videos/video2.mp4\")
-\(code-video \"eevvideopt\" \"$S/http/angg.twu.net/eev-videos/video2pt.mp4\")
-;; (find-eepitchvideo)
-;; (find-eevvideo)
-;; (find-eevvideopt)
-;; (find-ebuffer \"*Messages*\")
-" pos-spec-list)))
+is not enough; other setups, like these,
-;; (find-videos-intro)
+ ______________________
+ | | | _________________________
+ | | shell A | | | |
+ | |___________| | script | GDB |
+ | script | | | | |
+ | | shell B | |____________|____________|
+ | |___________| | | |
+ | | | | program | program |
+ | | shell C | | I/O | source |
+ |__________|___________| |____________|____________|
+may be necessary. Eev comes with a few _low-level_ tools for
+creating these setups; they are not very smart, but they should
+be easy to understand and to tweak - and I have the impression
+that ideas for good high-level tools will only come from
+practical experimentation.
+2. `find-wset'
+==============
+Suppose that we are in a buffer A, and we want to create a window
+configuration with A at the left, and with the buffers B and C
+stacked on one another at the right. That is:
-;;; _ __
-;;; __| | ___ / _|_ _ _ __
-;;; / _` |/ _ \ |_| | | | '_ \
-;;; | (_| | __/ _| |_| | | | |
-;;; \__,_|\___|_| \__,_|_| |_|
-;;;
-;; �find-defun-intro� (to ".find-defun-intro")
-;; (find-intro-links "defun")
+ ___________ ___________
+ | | | | |
+ | | | | B |
+ | A | --> | A |_____|
+ | | | | |
+ | | | | C |
+ |___________| |_____|_____|
-(defun find-defun-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-defun-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-defun-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-defun-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.
+To do that from the keyboard we could type this:
+ C-x 3 C-x o C-x b B RET C-x 2 C-x o C-x b C RET
-\[At present this is just a _skeleton_ for a tutorial on defining
-functions in Lisp...]
+You can try that here (the initial `C-x 1' is an extra, for
+convenience):
+ (eek \"C-x 1 ;; delete-other-windows
+ C-x 3 ;; split-window-horizontally (left/right)
+ C-x o ;; other-window (-> right)
+ C-x b B RET ;; switch to the buffer `B'
+ C-x 2 ;; split-window-vertically (upper/lower)
+ C-x o ;; other-window (-> lower right)
+ C-x b C RET ;; switch to the buffer `C'
+ \")
+We can write something equivalent to that as a `progn', in a way
+that makes it easy to replace later the `C-x b B RET' and the
+`C-x b C RET' by arbitrary sexp hyperlinks. We get:
-Simple examples
-===============
+ (progn (eek \"C-x 1 C-x 3 C-x o\")
+ (find-ebuffer \"B\")
+ (eek \"C-x 2 C-x o\")
+ (find-ebuffer \"C\")
+ (eek \"C-x o\")
+ )
- (* 5 5)
- (* 6 6)
- (defun foo (a) (* a a))
- (foo 5)
- (foo 6)
+When I started to rewrite my window configurations into that form
+I realized that the `eek's were being used in a very limited way
+- they only invoked a very small repertoire of window commands,
+all of them starting with `C-x'. So maybe I should have an
+interpreter for a simple language of window commands and sexp
+hyperlinks, in the which window setup above could be expressed
+like this:
- (+ 5 5)
- (defun foo (a) (+ a a))
- (foo 5)
+ `(\"13o\"
+ (find-ebuffer \"B\")
+ \"2o\"
+ (find-ebuffer \"C\")
+ \"o\"
+ )
- (symbol-function 'foo)
- ((lambda (a) (* a a)) 5)
- ((lambda (a) (+ a a)) 5)
+`find-wset' supports something like that, but with all the window
+command strings collapsed into a single one, with \"_\"s meaning
+\"execute the next sexp from the sexp list\". The corresponding
+call to `find-wset' is:
-See:
- (find-elnode \"Function Cells\")
- (find-elnode \"Defining Functions\")
+ (find-wset \"13o_2o_o\" '(find-ebuffer \"B\") '(find-ebuffer \"C\"))
+For the full list of supported window command characters - and
+how to extend it - see the source:
+ (find-eev \"eev-multiwindow.el\")
-Several arguments
-=================
- (defun foo (a b) (+ (* a a) (* b b)))
- (foo 10 2)
- (foo 5)
- (defun foo () (+ (* 2 3) (* 4 5)))
- (foo 10 2)
- (foo 5)
- (foo)
+3. High-level words
+===================
+Very often we want to create window setups like
-progn and prog1
-===============
-The body of a \"defun\" works like a \"progn\".
-See: (find-elnode \"Index\" \"* progn:\")
+ _______________ _______________
+ | | | | | |
+ | | | | | B |
+ | A | B | or | A |_______| ;
+ | | | | | |
+ | | | | | C |
+ |_______|_______| |_______|_______|
- (defun foo (a b) (* a b))
- (defun foo (a b) (+ a b) (* a b))
- (defun foo (a b) (* a b) (+ a b))
- (defun foo (a b) (+ a b))
- (foo 5 6)
+there are shorthands for that. If you run
- (progn (* 5 6) (+ 5 6))
- (progn \"ignored\" (+ 5 6) \"result\")
- (progn)
+ (find-2a sexpA sexpB)
- (prog1 (* 5 6) (+ 5 6))
- (prog1 \"result\" (+ 5 6) \"ignored\")
- (prog1)
+that will create a window setting like the one at the left above,
+initially with two copies of the current buffer, then will run
+sexpA at the window \"A\" and sexpB at the window \"B\", and
+finally will select the window \"A\", i.e., leave the cursor at
+the window at the left; this
+ (find-2b sexpA sexpB)
+will do exactly the same as the `(find-2a ...)' above, but will
+select the window \"B\" - the one at the right - at the end of
+the process. For three-window settings we have these:
-Docstrings
-==========
-Note that a string in a (progn ...) does nothing - unless it is
-the last BODY-FORM.
+ (find-3a sexpA sexpB sexpC)
+ (find-3b sexpA sexpB sexpC)
+ (find-3c sexpA sexpB sexpC)
-But see: (find-elnode \"Documentation\")
+all three create the three-window setting at the right above,
+initially with all three windows displaying the current buffer,
+then run sexpA at the window \"A\", sexpB at the window \"B\",
+and sexpC at the window \"C\"; the difference is that find-3a
+selects the window \"A\", find-3b the window \"B\", find-3c the
+window \"C\".
-Try:
- (defun foo (a b) \"IGNORED\" (+ a b))
- (defun foo (a b) \"This is the description of `foo'\" (+ a b))
- (defun foo (a b) \"This is the docstring of `foo'\" (+ a b))
- (defun foo (a b) \"This function returns (* A B). Note the italics!\" (+ a
b))
- (find-efunctiondescr 'foo)
+4. Several eepitch targets
+==========================
+If we try to build a window setup like this one, with two eepitch
+targets, with just `find-wset', we will run into problems -
-&optional and &rest
-===================
-See: (find-elnode \"Argument List\")
-Try:
+ ________________________
+ | | |
+ | | *shell* |
+ | script |_____________|
+ | | |
+ | | *shell 2* |
+ |__________|_____________|
- (defun foo (a &optional b c) (list \"a,b,c:\" a b c))
- (foo 11 22 33)
- (foo 11 22)
- (foo 11)
- (foo)
- (foo 11 22 33 44)
+because `(eepitch-shell)' and `(eepitch-shell2)' try to create a
+shell buffer and put it in an _another_ window, not the one we
+are in... one solution is to call the `(eepitch-*)' sexps inside
+an `ee-here', like this:
- (defun foo (a &optional b c &rest r) (list \"a,b,c,r:\" a b c r))
- (foo 11 22 33 44 55 66)
- (foo 11 22 33 44 55)
- (foo 11 22 33 44)
- (foo 11 22 33)
- (foo 11 22)
- (foo 11)
- (foo)
+ (ee-here '(eepitch-shell))
+ (ee-here '(eepitch-shell2))
- (defun foo (a &rest r) (list \"a,r:\" a r))
- (foo 11 22 33 44)
- (foo 11 22 33)
- (foo 11 22)
- (foo 11)
- (foo)
+where `ee-here' is a hack that runs a sexp in a way that
+preserves the current window configuration, then switches the
+buffer in the current selected window to the current eepitch
+target. We can use this to create the window setting above,
+ (find-wset \"13o2_o_o\"
+ ' (ee-here '(eepitch-shell))
+ ' (ee-here '(eepitch-shell2))
+ )
+This is too long - and would make a very bad one-liner - but
+there are two shorthands. First, \"e\" is a variant of \"_\" that
+runs its sexp inside an `(ee-here ...) - so this is equivalent
+the thing above,
-A tool: my-insert
-=================
-See: (find-elnode \"Formatting Strings\")
-Try:
+ (find-wset \"13o2eoeo\"
+ '(eepitch-shell)
+ '(eepitch-shell2)
+ )
- (format \"<%s>\" \"hello\")
- (format \"<%s>\" \"123\")
- (format \"<%s>\" 123)
- (format \"<%s>\" 'hello)
- (format \"<%s>\" '(+ 2 3))
+Second, these things are useful enough to deserve a high-level
+word, so this is equivalent to:
- (format \"<%S>\" \"hello\")
- (format \"<%S>\" \"123\")
- (format \"<%S>\" 123)
- (format \"<%S>\" 'hello)
- (format \"<%S>\" '(+ 2 3))
+ (find-3ee '(eepitch-shell) '(eepitch-shell2))
-Now define:
- (defun my-insert (obj)
- \"Print (insert) OBJ in the current buffer.\"
- (insert (format \"\\n ;; \\\\--> %S\" obj)))
-Try:
- (my-insert 123)
- (my-insert \"123\")
- (my-insert \"hello\")
- (my-insert 'hello)
- (my-insert '(+ 2 3))
- (my-insert nil)
- (my-insert '())
- (my-insert ())
+5. Restarting eepitch targets
+=============================
+Sometimes we want to do the same as above, but restarting both
+eepitch targets, i.e., something like this:
-See also:
- (find-elnode \"Character Type\")
- (find-elnode \"Basic Char Syntax\")
- (find-elnode \"Basic Char Syntax\" \"?\\\\n\")
- (find-elnode \"General Escape Syntax\")
+ (find-3ee '(progn (eepitch-shell) (eepitch-kill) (eepitch-shell))
+ '(progn (eepitch-shell2) (eepitch-kill) (eepitch-shell2))
+ )
+There's a variant of `ee-here' that does that: `ee-here-reset'.
+For example,
+ (ee-here-reset '(eepitch-shell2))
-interactive
-===========
-Not all Emacs functions are callable with `M-x' - only those that
-are \"commands\" are callable in this way. And only \"commands\"
-can be bound to keys...
+is equivalent to:
+
+ (ee-here '(progn (eepitch-shell2) (eepitch-kill) (eepitch-shell2)))
+
+and the letter \"E\" is a variant of \"e\" that uses
+`ee-here-reset' instead of `ee-here'; also, `find-3EE' is a
+variant of `find-3ee' that restarts both targets. Let's adapt
+this example,
+
+ (find-eepitch-intro \"Other targets\")
+
+to make it show the two eepitch targets at once in a three-window
+settings. It becomes:
+
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+ (eepitch-shell)
+echo Hello... > /tmp/o
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
+ (eepitch-shell)
+echo ...and bye >> /tmp/o
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
+
+ Now compare:
+ (eek \"C-x 1\")
+ (find-3ee '(eepitch-shell) '(eepitch-python))
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+
+
+
+6. Non-trivial examples
+========================
+See:
+
+ (find-prepared-intro \"An `ee' for Python\")
+ (find-rcirc-intro \"The server buffer and the channel buffers\")
+
+
+
+7. Eepitch blocks for two targets
+=================================
+An eepitch script with two targets uses several different kinds
+of red star lines - `(eepitch-target1)', `(eepitch-target2)',
+`(find-3EE ...)', `(find-3ee ...)', etc. We don't want to have to
+type all those by hand, so there is a hack similar to `M-T' that
+generates all those kinds from just \"target1\" and \"target2\"
+to let us just copy around the sexps we need. It is bound to
+`meta-shift-3', which Emacs sees as `M-#'. Compare the result of
+typing `M-T' here,
+
+python
+
+with the result of typing `M-#' on this line,
+
+shell python
+
+which yield this:
+
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+ (find-3ee '(eepitch-shell) '(eepitch-python))
+ (eepitch-shell)
+ (eepitch-python)
+
+Note that we use to `find-3EE' to restart targets instead of
+`eepitch-kill' (this is non-trivial - think about it =/)...
+
+
+
+8. Adding support for new characters in `find-wset'
+===================================================
+The standard characters supported by `find-wset' are these:
+
+ char action key
+ ---- ---------------------------- ---------
+ `1' `delete-other-windows' (C-x C-1)
+ `2' `split-window-vertically' (C-x C-2)
+ `3' `split-window-horizontally' (C-x C-3)
+ `s' `split-window-sensibly'
+ `o' `other-window' (C-x o)
+ `+' `balance-windows' (C-x +)
+ `_' execute the next sexp
+
+but the action of each one is defined in a different function,
+and to add support for a new character, say, `=', we just need to
+define a function with the right name - in this case,
+`find-wset-='.
+
+The source code is simple enough, so take a look:
+
+ (find-eev \"eev-multiwindow.el\" \"find-wset-_\")
+ (find-eev \"eev-multiwindow.el\" \"find-wset-=\")
+ (find-eev \"eev-multiwindow.el\" \"find-wset-!\")
+
+Note that `find-wset-!' restarts an eepitch target, while
+`find-wset-=' will reuse an eepitch target if its buffer already
+exists. [Obs: \"=\" and \"!\" have been mostly superseded by
+\"e\" and \"E\"... to do: explain this]
+
+
+See: (find-prepared-intro)
+
+ [Example at find-prepared-intro]
+
+
+
+
+9. Executing key sequences at other windows
+===========================================
+It is possible to use multi-window settings, together with the
+trick that `<f8>' on a red star line executes it as Lisp and
+moves down, to create tutorials for Emacs modes. An example:
+
+ (...)
+
+
+
+10. A tutorial for Info mode
+============================
+Here's a mini-tutorial for Info mode, demonstrating how to
+navigate in Info using the usual movement keys, plus TAB,
+<backtab>, RET, l (last), u (up), n (next), p (prev), q (quit),
+C-h i, and the digits 1-9. Note that the display in Info mode is
+like this:
+
+ ____________________________________________
+ |Next: Nonincremental Search, Up: Search | <- next/prev/up
+ | (emacs)Top > Search > Incremental Search | <- breadcrumbs
+ | |
+ | 19.1 Incremental Search | <- section number /
+ | | node name (long)
+ | (...) |
+ | |
+ |--:%%- *info* (emacs) Incremental Search |
+ |____________________________________________|
+
+Here:
+
+ Define some hacks
+ (defun ow (n) (other-window n))
+ (defun eeoe (code) (ow 1) (prog1 (eval code) (ow -1)))
+ (defun eeok (keystr) (eeoe `(eek ,keystr)))
+
+ Prepare the windows
+ (ee-kill-buffer \"*info*\")
+ (find-wset \"1so_o\" '(find-enode \"Search\"))
+
+ The arrows (and other movent keys) work as expected.
+ Watch the cursor in the Info window...
+ (eeok \"3*<down>\")
+ (eeok \"10*<right>\")
+
+ TAB and <backtab> move to the next and to the previous link.
+ Note that they consider all the links in a page, not only
+ the ones in menus - including the breadcrumb links at the top.
+ (eeok \"TAB ;; Info-next-reference\")
+ (eeok \"TAB ;; Info-next-reference\")
+ (eeok \"TAB ;; Info-next-reference\")
+ (eeok \"TAB ;; Info-next-reference\")
+ (eeok \"TAB ;; Info-next-reference\")
+ (eeok \"<backtab> ;; Info-prev-reference\")
+ (eeok \"<backtab> ;; Info-prev-reference\")
+ (eeok \"<backtab> ;; Info-prev-reference\")
+ (eeok \"<backtab> ;; Info-prev-reference\")
+
+ RET follows a link, l (last) goes back.
+ Watch the section number: 19 -> 32.3.6 -> 19.
+ (eeok \"RET ;; Info-follow-nearest-node\")
+ (eeok \"l ;; Info-history-back\")
+
+ The digits 1-9 can be used to go straight to subsections.
+ For example, a `4' would follow the 4th _menu_ link -
+ ignoring the non-menu links.
+ Watch the section number: 19 -> 19.1 -> 19.1.1.
+ (eeok \"1 ;; Info-nth-menu-item\")
+ (eeok \"1 ;; Info-nth-menu-item\")
+
+ The keys `u', `n', `p' (up, next, and prev) move through the
+ tree structure. Watch the section number:
+ 19.1.1 -u-> 19.1 -u-> 19 -n-> 20 -n-> 21 -p-> 20 -p-> 19
+ (eeok \"u ;; Info-up\")
+ (eeok \"u ;; Info-up\")
+ (eeok \"n ;; Info-next\")
+ (eeok \"n ;; Info-next\")
+ (eeok \"p ;; Info-prev\")
+ (eeok \"p ;; Info-prev\")
+
+ `q' leaves Info mode - more precisely, it buries the info buffer.
+ `C-h i' goes back to the Info buffer (or restarts info).
+ (eeok \"q ;; Info-exit\")
+ (eeok \"C-h i ;; info\")
+
+" pos-spec-list)))
+
+;; (find-multiwindow-intro)
+
+
+
+;;; _
+;;; _ __ ___(_)_ __ ___
+;;; | '__/ __| | '__/ __|
+;;; | | | (__| | | | (__
+;;; |_| \___|_|_| \___|
+;;;
+;; �find-rcirc-intro� (to ".find-rcirc-intro")
+;; (find-intro-links "rcirc")
+
+(defun find-rcirc-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-rcirc-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-rcirc-intro)
+Source code: (find-efunction 'find-rcirc-intro)
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
+
+
+
+Recent versions with Emacs come with two IRC clients built-in:
+Rcirc and ERC. I never understood ERC well enough, and I found
+Rcirc quite easy to understand and to hack, so eev has some
+support for Rcirc (and no support for ERC).
-See:
- (find-elnode \"Defining Functions\" \"the first two of the BODY-FORMS\")
- (find-elnode \"Defining Commands\")
- (find-elnode \"Command Overview\")
-When you execute an `(interactive ...)' it does nothing - it
-simply ignores its arguments (which aren't even evaluated!) and
-returns nil. But just as
+The server buffer and the channel buffers
+=========================================
+If you type `M-6 M-6 M-j' - or `M-e' on the line below - then eev
+runs this,
- (defun my-insert (obj) (insert (format \"\\n ;; \\\\--> %S\" obj)))
+ (find-freenode-3a \"#eev\")
- (find-efunctiondescr 'interactive)
+which tells Emacs to connect to Freenode and to the channel #eev,
+using this window setting:
- (eek \"M-x foo\")
- (commandp 'foo)
+ _________________________
+ | | |
+ | | Freenode |
+ | | server |
+ | | messages |
+ | current |_____________|
+ | buffer | |
+ | | #eev |
+ | | channel |
+ | | |
+ |___________|_____________|
- (defun foo (&rest rest) (interactive) (bar rest))
- (eek \"M-x foo\")
+You will then be able to watch the process of connecting to
+Freenode, which takes about 20s on my machine, by the messages
+that will appear at the Freenode server buffer; at some point
+rcirc will be allowed by the server to connect to channels, it
+will request to connect to the channel #eev, and some login
+messages, plus at list of all users connected to #eev and a
+prompt, will appear at the #eev channel buffer.
- (defun foo (&rest rest) (bar rest))
- (defun foo (&rest rest) (interactive \"P\") (bar rest))
- (eek \" M-x foo\")
- (eek \"M-1 M-x foo\")
- (eek \"M-1 M-2 M-3 M-x foo\")
- (eek \"M-- M-2 M-3 M-x foo\")
+`M-66j' is mostly for establishing a connection to an IRC server
+and watching if any errors occur; once we know that we are
+connected we can use `M-6j' - with just one `M-6' - which just
+takes us to the #eev channel without changing the current window
+configuration. A mnemonic: `M-66j', which is one keypress longer,
+is to be used less often - essentially only once per session, or
+when we want to check the status of our connection to Freenode.
- (defun foo (&rest rest) (interactive \"R\") (bar rest))
- (eek \"M-x foo\")
-" rest)))
-;; (find-defun-intro)
-;; (find-defun-intro "&rest")
-;; (find-defun-intro "\ninteractive\n")
-;; (find-defun-intro "Defining Commands")
+Messages and commands
+=====================
+IRC is a command-line-ish protocol, in which lines starting with
+\"/\" are treated as commands and other lines as messages. A
+message typed at the #eev channel buffer is broadcast to all
+other users also connected to #eev; some commands, like
+ /join #emacs
+work in the same way no matter where they are typed, while
+others, like for example \"/part\", work differently when typed
+in #eev than when in #emacs. See:
+ (find-rcircnode \"rcirc commands\" \"/join #emacs\")
+ (find-rcircnode \"rcirc commands\" \"/part\")
-;;; _
-;;; ___ _ __ ___ __ _ ___ ___ | | _____ _ _ ___
-;;; / _ \ '_ ` _ \ / _` |/ __/ __|_____| |/ / _ \ | | / __|
-;;; | __/ | | | | | (_| | (__\__ \_____| < __/ |_| \__ \
-;;; \___|_| |_| |_|\__,_|\___|___/ |_|\_\___|\__, |___/
-;;; |___/
-;;
-;; �find-emacs-keys-intro� (to ".find-emacs-keys-intro")
-;; (find-intro-links "emacs-keys")
-(defun find-emacs-keys-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-emacs-keys-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-emacs-keys-intro)
-Source code: (find-efunction 'find-emacs-keys-intro)
-More intros: (find-eev-quick-intro)
- (find-eev-intro)
- (find-eval-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
+Other channels
+==============
+where `find-freenode-3a' is based on `find-3a', described here:
-1. Basic keys (eev)
-===================
-The most basic keys of eev are:
- M-e - to follow a hyperlink. Mnemonic: \"(e)valuate\"/\"(e)xecute\".
- See: (find-eev-quick-intro \"2. Evaluating Lisp\")
- (find-eev-quick-intro \"3. Elisp hyperlinks\")
- M-k - to go back. Mnemonic: \"(k)ill buffer\".
- See: (find-eev-quick-intro \"3. Elisp hyperlinks\" \"M-k\")
- M-j - to jump to certain predefined places - in particular,
- `M-j' takes you to the list of jump targets.
- `M-2 M-j' takes you to this help page.
- `M-5 M-j' takes you to: (find-eev-quick-intro)
- <f8> - See: (find-eev-quick-intro \"6. Controlling shell-like programs\")
- M-T - See: (find-eev-quick-intro \"6.3. Creating eepitch blocks: `M-T'\")
+ (find-multiwindow-intro \"High-level words\")
-The keys for creating \"hyperlinks to here\" and refining them are:
- M-h M-h - `find-here-links'. See: (find-eev-quick-intro \"`M-h M-h'\")
- M-h M-2 - `ee-duplicate-this-line'. See: (find-eval-intro \"M-h M-2\")
- M-h M-y - `ee-yank-pos-spec'. See: (find-eval-intro \"M-h M-y\")
+ (find-eev \"eev-rcirc.el\")
+If you are new to IRC
+=====================
+Most of the discussions between Free Software developers still
+happen in IRC channels, and mostly at Freenode. The best way to
+understand what IRC is - for modern people, I mean - is probably
+to try this first:
-2. Key sequences and how to abort them
-======================================
-See: (find-enode \"Keys\" \"key sequence\")
- (find-enode \"User Input\" \"`Control-a'\" \"usually written `C-a'\")
- (find-enode \"User Input\" \"<META> key\")
- (find-enode \"Completion\" \"<TAB>\")
+ http://webchat.freenode.net/
-<ESC> <ESC> <ESC> (find-enode \"Quitting\")
-C-g keyboard-quit (find-enode \"Quitting\" \"`C-g'\")
-M-x execute-extended-command (find-enode \"M-x\" \"Running Commands by
Name\")
+IRC is a command-line-ish protocol, in which lines starting with
+\"/\" are treated as commands and other lines are messages to be
+broadcast. Try to \"/join\" the channels \"#emacs\" and \"#eev\",
+with \"/join #emacs\" and \"/join #eev\"; in that webchat, try to
+switch between the channels you're connected to by clicking on
+the tabs at the top - and note that there is also a tab for a
+channel-ish thing that has only messages from the server. Try
+also to leave these channels with \"/part\", \"/part #emacs\",
+\"/part #eev\".
-More about the minibuffer: (find-enode \"Minibuffer\")
-More about TAB - for completion: (find-enode \"Completion\")
- for indentation: (find-enode \"Indentation\")
- in programming modes: (find-enode \"Basic Indent\")
-More about modes: (find-enode \"Major Modes\")
- (find-enode \"Minor Modes\")
- (find-enode \"Dired\")
+In Rcirc each one of these channels, including the server
+channel, becomes an Emacs buffer. The names of these buffers will
+be:
+ *irc.freenode.net*
+ address@hidden
+ address@hidden
+ (defun eejump-66 () (find-freenode-3a \"#eev\"))
-3. Cutting & pasting
-====================
-The \"region\" where cut & copy operate is always what is between
-the \"point\" and the \"mark\":
+For more information see:
- (find-enode \"Point\")
- (find-enode \"Mark\")
+ (find-node \"(rcirc)Top\")
+ (find-node \"(rcirc)Internet Relay Chat\")
+ (find-node \"(rcirc)rcirc commands\")
+ http://www.emacswiki.org/emacs/RcIrc
+ http://www.irchelp.org/
-You can do cut, copy and paste by using the icons in the toolbar
-or by using the menu bar (the relevant options are under
-\"Edit\"), but the keys are worth learning:
+ (find-node \"(erc)Top\")
+ http://www.emacswiki.org/emacs/ErC
- C-SPC -- set-mark-command (find-enode \"Setting Mark\")
- C-x C-x -- exchange-point-and-mark (find-enode \"Setting Mark\" \"C-x
C-x\")
- C-w -- kill-region (cut) (find-enode \"Other Kill Commands\")
- M-w -- kill-ring-save (copy) (find-enode \"Kill Ring\")
- C-y -- yank (paste) (find-enode \"Kill Ring\")
+" pos-spec-list)))
-See: (find-enode \"Tool Bars\")
- (find-enode \"Menu Bar\")
+;; (find-rcirc-intro)
-4. Moving point
-===============
-C-a -- beginning-of-line (find-enode \"Moving Point\")
-C-e -- end-of-line (find-enode \"Moving Point\")
-M-< -- beginning-of-buffer (find-enode \"Moving Point\")
-M-> -- end-of-buffer (find-enode \"Moving Point\")
+;;; _ _ _
+;;; | |_ ___ _ __ ___ _ __ | | __ _| |_ ___ ___
+;;; | __/ _ \ '_ ` _ \| '_ \| |/ _` | __/ _ \/ __|
+;;; | || __/ | | | | | |_) | | (_| | || __/\__ \
+;;; \__\___|_| |_| |_| .__/|_|\__,_|\__\___||___/
+;;; |_|
+;;
+;; �find-templates-intro� (to ".find-templates-intro")
+;; (find-intro-links "templates")
+
+(defun find-templates-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-templates-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-templates-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-templates-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. Undoing
-==========
-C-/ -- undo (find-enode \"Basic Undo\")
-C-_ -- undo (find-enode \"Basic Undo\")
- (find-enode \"Undo\")
+`ee-template0'
+==============
+\(find-efunctiondescr 'ee-template0)
+\(find-efunction 'ee-template0)
-6. Windows
-==========
-See: (find-enode \"Windows\")
- (find-enode \"Frames\")
-C-x o -- other-window (find-enode \"Other Window\")
-C-x 0 -- delete-window (find-enode \"Change Window\")
-C-x 1 -- delete-other-windows (\"1 window\") (find-enode \"Change
Window\")
-C-x 2 -- split-window-vertically (Above/Below) (find-enode \"Split Window\")
-C-x 3 -- split-window-horizontally (L|R) (find-enode \"Split Window\")
+`ee-H', `ee-S', `ee-HS'
+=======================
-7. Files and buffers
-====================
-C-x C-f -- find-file (find-enode \"Visiting\")
-C-x C-s -- save-buffer (find-enode \"Saving\")
-C-x C-c -- save-buffers-kill-emacs (find-enode \"Saving\")
-C-x b -- switch-to-buffer (find-enode \"Select Buffer\")
-C-x k -- kill-buffer (find-enode \"Kill Buffer\")
- (find-enode \"Dired\")
+`find-find-links-links'
+=======================
+\(find-links-intro)
+\(find-find-links-links)
+\(find-efunction 'ee-stuff-around-point)
+interactive
-8. Search and replace
-=====================
-C-s -- isearch-forward (find-enode \"Incremental Search\")
-C-r -- isearch-backward (find-enode \"Incremental Search\")
-M-C-s -- isearch-forward-regexp (find-enode \"Regexp Search\")
-M-C-r -- isearch-backward-regexp (find-enode \"Regexp Search\")
-M-% -- query-replace (find-enode \"Replace\")
+`find-elinks'
+=============
+\(find-efunction 'find-elinks)
-9. Macros
-=========
-C-x ( -- start-kbd-macro (find-enode \"Keyboard Macros\")
-C-x ) -- end-kbd-macro (find-enode \"Keyboard Macros\")
-C-x e -- call-last-kbd-macro (find-enode \"Keyboard Macros\")
+ (find-intro-links)
+\(find-eev \"eev-tlinks.el\" \"find-intro-links\")
+\(find-eevfile \"eev-tlinks.el\")
-10. Other keys (Emacs)
+The innards: templates
======================
-M-q -- fill-paragraph (find-enode \"Fill Commands\")
-C-x r <SPC> <char> -- point-to-register (find-enode \"Position
Registers\")
-C-x r j <char> -- jump-to-register (find-enode \"Position
Registers\")
-
-
-
-11. Other keys (eev)
-====================
-M-F -- eewrap-find-fline (find-eev-quick-intro \"`M-F'\")
-M-M -- eewrap-man (find-eev-quick-intro \"`M-M'\")
-M-S -- eewrap-sh (find-eev-quick-intro \"`M-S'\")
-M-A -- eewrap-anchor (find-eev-quick-intro \"`M-A'\")
-M-B -- eewrap-escript-block (find-eev-quick-intro \"`M-B'\")
-" pos-spec-list)))
+Several functions in eev besides `code-c-d' work by replacing
+some substrings in \"templates\"; they all involve calls to
+either the function `ee-template0', which is simpler, or to
+`ee-template', which is much more complex.
-;; (find-emacs-keys-intro)
+The function `ee-template0' receives a single argument - a
+string, in which each substring surrounded by `{...}'s is to be
+replaced, and replaces each `{...}' by the result of evaluating
+the `...' in it. For example:
+ (ee-template0 \"a{(+ 2 3)}b\")
+ --> \"a5b\"
+Usually the contents of each `{...}' is the name of a variable,
+and when the result of evaluating a `{...}' is a string the
+replacement does not get `\"\"'s.
+The function `ee-template' receives two arguments, a list and a
+template string, and the list describes which `{...}' are to be
+replaced in the template string, and by what. For example, here,
+ (let ((a \"AA\")
+ (b \"BB\"))
+ (ee-template '(a
+ b
+ (c \"CC\"))
+ \"_{a}_{b}_{c}_{d}_\"))
-;;; _ _
-;;; ___ _ __ ___ __ _ ___ ___ (_)_ __ | |_ _ __ ___
-;;; / _ \ '_ ` _ \ / _` |/ __/ __|_____| | '_ \| __| '__/ _ \
-;;; | __/ | | | | | (_| | (__\__ \_____| | | | | |_| | | (_) |
-;;; \___|_| |_| |_|\__,_|\___|___/ |_|_| |_|\__|_| \___/
-;;;
-;; �find-emacs-intro� (to ".find-emacs-intro")
-;; (find-intro-links "emacs")
+ --> \"_AA_BB_CC_{d}_\"
-(defun find-emacs-intro (&rest rest) (interactive)
- (let ((ee-buffer-name "*(find-emacs-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-emacs-intro)
-Source code: (find-eev \"eev-intro.el\" \"find-emacs-intro\")
-More intros: (find-eev-quick-intro)
- (find-emacs-keys-intro)
- (find-eev-intro)
- (find-eval-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
+the \"{d}\" is not replaced. Note that the list (a b (c \"CC\"))
+contains some variables - which get replaced by their values -
+and a pair, that specifies explicitly that every \"{c}\" should
+be replaced by \"CC\".
-THIS INTRO IS OBSOLETE, and has been superseded by:
- (find-emacs-keys-intro)
+Templated buffers
+=================
+Introduction
+Conventions:
+ the first line regenerates the buffer,
+ buffer names with \"**\"s,
+ (find-evariable 'ee-buffer-name)
+ code
+`find-elinks'
+=============
+Variant: `find-elinks-elisp'
-Basic keys (eev)
-================
-The most basic keys of eev are:
- M-e - to follow a hyperlink, see: (find-eval-intro \"Elisp hyperlinks\")
- M-k - to go back, see: (find-eval-intro \"\\nGoing back\")
- M-j - to jump to certain predefined places - in particular,
- `M-j' takes you to the list of jump targets.
- `M-2j' takes you to this help page.
- `M-5j' takes you to: (find-eev-intro)
- See: (find-eejump-intro \"Families\")
- M-h M-h - hyperlinks to here, plus help.
- See: (find-eev-quick-intro \"7.1. eejump\")
- (find-links-intro \"`find-here-links'\")
+`find-e*-links'
+===============
+\(find-eev \"eev-elinks.el\")
+`find-*-intro'
+==============
-The mnemonics are:
- M-e - evaluate/execute
- M-j - jump
- M-k - kill buffer
+`eewrap-*'
+==========
-It is possible to start learning Emacs and eev by remembering
-only that `M-j' jumps to an index; when you're lost, type `M-j',
-and will see a reminder of the main keys and of the main jump
-targets - after that you can learn how to use `M-k' to kill the
-top buffer, and `M-e' to follow elisp hyperlinks. The other keys
-are explained in \"intros\" like this one.
+Experiments
+===========
+\(find-efunction 'find-youtubedl-links)
+\(find-efunction 'ee-hyperlinks-prefix)
+\(find-efunction 'find-newhost-links)
+\(find-efunction 'find-eface-links)
+ Note that there is no undo.
+" rest)))
+;; (find-templates-intro)
-Files, Buffers, Windows, Frames, Display, etc
-=============================================
-Emacs can edit several files at the same time, each one
-in a \"buffer\".
+;; �find-anchors-intro� (to ".find-anchors-intro")
+;; (find-intro-links "anchors")
- (find-enode \"Files\")
- (find-enode \"Buffers\")
- (find-enode \"Windows\")
- (find-enode \"Frames\")
+(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.
-The display of Emacs looks like this (asciified):
- __ _ _
- ______________emacs_______\\/|-|X|
- / | | \\
- | | bla. | | Emacs
-Window | | | | calls this
-managers | | | | a \"window\".
-call | | | /
-this a | |--:** foo.txt (Fundamental) ----| <-- Its \"modeline\".
-\"window\". / | | \\
-Emacs \\ | bla bla. | | Another
-calls | | bleh | | window.
-this a | | | |
-\"frame\". | | | /
- | |--:** bar.txt (Fundamental) ----| <-- Its modeline.
- \\ |Find file: ~/bletch.txt_ ________| <-- The minibuffer.
-The bottom line of a frame is sometimes the \"echo area\",
-sometimes the \"minibuffer\". The minibuffer acts like a
-window when it is active, and `C-x o' can be used to move
-from it to the \"normal windows\" and back. You can also
-use the mouse to move between windows.
- (find-enode \"Echo Area\")
- (find-enode \"Minibuffer\")
- (find-enode \"Other Window\")
+NOTE: This has been mostly superseded by:
+(find-eev-quick-intro \"8. Anchors\")
-By default there's also a \"menu bar\" (with textual entries) and
-a \"tool bar\" (with icons) at the top of each frame, but
-advanced users usually disable them.
- (find-enode \"Menu Bar\")
- (find-enode \"Tool Bars\")
+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:
-Basic keys (Emacs)
-==================
-\(find-enode \"Keys\" \"key sequence\")
-\(find-enode \"User Input\" \"`Control-a'\" \"usually written `C-a'\")
-\(find-enode \"User Input\" \"<META> key\")
-\(find-enode \"Completion\" \"<TAB>\")
+ ee-anchor-format
+ (format ee-anchor-format \"foo\")
+ (ee-goto-position (format ee-anchor-format \"foo\"))
-<ESC> <ESC> <ESC> (find-enode \"Quitting\")
-C-g keyboard-quit (find-enode \"Quitting\" \"`C-g'\")
+We will call strings in `��'s _anchors_, and we will say
+that `(to \"foo\")' jumps \"to the anchor `foo'\".
-M-x execute-extended-command (find-enode \"M-x\" \"Running Commands by
Name\")
+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.
-Cutting & pasting
-=================
-The \"region\" where cut & copy operate is always what is between
-the \"point\" and the \"mark\":
+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-enode \"Point\")
- (find-enode \"Mark\")
+ (find-eepitch-intro \"\\nRed stars\\n\")
-You can do cut, copy and paste by using the icons in the toolbar
-or by using the menu bar (the relevant options are under
-\"Edit\"), but the keys are worth learning:
+For historical reasons, the glyphs for `�' and `�' defined in
- C-SPC -- set-mark-command (find-enode \"Setting Mark\")
- C-x C-x -- exchange-point-and-mark (find-enode \"Setting Mark\" \"C-x
C-x\")
- C-w -- kill-region (cut) (find-enode \"Other Kill Commands\")
- M-w -- kill-ring-save (copy) (find-enode \"Kill Ring\")
- C-y -- yank (paste) (find-enode \"Kill Ring\")
+ (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.
-Undoing
-=======
-C-/ -- undo (find-enode \"Basic Undo\")
-C-_ -- undo (find-enode \"Basic Undo\")
- (find-enode \"Undo\")
-Windows
+Indexes
=======
-See: (find-enode \"Frames\")
- (find-enode \"Windows\")
-C-x o -- other-window (find-enode \"Other Window\")
-C-x 0 -- delete-window (find-enode \"Change Window\")
-C-x 1 -- delete-other-windows (\"1 window\") (find-enode \"Change Window\")
-C-x 2 -- split-window-vertically (Abv/Blw) (find-enode \"Split Window\")
-C-x 3 -- split-window-horizontally (L|R) (find-enode \"Split Window\")
+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_.
-Other keys / reference
-======================
-M-x -- execute-extended-command (find-enode \"M-x\")
- more about the minibuffer: (find-enode \"Minibuffer\")
-TAB -- for completion: (find-enode \"Completion\")
- for indentation: (find-enode \"Indentation\")
- in programming modes: (find-enode \"Basic Indent\")
+In a case like this,
- (find-enode \"Dired\")
-C-x C-f -- find-file (find-enode \"Visiting\")
-C-x C-s -- save-buffer (find-enode \"Saving\")
-C-x C-c -- save-buffers-kill-emacs (find-enode \"Saving\")
-C-x b -- switch-to-buffer (find-enode \"Select Buffer\")
-C-x k -- kill-buffer (find-enode \"Kill Buffer\")
+ �.three� (to \"three\")
+ �three� (to \".three\")
-C-a -- beginning-of-line (find-enode \"Moving Point\")
-C-e -- end-of-line (find-enode \"Moving Point\")
-M-< -- beginning-of-buffer (find-enode \"Moving Point\")
-M-> -- end-of-buffer (find-enode \"Moving Point\")
+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:
-M-q -- fill-paragraph (find-enode \"Fill Commands\")
+ (find-eev \"eev-intro.el\" \".find-eev-intro\")
-C-s -- isearch-forward (find-enode \"Incremental Search\")
-C-r -- isearch-backward (find-enode \"Incremental Search\")
-M-C-s -- isearch-forward-regexp (find-enode \"Regexp Search\")
-M-C-r -- isearch-backward-regexp (find-enode \"Regexp Search\")
-M-% -- query-replace (find-enode \"Replace\")
-C-x ( -- start-kbd-macro (find-enode \"Keyboard Macros\")
-C-x ) -- end-kbd-macro (find-enode \"Keyboard Macros\")
-C-x e -- call-last-kbd-macro (find-enode \"Keyboard Macros\")
-" rest)))
-;; (find-emacs-intro)
-;; (find-TH "emacs" "short-emacs-tutorial")
+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:
-;; �find-org-intro� (to ".find-org-intro")
-;; (find-intro-links "org")
+ comment-prefix �.anchor-name� (to \"anchor-name\")
+ comment-prefix �anchor-name� (to \".anchor-name\")
-(defun find-org-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-org-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-org-intro)
-Source code: (find-efunction 'find-org-intro)
-More intros: (find-eev-quick-intro)
- (find-eev-intro)
- (find-eval-intro)
- (find-eepitch-intro)
-This buffer is _temporary_ and _editable_.
-Is is meant as both a tutorial and a sandbox.
+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.
-Google Tech talk by Carsten Dominik (2008)
-==========================================
-http://orgmode.org/talks.html
-http://orgmode.org/worg/org-tutorials/org-screencasts/org-mode-google-tech-talk.html
-http://www.youtube.com/watch?v=oJTwQvgfgMM Emacs Org-mode - a system for
note-taking and project planning
-\(find-youtubedl-links \"/sda5/videos/\"
\"Emacs_Org-mode_-_a_system_for_note-taking_and_project_planning\"
\"oJTwQvgfgMM\" \".flv\" \"carsten2008\")
- (ee-youtubedl-hash-to-fname \"oJTwQvgfgMM\")
-\(setq ee-carsten2008 (ee-youtubedl-hash-to-fname \"oJTwQvgfgMM\"))
-\(code-mplayer \"carsten2008\" ee-carsten2008)
-\(find-carsten2008 \"0:00\")
+find-anchor
+===========
+\(find-eev \"eev-anchors.el\")
+\(find-eev \"eev-anchors.el\" \"find-anchor\")
-\(eev-avadj-mode 1)
-\(find-carsten2008 t)
-1:20 Carsten Start
-1:50 History
-2:15 Working with Text Files
-3:58 Notes (not tasks) based project planning
-5:50 Outline mode - fixing
-9:56 Structure Editing
-11:00 Note taking other supports
-13:35 Meta data Intro
-14:57 tags
-15:26 Timeplanning
-15:53 Properties
-16:02 Meta data propagation
-16:49 Special Meta entry interfaces
-17:55 DateTime interface
-18:24 Column view
-19:20 Capture with remember
-23:02 Collect and Display
-23:52 Sparse tree
-25:47 Agenda view
-27:27 Exporting and publishing
-29:05 Tables
-31:34 Calc
-32:44 Radio tables
-34:53 Context sensitive keys
-38:13 How is org used
-40:55 Evolved Software software
+code-c-d and :anchor
+====================
+\(find-eev \"eev-code.el\" \"ee-code-c-d-:anchor\")
-" pos-spec-list)))
-;; (find-org-intro)
+
+# Local Variables:
+# coding: raw-text-unix
+# ee-anchor-format: \"�%s�\"
+# End:
+" rest)))
+;; (find-anchors-intro)
-;; �find-eev-quick-intro� (to ".find-eev-quick-intro")
-;; (find-intro-links "eev-quick")
+;;; _
+;;; _ __ _ __ ___ _ __ __ _ _ __ ___ __| |
+;;; | '_ \| '__/ _ \ '_ \ / _` | '__/ _ \/ _` |
+;;; | |_) | | | __/ |_) | (_| | | | __/ (_| |
+;;; | .__/|_| \___| .__/ \__,_|_| \___|\__,_|
+;;; |_| |_|
+;;
+;; �find-prepared-intro� (to ".find-prepared-intro")
+;; (find-eev "eev-bounded.el")
-(defun find-eev-quick-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-eev-quick-intro)*"))
- (apply 'find-estring (ee-tolatin1 "\
-\(Re)generate: (find-eev-quick-intro)
-Source code: (find-efunction 'find-eev-quick-intro)
-More intros: (find-escripts-intro)
- (find-emacs-keys-intro)
- (find-eev-intro)
+(defun find-prepared-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-prepared-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-prepared-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-prepared-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.
-This is a tutorial for real beginners.
-It supposes that you have Emacs installed.
-You may start by watching these (old) videos:
-
- http://angg.twu.net/eev-videos/video-eev-quick-0.mp4 (installation basics)
- http://angg.twu.net/eev-videos/video-eev-quick-1.mp4 (about this tutorial)
- http://angg.twu.net/eev-videos/video4-eepitch.mp4 (all of eev's main ideas)
-
+Prepared shells
+===============
+Long before eepitch had been created, eev had another way -
+technically much simpler, but clumsier from the user's point of
+view - to send commands to external shells (and other shell-like
+programs; but to simplify we will say just \"shells\"). Here is
+an overview of how it worked: if the user marked the three lines
+below,
+ rm -Rv /tmp/foo
+ mkdir /tmp/foo/
+ cd /tmp/foo/
+and typed `M-x eev' (which stood for \"Emacs-execute-verbosely\")
+then Emacs would save those three lines into a temporary script
+file, usually \"~/.eev/ee.sh\"; that would be just half of
+\"sending commands to an external shell\", and for the other half
+the user would have to go to an external prepared shell - that
+would usually be running in an xterm, and totally independent
+from Emacs - and type \"ee\" there. The shell had to be
+\"prepared\" in the sense that it would understand the \"ee\"
+command correctly, as meaning: \"execute the commands in the
+temporary script as if the user were typing them at the prompt\".
+Technically, that would mean that instead of calling
+\"~/.eev/ee.sh\" as a shell script its contents would be
+\"sourced\" - i.e., executed in the current shell context - and
+in verbose mode.
-1. Installing eev
-=================
-Open the page at
+Usually we would prepare bash by patching the file ~/.bashrc and
+putting the definition for \"ee\" there. We will discuss how to
+do that later; now let's test a simple environment in which `M-x
+eev' and \"ee\" work. First execute these two sexps:
- http://angg.twu.net/eev-intros/find-eev-quick-intro.html
+ (make-directory \"~/.eev/\" 'force)
+ (eev \"rm -Rv /tmp/foo\\nmkdir /tmp/foo/\\ncd /tmp/foo/\\n\")
-in a browser, and open a terminal running a shell. Mark the multi-line
-\"{ ... }\" block below, copy it to the clipboard with ctrl-C, and paste
-it into the shell to run its commands.
+Now run this script
-{
- rm -Rv ~/eev
- rm -Rv ~/eev2/
- mkdir ~/eev2/
- cd ~/eev2/
- rm -v eev2.tgz
- wget http://angg.twu.net/eev-current/eev2.tgz
- tar -xvzf eev2.tgz
- {
- echo '#!/bin/sh'
- echo 'cd ~/eev2/ && emacs -l eev-readme.el
--eval=\"(find-eev-quick-intro)\" $*'
- } > ~/eev
- chmod 755 ~/eev
-}
+ (eepitch-bash)
+ (eepitch-kill)
+ (eepitch-bash)
+export PS1='$PWD# '
+function ee () { set -v; . ~/.eev/ee.sh; set +v; }
-You now have a shell script that you can invoke with
- ~/eev
-that starts Emacs, loads eev, and opens a copy of this tutorial.
+`ee'
+====
+\[Explain how several interpreters can be programmed to accept
+an `ee' command to execute temporary scripts\]
-Every time that Emacs gets stuck into something that you don't know
-how to leave, or how to undo, you should kill the Emacs window and
-start it again by typing \"~/eev\" again in the shell prompt.
+ http://angg.twu.net/eev-article.html#making-progs-receive-cmds
-Eventually you will learn how go get out of everything and how to undo
-almost anything, _BUT THAT WILL NOT HAPPEN IN THE FIRST TEN MINUTES_.
-This tutorial is intented to make you learn the most essential things
-in the first ten minutes - including how to navigate in Emacs's
-manuals.
+ (find-eev \"eev-langs.el\")
+ (find-eev \"eev-bounded.el\")
+ (find-eev \"eev-rctool\")
-For more on ways to install eev see:
- (find-eev-install-intro)
+An `ee' for Python
+==================
+Here is a simple way to make Python execute commands saved in a
+temporary script when the user types `ee()' (note that it is not
+just `ee' - the `()' is needed). We will show first an example in
+which the temporary script is prepared by running \"cat\" from a
+shell - then we will explain a more user-friendly way to save a
+region from the current buffer as the temporary script.
+Note that the demo below uses `find-wset', which is an
+advanced (i.e., hackish) feature explained here:
-2. Evaluating Lisp
-==================
-The most important idea in Emacs is that Lisp code can appear
-anywhere, and you can evaluate a Lisp expression (a \"sexp\") by
-placing the cursor (the \"point\") just after it and typing `C-x
-C-e'; the result is then displayed in the echo area.
+ (find-multiwindow-intro \"Several eepitch targets\")
-Note: `C-e' means control-E, `M-e' means alt-e, `M-E' means
-alt-shift-e. If you have Caps Lock on then Emacs will receive an `M-E'
-if you type alt-e, and `M-e' if you type alt-shift-e. Hint: avoid Caps
-Lock!
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+ (find-3ee '(eepitch-shell) '(eepitch-python))
+ (eepitch-python)
+import os
+def ee():
+ execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())
-You can try `C-x C-e' in the line below, with the point in the three
-different indicated positions - you should get different results...
+ (eepitch-shell)
+cat > ~/.eev/ee.py <<'%%%'
+print(1+2)
+%%%
- (+ (* 2 3) (* 4 5))
- ^ ^^
- | | \\
- 6 20 26
+ (eepitch-python)
+ee()
-...but `C-x C-e' is not beginner-friendly, and it even enters a
-debugger that is hard to leave if it finds errors, so let's see
-something better.
+ (eepitch-shell)
+cat > ~/.eev/ee.py <<'%%%'
+def foo (x):
+ return x*x
-When you type `M-e' emacs moves the point to the end of the
-current line, then runs a variant of `C-x C-e'. Try this on each
-line of the block below:
+print foo(5)
+%%%
- (+ (* 2 3)
- (* 4 5)
- )
+ (eepitch-python)
+ee()
+print(foo(6))
-`M-e' accepts several different numeric prefixes that alter its
-behavior. We are only interested in one of them now - `M-0 M-e'
-highlights the sexp for a fraction of a second insted of executing it.
-Try it above.
+`eepy'
+======
+The function `eev' receives three parameters, called `s', `e', and
+`altfile'; `e' and `altfile' are optional, and `s' should be either a
+string or a number. When `s' is a string, then the commands to be
+saved into the temporary script are taken from `s'; the numeric case
+will be discussed later.
+A call to
-3. Elisp hyperlinks
-===================
-Each one of the sexps below makes Emacs \"go somewhere\" if you execute
-it with `M-e'. Executing sexps like those - we will call them \"elisp
-hyperlinks\" - is like following a hyperlink in a browser.
+ (eev \"print(1+2)\" nil \"~/.eev/ee.py\")
-In a browser you can \"go back\" after following a hyperlink because the
-previous page is kept in the memory somehow. In Emacs+eev the easiest
-way to \"go back\" is with `M-k', which runs a function called
-`ee-kill-this-buffer'. If you follow one of the links below with
-`M-e', it creates a new buffer and displays it. If you then type `M-k'
-this new buffer is killed, and Emacs displays the buffer that was just
-below it, which is this tutorial... try it! Here are some nice elisp
-hyperlinks:
+writes \"print(1+2)\" (with an added trailing newline, but that's
+a technical detail) into the \"alternative file\"
+\"~/.eev/ee.py\" - the default would be \"~/.eev/ee.sh\". We can
+that to simplify our demo a bit:
- (find-fline \"/tmp/\")
- (find-efunctiondescr 'find-file)
- (find-man \"cat\")
+ (eek \"C-x 1\")
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
+import os
+def ee():
+ execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())
-Not all elisp hyperlinks \"go somewhere\"; some are like buttons that
-perform an action, like the one below, that acts as if the user had
-pressed a series of keys,
+ (eev \"print(1+2)\" nil \"~/.eev/ee.py\")
+ee()
+ (eev \"def foo (x):\\n return x*x\\n\\nprint foo(5)\" nil
\"~/.eev/ee.py\")
+ee()
+print(foo(6))
- (eek \"<down> C-a H E L L O ! <up> C-e\")
-and some display their output in the echo area:
+ In the example below the first line defines a `eepy' in a
+ simplistic way:
- (find-sh0 \"date\")
+ (defun eepy (s &optional e) (eev s e \"~/.eev/ee.py\"))
+ (eek \"C-x 1\")
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
+import os
+def ee():
+ execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())
-The following elisp hyperlinks may or may not work - try them too, but
-be aware that they may show errors instead of opening a new buffer.
-The first two of them open a page - actually a section, whose short
-title is \"Lisp Eval\" - from the main Emacs manual. The third one
-opens the file with the source code (in Lisp) for the function
-`find-file'.
+ (eepy \"print(1+2)\")
+ee()
+ (eepy \"def foo (x):\\n return x*x\\n\\nprint foo(5)\")
+ee()
+print(foo(6))
- (find-node \"(emacs)Lisp Eval\")
- (find-enode \"Lisp Eval\")
- (find-efunction 'find-file)
-If they don't work that means that you don't have the Emacs manuals,
-or the elisp source files, installed. The names for the packages which
-have those things vary from one GNU/Linux distro to another. On Debian
-something like
- sudo apt-get install emacs24-el
- sudo apt-get install emacs24-common-non-dfsg
-may work - but \"emacs24-common-non-dfsg\" may need you to enable
-access to the \"non-free\" respository... ask for help if you need!
+`M-x eepy' and `M-x eev'
+========================
+Now let's define a more realistic `eepy' - one that can also be
+called interactively. We want `M-x eepy' to save the current
+_region_ into the temporary script; `eepy' has to be a _command_,
+and we will use the argument \"r\" to its `interactive' clause,
+to make the function `eepy' receive two numbers - the start and
+the end of the region - and it will pass these two numbers to
+`eev'.
+ (defun eepy (s &optional e)
+ \"Save the region between S and E (or the string S) into ~/.eev/ee.py .\"
+ (interactive \"r\")
+ (eev s e \"~/.eev/ee.py\"))
+When the first argument, `s', to `eev', is a number, not a
+string, then `eev' expects the second argument, `e', to also be a
+number - and then `s' and `e' are considered as the extremities
+of a region of text in the current buffer. This idea - that the
+first argument can be either a string or a number - comes from:
-3.1. Non-elisp hyperlinks
--------------------------
-Emacs has ways to follow URLs, but the keys for that are totally
-different from the ones for elisp hyperlinks. You can follow the URL
-below by putting the point on it and typing `M-x browse-url':
+ (find-efunctiondescr 'write-region \"If START is a string\")
- http://www.lua.org/start.html
+But try these:
-This will make emacs invoke the default browser on that URL. See:
+ (ee-se-to-string \"foo\" nil)
+ (ee-se-to-string-with-nl \"foo\" nil)
+ (ee-se-to-string \"foo\\n\" nil)
+ (ee-se-to-string-with-nl \"foo\\n\" nil)
+ (ee-se-to-string (- (point) 5) (point))
+ (ee-se-to-string-with-nl (- (point) 5) (point))
+ (ee-se-to-string (point) (- (point) 5))
+ (ee-se-to-string-with-nl (point) (- (point) 5))
- (find-enode \"Browse-URL\")
-Eev defines several functions similar to `browse-url'. These elisp
-hyperlinks
- (find-firefox \"http://www.lua.org/start.html\";)
- (find-googlechrome \"http://www.lua.org/start.html\";)
-invoke \"firefox\" and \"google-chrome\" respectively on the given URL;
-note that the \"firefox\" in a Debian-based system is usually a free
-derivative of Firefox, and that \"google-chrome\" does not come
-installed by default because it is \"gratis\" but not free. Also,
+\[Garbage:\]
- M-x brff -- runs `find-firefox' on the URL at point,
- M-x brg -- runs `find-googlechrome' on the URL at point.
+ (find-elnode \"Defining Commands\")
+ (find-defun-intro \"\\ninteractive\\n\")
+ (find-efunction 'eev)
-For more on the \"brxxx functions\" of eev, see:
+" rest)))
- (find-brxxx-intro)
+;; (find-prepared-intro)
+;; (find-bashnode "Bourne Shell Builtins" "current shell context")
-4. Creating Elisp Hyperlinks
-============================
-You can write elisp hyperlinks by hand, but that is hard. It is better
-to generate hyperlinks automatically and then use cut and paste.
+;;; _ _ _
+;;; | |__ ___ _ _ _ __ __| | ___ __| |
+;;; | '_ \ / _ \| | | | '_ \ / _` |/ _ \/ _` |
+;;; | |_) | (_) | |_| | | | | (_| | __/ (_| |
+;;; |_.__/ \___/ \__,_|_| |_|\__,_|\___|\__,_|
+;;;
+;; �find-bounded-intro� (to ".find-bounded-intro")
+;; (find-intro-links "bounded")
+(defun find-bounded-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-bounded-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-bounded-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-bounded-intro\")
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
-Eev has several functions that generate \"elisp hyperlinks\" buffers.
-For example,
- (find-efunction-links 'find-file)
-creates this buffer, and switches to it:
- ___________________________________________________________
- |# (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)--|
- |___________________________________________________________|
+Note that you need to understand the concept of \"prepared
+shells\" quite well to be able to use this... see:
-One standard way of using eev is:
+ (find-prepared-intro)
- a) we keep our current notes in a a file - for example, \"~/TODO\"
- b) these notes are an \"executable log\" of what we did, including:
- c) hyperlinks to things we saw or visited
- d) commands issued to shells or shell-like programs (see sec. 6)
-The quickest way of generating hyperlinks for (c) is with `M-h M-h'
-\(`find-here-links'). When we type `M-h M-h' eev tries to generate an
-elisp hyperlinks buffer containing some hyperlinks to \"here\" - and how
-it does that depends on the major mode and on the name of the current
-buffer. For example, typing `M-h M-h' here generates:
- ____________________________________________________________
- |# See: |
- |# (find-links-intro \"`find-here-links'\") |
- |# (find-efunctiondescr 'eev-mode \"M-h M-h\") |
- | |
- |http://angg.twu.net/eev-intros/find-eev-quick-intro.html |
- |# (find-eev-quick-intro) |
- | |
- | |
- |--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
- |____________________________________________________________|
+Bad news: I've been using this feature very little, and I have
+not yet adapted the old, crappy docs to the new \"intro\"
+format... =\\ So this is just a bunch of notes!
-The
+Source code: \(find-eev \"eev-bounded.el\")
+Obsolete related code: \(find-eev \"eev-langs.el\")
+Old mentions to this: \(find-TH \"eev-article\" \"delimited-regions\")
+ http://angg.twu.net/eev-article.html#delimited-regions
- # (find-eev-quick-intro)
-opens this tutorial.
-Cutting and pasting is explained briefly in section 5.2.
-A way to \"refine\" hyperlinks to make them more precise is
-explained here:
+Delimited (\"bounded\") regions
+===============================
+Try:
- (find-eval-intro \"Producing and refining hyperlinks\")
+#
+# (eev-bounded)
+cd
+echo At: $PWD
+cd /tmp/
+echo At: $PWD
+
+#
+%
+% (eelatex-bounded)
+Hello
+%
+Defining new bounded functions
+==============================
+Try:
-5. Links to Emacs documentation
-===============================
-Try these links (some of them need the Emacs manuals installed):
+ (find-code-bounded 'eev-bounded 'eev \"\\n#\\n\")
+ (find-code-bounded 'eev-bounded 'eev 'ee-delimiter-hash)
- (find-emacs-intro \"Cutting & pasting\")
- (find-node \"(emacs)Screen\")
- (find-efunctiondescr 'find-file)
- (find-efunction-links 'find-file)
+as usual, when we remove the \"find-\"s the generated code is
+executed instead of displayed.
-This part of the eev tutorials has links to almost all the keys that
-I've learned by heart after using Emacs for 20 years:
- (find-emacs-intro \"Basic keys (Emacs)\")
-They are not very many, because I use this a lot,
- (find-node \"(emacs)M-x\")
+The default bounded function
+============================
+...is stored in the variable `ee-bounded-function', and can be
+re-run with `M-x ee-bounded-function' (i.e., there's a function
+with the same name as the variable). I used to bind `f3' to that,
+but in modern Emacsen this is bound to a macro key:
-and I use elisp hyperlinks to create quick reminders for the keys that
-I only need to remember when I am performing specific tasks.
+ (find-enode \"Basic Keyboard Macro\" \"<F3>\")
-Moral: when you want a quick reference of the main Emacs and eev keys,
-type `M-2 M-j'.
+so you should do something like this, but for your favourite key:
+ (define-key eev-mode-map [f3] 'ee-bounded-function)
+" pos-spec-list)))
+;; (find-bounded-intro)
-5.1. Navigating the Emacs manuals
----------------------------------
-The Emacs manuals are in \"info\" format, which means:
- a) they are divided into \"nodes\" - a top node, and chapters,
- sections, subsections, etc,
- b) the nodes in each manual in info format are organized as a tree,
- and they're all numbered except for the top node, the indexes and
- the appendixes. For example:
- top --.-- 1 --.-- 1.1
- | `-- 1.2
- |-- 2
- |-- 3 ----- 3.1 --.-- 3.1.1
- | |-- 3.1.2
- | `-- 3.1.3
- |-- Appendix A
- `-- Index
+;;; _ _
+;;; ___| |__ __ _ _ __ _ __ ___| |___
+;;; / __| '_ \ / _` | '_ \| '_ \ / _ \ / __|
+;;; | (__| | | | (_| | | | | | | | __/ \__ \
+;;; \___|_| |_|\__,_|_| |_|_| |_|\___|_|___/
+;;;
+;; �find-channels-intro� (to ".find-channels-intro")
+;; (find-intro-links "channels")
- c) each node also has a short name. Elisp hyperlinks use the
- (internal) name of the manual and the short name to jump straight
- to a node in a manual. The table below has some examples:
+(defun find-channels-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-channels-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-channels-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-channels-intro\")
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
- Manual (full name) Node \"number\" elisp hyperlink
- -----------------------------------------------------
- Emacs Top (find-node \"(emacs)\")
- Emacs 7 (find-node \"(emacs)Basic\")
- Emacs 7.4 (find-node \"(emacs)Basic Undo\")
- Emacs Concept Index (find-node \"(emacs)Concept
Index\")
- Emacs Lisp Top (find-node \"(elisp)\")
- d) Emacs uses \"Info mode\" when displaying nodes of manuals in info
- format. These are the most important keys of Info mode:
- q exit (go back to some other buffer)
- (arrows) move point
- RET follow link at point
- TAB move to next link
- BACKTAB move to prev link
- n next (1->2->3->Appendix A; 3.1.1->3.1.1->3.1.2)
- p previous (1<-2<-3<-Appendix A; 3.1.1<-3.1.1<-3.1.2)
- u up (Top<-1<-1.1; 1<-1.2; 3<-3.1<-3.1.2, etc)
- ] forward-node (Top->1->1.1->1.2->2->3->3.1->...->Index)
- [ backward-node (Top<-1<-1.1<-1.2<-2<-3<-3.1<-...<-Index)
+Introduction
+============
+Before eepitch had been invented, eev had two other ways to send
+commands to external shell-like programs. The first way,
+described here,
-Try the keys above now - they are VERY important! Use:
+ (find-prepared-intro \"\\n`ee'\\n\")
- (eek \"<down> M-3 M-e ;; open the hyperlink below in another window\")
- (find-node \"(emacs)Basic\")
- (find-node \"(emacs)Major Modes\")
+was technically very simple: running `M-x eev' would save a
+series of commands - usually the contents of the region - into a
+temporary script file, and then the user would type something
+like `ee' at the prompt of a (\"prepared\") shell; that would
+make it read the saved commands and execute them.
+Here we will describe the second of the Old Ways - one in which
+the target program, which is usually a shell running in an xterm,
+is sent a signal saying \"execute the command NOW\" as soon as a
+command is saved into a temporary file by Emacs. The difficulty
+is that this requires not only a directory for temporary files,
+but also an Expect script, which acts as an intermediary that
+listens to signals and handles them pretending that the saved
+commands came from the keyboard... and, as some people have said,
+this is \"a nightmare to set up\".
+Here we explain the protocol - which can be adapted to other
+cases too, like, for example, to make Emacs talk to SmallTalk
+environments and to computer algebra systems with GUIs - and we
+will present several tests that should help with troubleshooting.
-5.2. Cutting and pasting
-------------------------
-You can do cut, copy and paste in a \"user-friendly\" way by using
- a) the rightmost icons in the toolbar, or
- b) the \"Edit\" menu in the menu-bar,
-but the keys are very much worth learning:
+The innards
+===========
+Let's start with a detailed low-level view of of what we have
+just summarized as to \"save a command into a temporary file,
+then send a signal to the external program etc etc\".
- C-SPC -- set-mark-command (find-enode \"Setting Mark\")
- C-x C-x -- exchange-point-and-mark (find-enode \"Setting Mark\" \"C-x
C-x\")
- C-w -- kill-region (cut) (find-enode \"Other Kill Commands\")
- M-w -- kill-ring-save (copy) (find-enode \"Kill Ring\")
- C-y -- yank (paste) (find-enode \"Kill Ring\")
+Warning: this document is still VERY INCOMPLETE, and some parts
+of it are just notes, drafts, and links that may not work for
+you... =(
-The \"region\" where cut & paste operate is always what is between
-the \"point\" and the \"mark\". See:
+ (find-eev \"eegchannel\")
+ (find-eev \"anim/\")
+ (find-eev \"anim/channels.anim\")
+ http://angg.twu.net/eev-current/eegchannel.html
- (find-enode \"Point\")
- (find-enode \"Mark\")
-Exercise: understand how the `eek' sexp below switches the two
-lines just after it.
- (eek \"<down> C-a C-SPC <down> C-w <down> C-y 3*<up>\")
- First
- Second
+The protocol, in diagrams
+=========================
+Here's a diagram that shows roughly what we have when X is
+running both an Emacs and an xterm, each in a separate window.
+Many details have been omitted - for examples, the real
+communication happens through fifos and ptys, that are not shown
+- but it's easy to build a complete diagram from this. The arrows
+indicate flow of information.
+ keyboard mouse display
+ | | ^
+ v v |
+ +----------------------------+
+ | |
+ | X |
+ | |
+ +----------------------------+
+ key/mouse | ^ display key/mouse | ^ display
+ events v | commands events v | commands
+ +---------+ +---------+
+ | | | |
+ | emacs | | xterm |
+ | | | |
+ +---------+ +---------+
+ chars and | ^ chars and
+ signals v | signals
+ +---------+
+ | |
+ | sh |
+ | |
+ +---------+
+To make the external shell at the right able to receive commands
+from Emacs we will insert a program between the \"xterm\" and the
+\"sh\" boxes - an Expect script called eechannel, that will
+usually be totally transparent, in the sense that it will let all
+the chars and signals that it receives pass through it without
+changes.
+The trick is that \"eechannel\" will also be \"listening to
+commands from the outside\", according to the following protocol:
+ 1) each instance of eechannel \"listens\" to a fixed, named
+ \"channel\"; for simplicity, let's suppose that this name is
+ \"A\".
+ 2) When an eechannel receives a signal SIGUSR1 it reads a
+ string from the file \"eech.A.str\" and sends that to the
+ shell, as if the user had typed that.
-6. Controlling shell-like programs
-==================================
-This is the second main feature of eev. The hyperlinks thing used the
-keys `M-e', `M-k', and `M-h M-h', plus standard Emacs keys for cutting
-and pasting. The module of eev that controls shell-like programs - it
-is called \"eepitch\" - uses `<F8>' and `M-T'. Note that it is
-`alt-shift-t', to not interfere with Emacs's `M-t'.
+ 3) To make it simpler to send the signal, when eechannel starts
+ up it saves its pid into the file \"eech.A.pid\".
-The sections below were adapted from:
+That protocol can be depicted as the four horizontal arrows
+below; the temporal order is from top to bottom.
- (find-eepitch-intro \"The main key: <F8>\")
+ +-------------+
+ | |
+ | xterm |
+ | |
+ +-------------+
+ +-----------+ | ^
+ | | --> eeg.A.str v |
+ | emacs | <-- eeg.A.pid +-------------+
+ | | -----------------> | |
+ +-----------+ eeg.A.str ---> | eechannel A |
+ | |
+ +-------------+
+ | ^
+ v |
+ +-------------+
+ | |
+ | sh |
+ | |
+ +-------------+
+When Emacs wants to send a line, say, \"cd /tmp/\", to eechannel,
+it does this:
+ 1) \"--> eeg.A.str \" writes \"cd /tmp/\" into eech.A.str,
+ 2) \"<-- eeg.A.pid \" reads eechannel's pid from eech.B.str,
+ 3) \"----------------->\" sends a signal SIGUSR1 to that pid,
+ 4) \" eeg.A.str --->\" ...and when eechannel receives a SIGUSR1
+ it reads the contents of eech.A.str and
+ sends that to its spawned shell.
+Actually there's something else - how these programs are started.
+If we run just \"xterm\", it behaves in its default way, and runs
+a shell. But if we run
-6.1. 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 |
- |_________|_________|
+ \"xterm -e eechannel A /bin/sh\"
-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>.
+then xterm runs \"eechannel A /bin/sh\" instead of just
+\"/bin/sh\"; and \"eechannel A /bin/sh\" runs \"/bin/sh\".
-Here's what <F8> does:
+Also, evaluating this
- 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.
+ (find-bgprocess \"xterm\")
- \"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.
+from Emacs runs an xterm, which runs a shell; evaluating either
+of these sexps,
-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.
+ (find-bgprocess \"xterm -e eechannel A /bin/sh\")
+ (find-bgprocess \"xterm -e eechannel A $SHELL\")
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-echo \"We are at: $PWD\"
-cd /tmp/
-echo \"We changed to: $(pwd)\"
+runs an xterm, which runs the \"eechannel\" script, which runs a
+shell. The sexp
+ (eexterm \"A\")
+is a shorthand for the one using \"$SHELL\". Also, note that
+\"eechannel A ...\" saves its pid into \"eech.A.pid\".
+The diagram that shows what happens when we run `(eexterm \"A\")'
+is this one, below - note that the four arrows of the sending
+protocol are not shown.
-6.2. 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:
+ +------------+
+ | |
+ | X |
+ | |
+ +------------+
+ / ^ \\ ^
+ v / v \\
+ +-----------+ +-------------+
+ | | initiates | |
+ | emacs |:::::::::::>| xterm |
+ | | | |
+ +-----------+ +-------------+
+ :: | ^
+ \\/ v |
+ +-------------+
+ | |
+ eeg.A.pid <-- | eechannel A |
+ | |
+ +-------------+
+ :: | ^
+ \\/ v |
+ +-------------+
+ | |
+ | sh |
+ | |
+ +-------------+
- (eepitch-python)
- (eepitch-kill)
- (eepitch-python)
-def square (x):
- return x*x
-print(square(5))
- We can use several targets at the time, alternating between them.
- For example:
+Downloading and testing eechannel
+=================================
+Here I'll suppose that the directory \"~/bin/\" exists and is in
+your PATH. Run this to download the \"eechannel\" script and make
+it executable:
(eepitch-shell)
(eepitch-kill)
(eepitch-shell)
-echo Hello... > /tmp/o
+cd ~/bin/
+# See: http://angg.twu.net/bin/eechannel.html
+wget -n http://angg.twu.net/bin/eechannel
+chmod 755 eechannel
- (eepitch-python)
- (eepitch-kill)
- (eepitch-python)
-print(open(\"/tmp/o\").read())
+Now let's test - from Emacs - if a local copy of \"eechannel\"
+exists, is in your PATH, and can be executed (remember that it
+needs Expect). Calling \"eechannel\" with not enough arguments
+should yield a nice error message.
- (eepitch-shell)
-echo ...and bye >> /tmp/o
+ (find-fline \"~/bin/eechannel\")
+ (find-sh \"~/bin/eechannel\")
+ (find-sh \"eechannel\")
- (eepitch-python)
-print(open(\"/tmp/o\").read())
+It uses the environment variable EEVTMPDIR to decide where the
+temporary files - ee.CHANNELAME.pid, ee.CHANNELNAME.str - will
+be, so let's check that this directory exists:
+ (getenv \"EEVTMPDIR\")
+ (find-fline \"$EEVTMPDIR/\")
+Running eechannel with a first argument \"-v\" should show a lot
+of info, and then save the pid at eech.CHANNELAME.pid and run the
+given command. Let's try with a command that exits immediately.
+ (find-sh \"eechannel -v A /bin/true\")
+ (find-fline \"$EEVTMPDIR/\" \"eech.A.pid\")
-6.3. 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.
+Now let's verify - using just eepitch, without xterm at this
+moment - whether eechannel is being able to receive signals. In
+the eepitch script below, two `(find-sh0 \"kill ...\")'s should
+each make the controlled program receive a command - at the first
+\"kill\" an \"echo 2\", at the second an \"echo 3\".
-shell
-pwd
-cd /tmp/
-pwd
+ (eepitch-comint \"A\" \"eechannel -v A /bin/sh\")
+ (eepitch-kill)
+ (eepitch-comint \"A\" \"eechannel -v A /bin/sh\")
+echo 1
+ (find-sh0 \" cat $EEVTMPDIR/eech.A.pid\")
+ (find-sh0 \"echo 'echo 2' > $EEVTMPDIR/eech.A.str\")
+ (find-sh0 \" cat $EEVTMPDIR/eech.A.str\")
+ (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
+
+ (find-sh0 \"echo 'echo 3' > $EEVTMPDIR/eech.A.str\")
+ (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
+echo 4
+If the eepitched shell did run \"echo 1\", \"echo 2\", \"echo
+3\", \"echo 4\", then things are working - \"echo 1\" and \"echo
+4\" were sent through eepitch, but \"echo 3\" and \"echo 4\" were
+sent though channels.
+Now let's check if we can run an xterm, and if it can run an
+eechannel-ed shell instead of a plain shell. Check if the second
+sexp above starts an xterm, displays the info from \"eechannel
+-v\", and then runs a shell:
-6.4. 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-bgprocess \"xterm\")
+ (find-bgprocess \"xterm -e eechannel -v A $SHELL\")
+ (find-bgprocess \"xterm -e eechannel A $SHELL\")
+if that worked, run the four sexps below with <f8>,
+ (find-sh0 \"echo 'echo 1' > $EEVTMPDIR/eech.A.str\")
+ (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
+ (find-sh0 \"echo 'echo 2' > $EEVTMPDIR/eech.A.str\")
+ (find-sh0 \"kill -USR1 $(cat $EEVTMPDIR/eech.A.pid)\")
+and check if the eechannel-ed shell in the xterm has received the
+commands \"echo 1\" and \"echo 2\". If it did, try the
+higher-level version below - but use <f9>s on each line instead
+of the <f8>s:
-7. Quick access to one-liners
-=============================
+ (eexterm \"A\")
+echo 3
+echo 4
+If that worked, we're done. =)
-7.1. eejump
------------
-We may have elisp one-liners that we want to be able to execute very
-quickly, and from anywhere. For example, I keep all my notes that I
-have not organized yet in a file called \"~/TODO\", and if I type
- M-1 M-j
-then I \"jump\" to \"~/TODO\" - the effect is the same as running this:
+Several xterms
+==============
+http://angg.twu.net/eev-current/anim/channels.anim.html
- (find-fline \"~/TODO\")
+ (eexterm \"A\")
+ (eexterm \"B\")
+# listen on port 1234
+netcat -l -p 1234
-Note that `M-1 M-j' can be typed as:
+ (eexterm \"A\")
+# Send things to port 1234 (on localhost)
+{
+ echo hi
+ sleep 1
+ echo bye
+ sleep 1
+} | netcat -q O localhost 1234
- hold the meta key,
- type 1,
- type j,
- release the meta key.
-instead of:
- hold the meta key,
- type 1,
- release the meta key,
- hold the meta key,
- type j,
- release the meta key;
-There is no need to release and press agian the meta key between
-the `1' and the `j'.
-Internally, what happens when you type `M-1 M-j' is this:
- `M-j' is bound to `eejump',
- `M-1 M-j' runs `eejump' with argument 1, i.e., (eejump 1)
- (eejump 1) runs (eejump-1)
- (eejump-1) has been defined with:
+\[NOT DONE YET. The rest is (recyclable) garbage.\]
- (defun eejump-1 () (find-fline \"~/TODO\"))
-So `M-1 M-j' runs the one-liner `(find-fline \"~/TODO\")',
-`M-5 M-j' runs the one-liner `(find-eev-quick-intro)',
-and so on.
-7.2. The list of eejump targets
--------------------------------
-If you type `M-j' without a prefix argument then it runs
-`(find-eejumps)', that displays all the current eejump targets as
-defuns, one in each line. Try it:
- (eek \"M-j\")
- (find-eejumps)
+\(Old stuff:)
-You will see that two of those entries are:
+ emacs runs: (find-bgprocess \"xterm -T 'channel A' -e eegchannel A /bin/sh\")
+ xterm runs: eegchannel A /bin/sh
+ eegchannel saves its pid at ~/.eev/eeg.A.pid and runs: /bin/sh
- (defun eejump-1 () (find-fline \"~/TODO\"))
- (defun eejump-5 () (find-eev-quick-intro))
+At this point the xterm is running a shell that is \"listening on
+channel A\"; eegchannel pretends to be transparent and passes all
+characters and signals in the vertical arrows transparently - but when
+it receives a certain signal (a SIGUSR1) it reads the contents from
+the file ~/.eev/eeg.A.str and passes it to the shell, as if those
+characters were coming from the xterm - i.e., as if the used had typed
+them.
+
+Here are the details of this \"protocol\":
+when we type F9 on a line containing \"echo foo\",
+
+ emacs saves the string \"echo foo\\n\" into ~/.eev/A.str,
+ emacs reads the pid of eegchannel from ~/.eev/eeg.A.pid (say, \"1022\"),
+ emacs runs \"kill -USR1 1022\",
+ eegchannel reads the string from ~/.eev/A.str, and sends it to the shell.
+NOTE: one frequent question is: \"why are you using two normal files
+and SIGUSR1s for the communication between emacs and eegchannel,
+instead of making them talk through a fifo?\" - the answer is: try to
+explain the details of fifos - including creation - to someone who
+knows little about the inner workings of a *NIX kernel and who is
+uncomfortable to accept another kind of black box... The way with two
+files and SIGUSR1s is simpler, works well enough, and I've been able
+to write all the code for it in a few hours - and I still don't know
+enough about fifos to implement a fifo version of this.
+and another one, that was mostly used to control external
+programs running in dedicated xterms. You can see an animation
+demonstrating it - and an explanation of what each line does -
+here:
-7.3. Defining eejump targets
-----------------------------
-We can define new eejump targets, or overwrite the current ones, by
-just running `defun's to define functions with names starting with
-`eejump-'. Try:
+ http://angg.twu.net/eev-current/anim/channels.anim.html
+ http://angg.twu.net/eev-current/doc/shot-f9.png
- (defun eejump-9 () (find-eev-quick-intro \"7.2.\"))
- (defun eejump-9 () (find-eev-quick-intro \"7.3.\"))
- (fmakunbound 'eejump-9)
- (find-eejumps)
-Note that if you type `M-J' (i.e., meta-uppercase-j,
-`eewrap-eejump') on the line below then it will be converted into
-the first \"(defun eejump- ...)\" above:
- 9 (find-eev-quick-intro \"7.2.\")
+How to set it up
+================
+\[To be written\]
-An advanced feature: if you type `M-J' on a line that starts with
-something that is not a number, you get a defun for a \"command
-with a very short name\" like the ones that are described in the
-next section. Try it now:
+ ssh address@hidden
+ eegchannel A ssh address@hidden
+ (find-prepared-intro \"\\n`ee'\\n\")
+ (find-eev \"anim/channels.anim\")
+" pos-spec-list)))
- (eek \"<down> M-J\")
- e (find-fline \"/tmp/foo.tex\")
+;; (find-channels-intro)
-7.2. Commands with very short names
------------------------------------
-Let's start with an example. If we are editing a LaTeX file, say
-\"/tmp/foo.tex\", then it is convenient to have quick ways to:
- c) compile \"foo.tex\" into a \"foo.pdf\",
- d) display the resulting \"foo.pdf\",
- e) jump to \"foo.tex\" from anywhere to edit it.
+;;; _ _
+;;; __ _(_) __| | ___ ___ ___
+;;; \ \ / / |/ _` |/ _ \/ _ \/ __|
+;;; \ V /| | (_| | __/ (_) \__ \
+;;; \_/ |_|\__,_|\___|\___/|___/
+;;;
+;; �find-videos-intro� (to ".find-videos-intro")
+;; (find-intro-links "videos")
-If our \"/tmp/foo.tex\" starts with these lines
+(defun find-videos-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-videos-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-videos-intro)
+Source code: (find-efunction 'find-videos-intro)
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
- % (defun c () (interactive) (find-sh \"cd /tmp/; pdflatex foo.tex\"))
- % (defun d () (interactive) (find-xpdfpage \"/tmp/foo.pdf\"))
- % (defun e () (interactive) (find-fline \"/tmp/foo.tex\"))
-and we execute these defuns, then from that point on `M-x c', `M-x d'
-and `M-x e' will do \"compile\", \"display\" and \"edit\" on \"foo.tex\", as
-described above.
-For more on `M-x', and on why the defuns above need the
-\"(interactive)\", see:
+1. What we have now
+===================
+I am producing a series of videos about eev - but at this moment
+only two very broad introductions are ready 8-(. I have plans for
+several short videos about specific usage patterns, but don't
+hold your breath yet... also, these are my first videos EVER - so
+please excuse any stutterings, hesitations and false starts...
- (find-node \"(emacs)M-x\")
- (find-node \"(emacs)Commands\")
- (find-node \"(elisp)Defining Commands\")
+The videos are uploaded to Youtube to make them very easy to
+find, but Youtube reduces the resolution of the original videos
+and makes them blurry and almost unreadable - so the best way to
+watch them is to fetch local copies of the high-res .mp4 files.
+2. Downloading local copies
+===========================
+Here are direct links to both the low-res versions at Youtube
+and to the corresponding high-res \".mp4\"s:
-7.3. `find-latex-links'
------------------------
-The easiest way to put the three defuns of the last section in
-the header of a LaTeX file is with:
+ Eepitch: a way to control shell-like programs from Emacs
+ http://www.youtube.com/watch?v=Lj_zKC5BR64
+ http://angg.twu.net/eev-videos/video4-eepitch.mp4
- (find-latex-links \"/tmp/foo\")
+ An introduction to eev2 (2012nov11)
+ http://www.youtube.com/watch?v=doeyn5MOaB8
+ http://angg.twu.net/eev-videos/video2.mp4
-`find-latex-links' is just one of several template functions that
-generate commands with very short names. Here's how to use it -
-the other ones are similar.
+\(The video about eepitch is shorter and far better than the
+other one - please start by it.)
- 1) Run `M-x find-latex-links'. You will get a buffer whose top
- line is:
+The ideas behind \"local copies\" are here:
- # (find-latex-links \"{stem}\")
+ (find-psne-intro)
- 2) Edit that, and change the \"{stem}\" to \"/tmp/foo\".
+These sexps generate the download scripts in temporary buffers:
- 3) Execute that top line, which is now:
+ (find-eev-video-links \"eepitchvideo\" \"video4-eepitch\" \"Lj_zKC5BR64\")
+ (find-eev-video-links \"eevvideo\" \"video2\" \"doeyn5MOaB8\")
- # (find-latex-links \"/tmp/foo\")
- You should get:
- _____________________________________________________________________
- |# (find-latex-links \"/tmp/foo\") |
- |# (find-eev-quick-intro \"`find-latex-links'\") |
- |# (ee-copy-rest 1 '(find-fline \"/tmp/foo.tex\")) |
- | |
- |% (defun c () (interactive) (find-sh \"pdflatex foo.tex\")) |
- |% (defun d () (interactive) (find-pdf-page \"/tmp/foo.pdf\")) |
- |% (defun e () (interactive) (find-fline \"/tmp/foo.tex\")) |
- |% |
- |\\documentclass{article} |
- |\\begin{document} |
- | |
- |\\end{document} |
- | |
- | |
- | -:**- *Elisp hyperlinks* All L1 (Fundamental) |
- |_____________________________________________________________________|
+3. Hyperlinks to the local copies of the videos
+===============================================
+Notice that the download scripts above contain these sexps:
- 4) Execute the line with the \"(ee-copy-rest ...)\". You should get this -
- the window on the right is visiting the file \"/tmp/foo.tex\":
+\(code-video \"eepitchvideo\"
\"$S/http/angg.twu.net/eev-videos/video4-eepitch.mp4\")
+\(code-video \"eevvideo\" \"$S/http/angg.twu.net/eev-videos/video2.mp4\")
- ______________________________________________________________________
- |# (find-latex-links \"/tmp/foo\") | |
- |# (find-eev-quick-intro \"`find-lat| |
- |# (ee-copy-rest 1 '(find-fline \"/t| |
- | | |
- |% (defun c () (interactive) (find-| |
- |% (defun d () (interactive) (find-| |
- |% (defun e () (interactive) (find-| |
- |% | |
- |\\documentclass{article} | |
- |\\begin{document} | |
- | | |
- |\\end{document} | |
- | | |
- | | |
- | -:**- *Elisp hyperlinks* All L| -:**- foo.tex All L9 |
- |_(Copied 8 lines to the kill ring - use C-y to paste)________________|
+After you execute them hyperlinks like these should work:
+ (find-eepitchvideo)
+ (find-eevvideo)
- 5) Go to the window on the right and type `M-y'. You should get this,
+Note that they use mplayer to display the videos, and if you
+don't have mplayer - or if you haven't downloaded the \".mp4\"s -
+then you will get error messages in the \"*Messages*\" buffer.
+You can inspect them with `C-x b *Messages*' or with:
- ______________________________________________________________________
- |# (find-latex-links \"/tmp/foo\") |% (defun c () (interactive) (find-|
- |# (find-eev-quick-intro \"`find-lat|% (defun d () (interactive) (find-|
- |# (ee-copy-rest 1 '(find-fline \"/t|% (defun e () (interactive) (find-|
- | |% |
- |% (defun c () (interactive) (find-|\\documentclass{article} |
- |% (defun d () (interactive) (find-|\\begin{document} |
- |% (defun e () (interactive) (find-| |
- |% |\\end{document} |
- |\\documentclass{article} | |
- |\\begin{document} | |
- | | |
- |\\end{document} | |
- | | |
- | | |
- | -:**- *Elisp hyperlinks* All L| -:**- foo.tex All L9 |
- |_____________________________________________________________________|
+ (find-ebuffer \"*Messages*\")
- and you can now save the file foo.tex (hint: use `C-x C-s'!),
- execute the three defuns for `c', `d', and `e', and jump to
- \"/tmp/foo.tex\" from anywhere with `M-x e'.
+4. Hyperlinks to positions
+==========================
+The first argument to `find-eepitchvideo' and to other similar
+functions is a time offset; it is optional, and it defaults to
+\"0:00\". Any further arguments are ignored, and this allows us
+to use them as comments. So these two sexps are equivalent:
+ (find-eepitchvideo \"0:16\")
+ (find-eepitchvideo \"0:16\" \"the eepitch-to-shell-and-python example\")
-8. Anchors
-==========
+We could use a series of `find-eepitchvideo' sexps to create a
+\"table of contents\" for a video, similarly to what we do for
+written documents...
-8.1. Introduction: `to'
------------------------
-A hyperlink like
- (to \"foo\")
-jumps to the first occurrence of the string \"�foo�\" in the
-current buffer. The function that wraps a string in `��'s is
-called `ee-format-as-anchor', and the sexp `(to \"foo\")'
-is equivalent the second sexp below:
+5. Time offsets as hyperlinks to positions
+==========================================
+In some cases using sexps creates too much visual clutter, and we
+would like to be able to create an index or table of contents
+writing lines just like this,
- (ee-format-as-anchor \"foo\")
- (ee-goto-position (ee-format-as-anchor \"foo\"))
+ 0:16 the eepitch-to-shell-and-python example
-We will call strings in `��'s _anchors_, and we will say
-that `(to \"foo\")' jumps \"to the anchor `foo'\". The string
-inside a `��'s is called a _tag_.
+instead of using explicit elisp hyperlinks.
-In a situation like this,
+There is a way to do this, but it is tricky. It involves
+activating a mode, called `eev-avadj-mode', in which `M-p' is
+bound to a command that locates the first thing looking like a
+time offset in the current line, and calls the video player to
+make it play the *current default video* starting from that time
+offset; a sexp like
- �one� (to \"two\")
- �two� (to \"three\")
- �three� (to \"four\")
- �four� (to \"one\")
+ (find-eepitchvideo t)
-we have four anchors, and typing `M-e' at the line with the
-anchor \"one\" takes us to the line with the anchor \"two\",
-typing `M-e' at the line with the anchor \"two\" takes us to the
-line with the anchor \"three\", typing `M-e' again takes us to
-the line with the anchor \"four\", and typing `M-e' again takes
-us back to the line with the anchor \"one\". In a situation like
-this we say that the anchors \"one\", \"two\", \"three\", and
-\"four\" _point to one another_.
+just sets the current default video, but does not invoke the
+player. All this is explained here:
-In a case like this,
+ (find-audiovideo-intro \"The time-from-bol\")
- �.five� (to \"five\")
- �five� (to \".five\")
-where the names of two anchors pointing to one another differ by
-an initial dot, we will say that the anchor \".five\" is the
-\"index anchor\", and the anchor \"five\" 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\")
+6. Eepitch video: table of contents
+===================================
+\(find-eev-video-links \"eepitchvideo\" \"video4-eepitch\" \"Lj_zKC5BR64\")
+\(eev-avadj-mode 1)
+\(find-eepitchvideo t)
+0:16 the eepitch-to-shell-and-python example, very quickly
+1:18 executing eepitch scripts with `f8's; f8 on red star lines and normal
lines
+2:33 the eepitch-to-shell-and-python example - what each line does
+3:15 the first three lines use advanced features
+3:52 eepitch scripts are made to be executed interactively
+5:25 the eepitch-to-shell-and-python example again, more slowly
-8.2. Creating anchors by hand
------------------------------
-One way to type the chars `�' and `�' is with `C-x 8 <' and
-`C-x 8 >'. Try:
+5:58 what happens when the eepitch target is being shown
+7:13 the default is to use two windows
+7:33 what happens when the target does not exist
+8:25 how to send commands to a new shell
+8:54 how an eepitch block (like eepitch-shell/kill/shell) works
- (eek \"RET C-x 8 < t a g C-x 8 >\")
+9:38 an example with shell comments (which eev uses as hyperlinks)
+12:35 refining hyperlinks
+12:35 converting shell commands into hyperlinks (by wrapping - by hand)
+13:04 wrapping commands - bound to meta-uppercase-letters
+13:53 M-M wraps the current line into a hyperlink to a manpage
+14:12 demonstrating M-M, M-S and M-T with eek sexps
+14:40 M-T wraps the current linto an eepitch-xxx/kill/xxx triple
+15:47 introduction to the sandboxed tutorials and to M-j (eejump)
+16:17 the default numeric arguments for eejump
+16:35 M-5 M-j jumps to the index for the documentation for eev
+17:15 temp. eev buffers usually start with a sexp that regenerates the buffer
+18:23 where the eepitch-to-shell-and-python example is in the documentation
+18:58 Other examples
+19:07 pdf-like documents
+20:43 a tutorial for Lua based on eepitch
+22:26 that's it - last comments, where to find more info, how to get in touch
-8.3. Creating index/section anchor pairs
-----------------------------------------
-Eev has several commands that transform the text in the current
-line into something more complex. They are all called
-`eewrap-(something)', and they are bound to
-meta-uppercase-letters. The simplest examples are `M-F', `M-S'
-and `M-M', that just \"wrap the text in the current line into an
-elisp hyperlink\" by adding a prefix and a suffix; if you run
-`M-F', `M-S' and `M-M' in the following lines
+7. Eev video: table of contents
+===============================
+\(find-eev-video-links \"eevvideo\" \"video2\" \"doeyn5MOaB8\")
+\(eev-avadj-mode 1)
+\(find-eevvideo t)
-/tmp/
-ls /tmp/
-ls
+ 0:00 introduction
+ 2:45 unpack the tarball and invoke Emacs
+ 5:07 and make the cursor stop blinking
-they become this:
+ 5:11 Emacs as a Lisp environment
+11:48 Open the file \"VERSION\" (TAB completes)
+12:15 (eek \"C-x C-f VERSION\") is not very readable
+12:35 (find-file \".../VERSION\") is more readable
+12:43 to follow it we type M-e, and M-k to go back
+14:00 parts for humans and more or less for humans; passive sexps
+14:34 variations of M-e that split the screen
+15:09 left side is \"before\", right side is \"after\"
-# (find-fline \"/tmp/\")
-# (find-sh \"ls /tmp/\")
-# (find-man \"ls\")
+16:00 help on a key sequence
+16:28 C-h k gives us help on a key sequence
+17:46 (eek \"C-h k C-x C-f\") is an unreadble way to get help on a key
+17:55 (describe-function 'find-file) is even messier
+18:28 (find-efunctiondescr 'find-file) is cleaner - and why
-You can also try them by running the `eek' sexps below,
+20:14 introduction the eev documentation in \"intro\"s
+22:30 (eek \"M-h M-k C-x C-f\") generates a list of hyperlinks
+24:15 the first line regenerates the buffer
+24:40 the intros are temporary buffers
+25:07 we can play without destroying the documentation of eev
+25:40 we can copy the hyperlinks to intros to other places
-\(eek \"<down> M-F\")
-/tmp/
+25:53 introduction to eejump
+26:44 a plain M-j goes to the index of eejumps
+28:00 M-5 M-j goes to the top level of the documentation in intros
+28:22 M-2 M-j goes to (find-emacs-intro)
+28:36 ...which has lots of links to the emacs manuals
-\(eek \"<down> M-S\")
-ls /tmp/
+28:54 (find-eev-update-links)
+29:47 I could have done that with just instructions in English
+30:01 ...but it was more interesting to do that in an executable way.
+30:21 remember that the first line regenerates the buffer...
+31:07 we use that to select a directory for installation.
+31:40 an eepitch block
+31:53 emacs is made to handle anyting that looks like text...
+32:38 running terminals inside Emacs
+32:52 the best of both worlds
+33:50 f8
+35:48 [oops - I forgot to unpack]
-\(eek \"<down> M-M\")
-ls
-HINT: sometimes the eewrap commands don't do exactly what we
-want, so learn how to use the \"undo\" command of Emacs. See:
- (find-emacs-keys-intro \"5. Undoing\")
-The command `eewrap-anchor' (bound to `M-A') is similar to those
-above, but it parses the current line in a more complex way -
-everything between \"<>\" is the \"anchor\" and everything before
-the \"<\" is the \"comment prefix\" - and it converts the current
-line into two lines with `to's, each one pointing to the other
-one. For example, `M-A' in the line below
+8. In Portuguese
+================
- # <first-test>
+ (find-eev-video-links \"eevvideopt\" \"video2pt\" \"yztYD9Y7Iz4\")
+ (code-video \"eevvideopt\" \"$S/http/angg.twu.net/eev-videos/video2pt.mp4\")
+ (eev-avadj-mode 1)
+ (find-eevvideopt t)
-yields this:
+;; (find-eepitchvideo)
+;; (find-eevvideo)
+;; (find-eevvideopt)
- # �.first-test� (to \"first-test\")
- # �first-test� (to \".first-test\")
-The line with the anchor \"�.first-test�\" is intended to be
-moved - by hand, with cut and paste - to the index section at the
-beginning of the file, as explained here:
- (find-escripts-intro)
+9. Comparison with youtube
+==========================
+Note that Youtube has a trick that lets we use URLs that point to
+specific positions in videos. For example, this,
+ http://www.youtube.com/watch?v=Lj_zKC5BR64&t=0m16s
+makes the video about eepitch start at 0:16 instead of from the
+beginning. Also, each video at Youtube can have uploader comments
+and a discussion, and in the text of these comments things like
+\"12:34\" become links that make the current video skip to that
+position.
-8.4. Creating e-script blocks
------------------------------
-The key `M-B' (`eewrap-escript-block') is a variant of `M-A' that
-converts the current line into seven (!) lines instead of two. If
-we type `M-B' on the line below
+ (find-audiovideo-intro)
- second-test Long description
-it becomes this - the header of an \"e-script block\":
-#####
-#
-# Long description
-# 2018may22
-#
-#####
+10. Video2pt: Uma introducao ao eev2 (2012nov15)
+================================================
+This is a version in Portuguese of the video above.
+It is slightly longer than the version in English because it's
+intended mostly for non-Emacsers, so some things are explained
+\(much) more slowly...
-# �.second-test� (to \"second-test\")
-# �second-test� (to \".second-test\")
+At youtube: http://www.youtube.com/watch?v=yztYD9Y7Iz4
+ http://www.youtube.com/watch?v=yztYD9Y7Iz4&t=1h07m40s
+Hi-res mp4: http://angg.twu.net/eev-videos/video2pt.mp4
+ (128228339 bytes, 122MB. Duration: 1:09:42)
-where again the line with the anchor \"�.second-test�\" is
-intended to be moved to the index section at the beginning of the
-file. The use of these \"e-script blocks\" is explained bere:
+# (find-eevvideopt)
+# (find-eevvideopt \"1:07:40\" \"eepitch pro shell e pro Python\")
- (find-escripts-intro)
+Long story short
+================
+You may want to copy the block of elisp below to your .emacs. You can
+use this sexp to help you:
-8.5. Hyperlinks to anchors in other files
------------------------------------------
-`find-anchor' is like `find-fline', but it interprets the first
-argument after the file in a special way if it is present. These
-hyperlinks are all equivalent:
+ (ee-copy-rest 0 '(find-fline \"~/.emacs\"))
- (find-anchor \"~/eev2/eev-blinks.el\" \"find-wottb\")
- (find-anchor \"~/eev2/eev-blinks.el\" (ee-format-as-anchor \"find-wottb\"))
- (find-fline \"~/eev2/eev-blinks.el\" \"�find-wottb�\")
+;; Hyperlinks to videos about eev.
+;; See: (find-videos-intro)
+;; (find-eev-video-links \"eepitchvideo\" \"video4-eepitch\" \"Lj_zKC5BR64\")
+;; (find-eev-video-links \"eevvideo\" \"video2\" \"doeyn5MOaB8\")
+;; (find-eev-video-links \"eevvideopt\" \"video2pt\" \"yztYD9Y7Iz4\")
+\(code-video \"eepitchvideo\"
\"$S/http/angg.twu.net/eev-videos/video4-eepitch.mp4\")
+\(code-video \"eevvideo\" \"$S/http/angg.twu.net/eev-videos/video2.mp4\")
+\(code-video \"eevvideopt\" \"$S/http/angg.twu.net/eev-videos/video2pt.mp4\")
+;; (find-eepitchvideo)
+;; (find-eevvideo)
+;; (find-eevvideopt)
+;; (find-ebuffer \"*Messages*\")
+" pos-spec-list)))
-You can use this - or the shorter hyperlinks to anchors in
-section 9.3 - to point to anchors or to e-script blocks in your
-files.
+;; (find-videos-intro)
+;;; _ __
+;;; __| | ___ / _|_ _ _ __
+;;; / _` |/ _ \ |_| | | | '_ \
+;;; | (_| | __/ _| |_| | | | |
+;;; \__,_|\___|_| \__,_|_| |_|
+;;;
+;; �find-defun-intro� (to ".find-defun-intro")
+;; (find-intro-links "defun")
-9. Shorter hyperlinks
-=====================
-See also: (find-code-c-d-intro)
+(defun find-defun-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-defun-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-defun-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-defun-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.
-9.1. `code-c-d'
----------------
-Sexps like
- (find-eevfile \"\")
- (find-eevfile \"eev-blinks.el\")
- (find-eevfile \"eev-blinks.el\" \"�find-sh�\")
- (find-udfile \"\")
- (find-udfile \"lua5.1-doc/\")
- (find-udfile \"lua5.1-doc/test/\")
- (find-udfile \"lua5.1-doc/test/fib.lua\")
- (find-udfile \"lua5.1-doc/test/fib.lua\" \"function fib(n)\")
+\[At present this is just a _skeleton_ for a tutorial on defining
+functions in Lisp...]
-work as abbreviations for
- (find-fline \"~/eev-current/\")
- (find-fline \"~/eev-current/eev-blinks.el\")
- (find-fline \"~/eev-current/eev-blinks.el\" \"�find-sh�\")
- (find-fline \"/usr/share/doc/\")
- (find-fline \"/usr/share/doc/lua5.1-doc/\")
- (find-fline \"/usr/share/doc/lua5.1-doc/test/\")
- (find-fline \"/usr/share/doc/lua5.1-doc/test/fib.lua\")
- (find-fline \"/usr/share/doc/lua5.1-doc/test/fib.lua\" \"function fib(n)\")
-They are \"mass-produced\", in the following sense. When we run this,
+Simple examples
+===============
- (code-c-d \"ud\" \"/usr/share/doc/\")
+ (* 5 5)
+ (* 6 6)
+ (defun foo (a) (* a a))
+ (foo 5)
+ (foo 6)
-the function `code-c-d' produces a big string using a template, and
-evaluates that big string; the \"{c}\"s in the template are replaced by
-the argument \"ud\" - called the \"code\" - and the \"{d}\"s in the template
-are replaced by \"/usr/share/doc/\" - called the \"directory\". If we add
-a \"find-\" before the `code-c-d', like this,
+ (+ 5 5)
+ (defun foo (a) (+ a a))
+ (foo 5)
- (find-code-c-d \"ud\" \"/usr/share/doc/\")
+ (symbol-function 'foo)
+ ((lambda (a) (* a a)) 5)
+ ((lambda (a) (+ a a)) 5)
-we get a hyperlink to the code that `(code-c-d \"ud\" \"/usr/share/doc/\")'
-would execute - i.e., to the result of substiting the \"{c}\"s and
-\"{d}\"s in the template. This is useful for understanding how
-`code-c-d' works; each call to `code-c-d' defines lots of functions,
-some of them easier to explain, some harder. This, for example,
+See:
+ (find-elnode \"Function Cells\")
+ (find-elnode \"Defining Functions\")
- (find-eevgrep \"grep --color -nH -e '(code-c-d ' *.el\")
-greps for all calls to \"code-c-d\" in the source of eev.
-By default, eev runs these `code-c-d's:
+Several arguments
+=================
- (find-eevfile \"eev-code.el\" \"code-c-d \\\"e\\\"\")
+ (defun foo (a b) (+ (* a a) (* b b)))
+ (foo 10 2)
+ (foo 5)
+ (defun foo () (+ (* 2 3) (* 4 5)))
+ (foo 10 2)
+ (foo 5)
+ (foo)
-You can add many more of them to your .emacs file.
-An introduction to the ideas, details, innards and technicalities of
-`code-c-d' can be found here:
- (find-code-c-d-intro)
+progn and prog1
+===============
+The body of a \"defun\" works like a \"progn\".
+See: (find-elnode \"Index\" \"* progn:\")
+ (defun foo (a b) (* a b))
+ (defun foo (a b) (+ a b) (* a b))
+ (defun foo (a b) (* a b) (+ a b))
+ (defun foo (a b) (+ a b))
+ (foo 5 6)
+ (progn (* 5 6) (+ 5 6))
+ (progn \"ignored\" (+ 5 6) \"result\")
+ (progn)
-9.2. Extra arguments to `code-c-d'
-----------------------------------
-If you compare the buffers generated by
+ (prog1 (* 5 6) (+ 5 6))
+ (prog1 \"result\" (+ 5 6) \"ignored\")
+ (prog1)
- (find-code-c-d \"CODE\" \"/DIR/\")
- (find-code-c-d \"CODE\" \"/DIR/\" :info \"INFO\")
- (find-code-c-d-rest \"CODE\" \"/DIR/\" :info \"INFO\")
-you will see that the `:info \"INFO\"' part adds some code to the end of
-the generated string, and that the `find-code-c-d-rest' shows only
-this extra code.
-The most important extra arguments to `code-c-d' are:
+Docstrings
+==========
+Note that a string in a (progn ...) does nothing - unless it is
+the last BODY-FORM.
- 1) :info \"name-of-an-info-manual\"
- 2) :gz
- 3) :anchor
+But see: (find-elnode \"Documentation\")
-If the first extra argument is a string then `ee-code-c-d' adds an
-`:info' before it, so these generate the same code:
+Try:
- (find-code-c-d \"CODE\" \"/DIR/\" \"INFO\")
- (find-code-c-d \"CODE\" \"/DIR/\" :info \"INFO\")
+ (defun foo (a b) \"IGNORED\" (+ a b))
+ (defun foo (a b) \"This is the description of `foo'\" (+ a b))
+ (defun foo (a b) \"This is the docstring of `foo'\" (+ a b))
+ (defun foo (a b) \"This function returns (* A B). Note the italics!\" (+ a
b))
+ (find-efunctiondescr 'foo)
-The eev source has this (in the file \"eev-code.el\"),
- (code-c-d \"e\" ee-emacs-lisp-directory :info \"emacs\" :gz)
- (code-c-d \"eev\" ee-eev-source-directory :anchor)
-and that code
+&optional and &rest
+===================
+See: (find-elnode \"Argument List\")
+Try:
- 1) makes (find-enode \"\")
- work as an abbreviation for (find-node \"(emacs)\")
+ (defun foo (a &optional b c) (list \"a,b,c:\" a b c))
+ (foo 11 22 33)
+ (foo 11 22)
+ (foo 11)
+ (foo)
+ (foo 11 22 33 44)
- 2) makes (find-efile \"files.el\")
- run (find-efile \"files.el.gz\")
- if the file \"files.el\" is not found,
+ (defun foo (a &optional b c &rest r) (list \"a,b,c,r:\" a b c r))
+ (foo 11 22 33 44 55 66)
+ (foo 11 22 33 44 55)
+ (foo 11 22 33 44)
+ (foo 11 22 33)
+ (foo 11 22)
+ (foo 11)
+ (foo)
- 3) makes (find-eev \"eev-blinks.el\" \"find-wottb\")
- run: (find-eevfile \"eev-blinks.el\" \"�find-wottb�\")
- or actually: (find-anchor (ee-eevfile \"eev-blinks.el\") \"find-wottb\")
+ (defun foo (a &rest r) (list \"a,r:\" a r))
+ (foo 11 22 33 44)
+ (foo 11 22 33)
+ (foo 11 22)
+ (foo 11)
+ (foo)
-Calls to `find-eev' are \"short hyperlinks to anchors\":
- (find-eev \"eev-blinks.el\" \"find-wottb\")
- (find-eev \"eev-blinks.el\" \"find-wottb\" \"defun find-wottb-call\")
-For the technical details of the implementation, see here:
+A tool: my-insert
+=================
+See: (find-elnode \"Formatting Strings\")
+Try:
- (find-code-c-d-intro \"Extra arguments to `code-c-d'\")
+ (format \"<%s>\" \"hello\")
+ (format \"<%s>\" \"123\")
+ (format \"<%s>\" 123)
+ (format \"<%s>\" 'hello)
+ (format \"<%s>\" '(+ 2 3))
+ (format \"<%S>\" \"hello\")
+ (format \"<%S>\" \"123\")
+ (format \"<%S>\" 123)
+ (format \"<%S>\" 'hello)
+ (format \"<%S>\" '(+ 2 3))
+Now define:
-9.3. Hyperlinks to PDF files
-----------------------------
-If you run this e-script
+ (defun my-insert (obj)
+ \"Print (insert) OBJ in the current buffer.\"
+ (insert (format \"\\n ;; \\\\--> %S\" obj)))
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-# https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
-mkdir -p $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/
-cd $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/
-wget -nc https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
+Try:
-you will download a local copy of J.M. Coetzee's \"The Lives of
-Animals\" into this directory:
+ (my-insert 123)
+ (my-insert \"123\")
+ (my-insert \"hello\")
+ (my-insert 'hello)
+ (my-insert '(+ 2 3))
+ (my-insert nil)
+ (my-insert '())
+ (my-insert ())
- (find-fline \"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/\")
- (find-fline \"~/snarf/https/tannerlectures.utah.edu/_documents/a-to-z/c/\")
+See also:
+ (find-elnode \"Character Type\")
+ (find-elnode \"Basic Char Syntax\")
+ (find-elnode \"Basic Char Syntax\" \"?\\\\n\")
+ (find-elnode \"General Escape Syntax\")
-The full idea behind these \"local copies\" is explained here:
- (find-psne-intro)
-If you have xpdf installed then the second sexp here,
+interactive
+===========
+Not all Emacs functions are callable with `M-x' - only those that
+are \"commands\" are callable in this way. And only \"commands\"
+can be bound to keys...
- (setq l-o-a
\"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf\")
- (find-pdf-page l-o-a)
+See:
+ (find-elnode \"Defining Functions\" \"the first two of the BODY-FORMS\")
+ (find-elnode \"Defining Commands\")
+ (find-elnode \"Command Overview\")
-should work as a \"hyperlink to the PDF\": it calls xpdf as
-external program to open that PDF file. The main keys of xpdf
-are:
+When you execute an `(interactive ...)' it does nothing - it
+simply ignores its arguments (which aren't even evaluated!) and
+returns nil. But just as
- q quit xpdf
- alt-f toggle full-screen; use twice to fit document to page
- PageDown scroll down/go to next page
- PageUp scroll up/go to previous page
- 0 set zoom to 125%
- + zoom in one step
- - zoom out out step
- arrows scroll within the current page
-Also, if you have the program pdftotext installed (hint: apt-get
-install poppler-utils!) then this
+ (defun my-insert (obj) (insert (format \"\\n ;; \\\\--> %S\" obj)))
- (find-pdf-text l-o-a)
+ (find-efunctiondescr 'interactive)
-should work as a \"hyperlink to the text of the PDF\".
+ (eek \"M-x foo\")
+ (commandp 'foo)
-You can use these two sexps
+ (defun foo (&rest rest) (interactive) (bar rest))
+ (eek \"M-x foo\")
- (ee-find-pdf-text l-o-a)
- (ee-find-pdf-page l-o-a)
+ (defun foo (&rest rest) (bar rest))
+ (defun foo (&rest rest) (interactive \"P\") (bar rest))
+ (eek \" M-x foo\")
+ (eek \"M-1 M-x foo\")
+ (eek \"M-1 M-2 M-3 M-x foo\")
+ (eek \"M-- M-2 M-3 M-x foo\")
-to see exactly how the `find-pdf-page' and the `find-pdf-text'
-sexps above invoke xpdf and pdftotext; note that `find-pdf-page'
-uses `find-bgprocess' and `find-pdf-text' uses `find-sh'.
+ (defun foo (&rest rest) (interactive \"R\") (bar rest))
+ (eek \"M-x foo\")
-The functions above accept extra arguments, that are interpreted
-as a page number and as strings to look for, but it's easier to
-discuss them using shorter hyperlinks.
+" rest)))
+;; (find-defun-intro)
+;; (find-defun-intro "&rest")
+;; (find-defun-intro "\ninteractive\n")
+;; (find-defun-intro "Defining Commands")
-9.4. Shorter hyperlinks to PDF files
-------------------------------------
-If you run these sexps
- (code-pdf-page \"livesofanimals\" l-o-a)
- (code-pdf-text \"livesofanimals\" l-o-a -110)
-then these hyperlinks should work:
+;;; _ _
+;;; ___ _ __ ___ __ _ ___ ___ (_)_ __ | |_ _ __ ___
+;;; / _ \ '_ ` _ \ / _` |/ __/ __|_____| | '_ \| __| '__/ _ \
+;;; | __/ | | | | | (_| | (__\__ \_____| | | | | |_| | | (_) |
+;;; \___|_| |_| |_|\__,_|\___|___/ |_|_| |_|\__|_| \___/
+;;;
+;; �find-emacs-intro� (to ".find-emacs-intro")
+;; (find-intro-links "emacs")
- (find-livesofanimalspage (+ -110 127) \"wrong thoughts\")
- (find-livesofanimalstext (+ -110 127) \"wrong thoughts\")
- (find-livesofanimalspage (+ -110 132) \"into the place of their victims\")
- (find-livesofanimalstext (+ -110 132) \"into the place of their victims\")
- (find-livesofanimalspage (+ -110 134) \"woke up haggard in the mornings\")
- (find-livesofanimalstext (+ -110 134) \"woke up haggard in the mornings\")
- (find-livesofanimalspage (+ -110 143) \"Babies have no self-consciousness\")
- (find-livesofanimalstext (+ -110 143) \"Babies have no self-consciousness\")
- (find-livesofanimalspage (+ -110 145) \"squirrel doing its thinking\")
- (find-livesofanimalstext (+ -110 145) \"squirrel doing its thinking\")
- (find-livesofanimalspage (+ -110 147) \"Rilke's panther\")
- (find-livesofanimalstext (+ -110 147) \"Rilke's panther\")
- (find-livesofanimalspage (+ -110 162) \"a grasp of the meaning\")
- (find-livesofanimalstext (+ -110 162) \"a grasp of the meaning\")
- (find-livesofanimalspage (+ -110 164) \"last common ground\")
- (find-livesofanimalstext (+ -110 164) \"last common ground\")
+(defun find-emacs-intro (&rest rest) (interactive)
+ (let ((ee-buffer-name "*(find-emacs-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-emacs-intro)
+Source code: (find-eev \"eev-intro.el\" \"find-emacs-intro\")
+More intros: (find-eev-quick-intro)
+ (find-emacs-keys-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
+
+
+
+THIS INTRO IS OBSOLETE, and has been superseded by:
+ (find-emacs-keys-intro)
-[To do: explain them]
+Basic keys (eev)
+================
+The most basic keys of eev are:
+ M-e - to follow a hyperlink, see: (find-eval-intro \"Elisp hyperlinks\")
+ M-k - to go back, see: (find-eval-intro \"\\nGoing back\")
+ M-j - to jump to certain predefined places - in particular,
+ `M-j' takes you to the list of jump targets.
+ `M-2j' takes you to this help page.
+ `M-5j' takes you to: (find-eev-intro)
+ See: (find-eejump-intro \"Families\")
+ M-h M-h - hyperlinks to here, plus help.
+ See: (find-eev-quick-intro \"7.1. eejump\")
+ (find-links-intro \"`find-here-links'\")
-\(To be continued...)
-") pos-spec-list)))
+The mnemonics are:
+ M-e - evaluate/execute
+ M-j - jump
+ M-k - kill buffer
-;; end of defun
+It is possible to start learning Emacs and eev by remembering
+only that `M-j' jumps to an index; when you're lost, type `M-j',
+and will see a reminder of the main keys and of the main jump
+targets - after that you can learn how to use `M-k' to kill the
+top buffer, and `M-e' to follow elisp hyperlinks. The other keys
+are explained in \"intros\" like this one.
-;; (find-eev-quick-intro)
+Files, Buffers, Windows, Frames, Display, etc
+=============================================
+Emacs can edit several files at the same time, each one
+in a \"buffer\".
-;;; _ _ _ _
-;;; (_)_ __ ___| |_ __ _| | |
-;;; | | '_ \/ __| __/ _` | | |
-;;; | | | | \__ \ || (_| | | |
-;;; |_|_| |_|___/\__\__,_|_|_|
-;;;
+ (find-enode \"Files\")
+ (find-enode \"Buffers\")
+ (find-enode \"Windows\")
+ (find-enode \"Frames\")
-;; �find-eev-install-intro� (to ".find-eev-install-intro")
-;; (find-intro-links "eev-install")
+The display of Emacs looks like this (asciified):
+ __ _ _
+ ______________emacs_______\\/|-|X|
+ / | | \\
+ | | bla. | | Emacs
+Window | | | | calls this
+managers | | | | a \"window\".
+call | | | /
+this a | |--:** foo.txt (Fundamental) ----| <-- Its \"modeline\".
+\"window\". / | | \\
+Emacs \\ | bla bla. | | Another
+calls | | bleh | | window.
+this a | | | |
+\"frame\". | | | /
+ | |--:** bar.txt (Fundamental) ----| <-- Its modeline.
+ \\ |Find file: ~/bletch.txt_ ________| <-- The minibuffer.
-(defun find-eev-install-intro (&rest pos-spec-list) (interactive)
- (let ((ee-buffer-name "*(find-eev-install-intro)*"))
- (apply 'find-estring "\
-\(Re)generate: (find-eev-install-intro)
-Source code: (find-efunction 'find-eev-install-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.
+The bottom line of a frame is sometimes the \"echo area\",
+sometimes the \"minibuffer\". The minibuffer acts like a
+window when it is active, and `C-x o' can be used to move
+from it to the \"normal windows\" and back. You can also
+use the mouse to move between windows.
+ (find-enode \"Echo Area\")
+ (find-enode \"Minibuffer\")
+ (find-enode \"Other Window\")
+By default there's also a \"menu bar\" (with textual entries) and
+a \"tool bar\" (with icons) at the top of each frame, but
+advanced users usually disable them.
-The \"quick introduction to eev\" in
+ (find-enode \"Menu Bar\")
+ (find-enode \"Tool Bars\")
- (find-eev-quick-intro)
-describes a way to install eev for tests that does not make any
-permanent changes in your HD - everything gets installed in the
-/tmp/ directory, that is cleared at every boot. Here we describe
-several ways to install eev in other, more permanent, places.
+Basic keys (Emacs)
+==================
+\(find-enode \"Keys\" \"key sequence\")
+\(find-enode \"User Input\" \"`Control-a'\" \"usually written `C-a'\")
+\(find-enode \"User Input\" \"<META> key\")
+\(find-enode \"Completion\" \"<TAB>\")
-1. Running `(find-eev-install-links)'
-=====================================
-The shell commands in
+<ESC> <ESC> <ESC> (find-enode \"Quitting\")
+C-g keyboard-quit (find-enode \"Quitting\" \"`C-g'\")
- (find-eev-quick-intro \"1. Installing eev\")
+M-x execute-extended-command (find-enode \"M-x\" \"Running Commands by
Name\")
-can be obtained by running
- (find-eev-install-links)
-with these arguments:
+Cutting & pasting
+=================
+The \"region\" where cut & copy operate is always what is between
+the \"point\" and the \"mark\":
- (find-eev-install-links \"/tmp/eev2/\" \"/tmp/eev\")
+ (find-enode \"Point\")
+ (find-enode \"Mark\")
-Note that `(find-eev-install-links)' is somehow similar to this,
+You can do cut, copy and paste by using the icons in the toolbar
+or by using the menu bar (the relevant options are under
+\"Edit\"), but the keys are worth learning:
- (find-eev-quick-intro \"7.3. `find-latex-links'\")
+ C-SPC -- set-mark-command (find-enode \"Setting Mark\")
+ C-x C-x -- exchange-point-and-mark (find-enode \"Setting Mark\" \"C-x
C-x\")
+ C-w -- kill-region (cut) (find-enode \"Other Kill Commands\")
+ M-w -- kill-ring-save (copy) (find-enode \"Kill Ring\")
+ C-y -- yank (paste) (find-enode \"Kill Ring\")
-and follows most of the same conventions.
-If you want to install eev in a more permanent place the default
-way is to run `(find-eev-install-links)' with these arguments,
- (find-eev-install-links \"~/eev2/\" \"~/eev\" \"#\")
+Undoing
+=======
+C-/ -- undo (find-enode \"Basic Undo\")
+C-_ -- undo (find-enode \"Basic Undo\")
+ (find-enode \"Undo\")
-and execute its eepitch block.
+Windows
+=======
+See: (find-enode \"Frames\")
+ (find-enode \"Windows\")
+C-x o -- other-window (find-enode \"Other Window\")
+C-x 0 -- delete-window (find-enode \"Change Window\")
+C-x 1 -- delete-other-windows (\"1 window\") (find-enode \"Change Window\")
+C-x 2 -- split-window-vertically (Abv/Blw) (find-enode \"Split Window\")
+C-x 3 -- split-window-horizontally (L|R) (find-enode \"Split Window\")
-2. Changing your .emacs
-=======================
-To be written. See:
+Other keys / reference
+======================
+M-x -- execute-extended-command (find-enode \"M-x\")
+ more about the minibuffer: (find-enode \"Minibuffer\")
+TAB -- for completion: (find-enode \"Completion\")
+ for indentation: (find-enode \"Indentation\")
+ in programming modes: (find-enode \"Basic Indent\")
- (find-eev-install-links \"~/eev2/\" \"~/eev\" \"#\")
- (find-eev-install-links \"~/eev2/\" \"~/eev\" \"#\" 2 \".emacs\")
- (find-elnode \"Init File\")
- (find-elnode \"Init Examples\")
+ (find-enode \"Dired\")
+C-x C-f -- find-file (find-enode \"Visiting\")
+C-x C-s -- save-buffer (find-enode \"Saving\")
+C-x C-c -- save-buffers-kill-emacs (find-enode \"Saving\")
+C-x b -- switch-to-buffer (find-enode \"Select Buffer\")
+C-x k -- kill-buffer (find-enode \"Kill Buffer\")
+C-a -- beginning-of-line (find-enode \"Moving Point\")
+C-e -- end-of-line (find-enode \"Moving Point\")
+M-< -- beginning-of-buffer (find-enode \"Moving Point\")
+M-> -- end-of-buffer (find-enode \"Moving Point\")
+M-q -- fill-paragraph (find-enode \"Fill Commands\")
+C-s -- isearch-forward (find-enode \"Incremental Search\")
+C-r -- isearch-backward (find-enode \"Incremental Search\")
+M-C-s -- isearch-forward-regexp (find-enode \"Regexp Search\")
+M-C-r -- isearch-backward-regexp (find-enode \"Regexp Search\")
+M-% -- query-replace (find-enode \"Replace\")
-3. Using the git repository
-===========================
-Eev has a git repository at:
+C-x ( -- start-kbd-macro (find-enode \"Keyboard Macros\")
+C-x ) -- end-kbd-macro (find-enode \"Keyboard Macros\")
+C-x e -- call-last-kbd-macro (find-enode \"Keyboard Macros\")
+" rest)))
- https://github.com/edrx/eev.git
+;; (find-emacs-intro)
+;; (find-TH "emacs" "short-emacs-tutorial")
-All recent changes are being made at the \"UTF-8\" branch and I
-haven't learned yet how to make the master branch point to
-UTF-8... so if you clone the repository you'll have to do a
-\"checkout UTF-8\" the go to the most recent version.
-Try this:
- (eepitch-shell)
- (eepitch-kill)
- (eepitch-shell)
-rm -Rfv /tmp/eev2
-mkdir /tmp/eev2/
-cd /tmp/eev2/ && git clone https://github.com/edrx/eev.git .
-cd /tmp/eev2/
-git checkout UTF-8
-# (find-gitk \"/tmp/eev2/\")
-{
- echo '#!/bin/sh'
- echo 'cd /tmp/eev2/ && emacs -l eev-readme.el
--eval=\"(find-eev-quick-intro)\"'
-} > /tmp/eev
-chmod 755 /tmp/eev
-and run the script in /tmp/eev if you want to.
-Note the \"cd ... && git clone URL .\". This is needed because if
-we don't specify a directory after the URL in \"git clone\" then
-git will create a directory /tmp/eev/, and that would be
-incompatible with our convention of creating a script called
-\"eev\" (\"/tmp/eev\" in this case).
+;; �find-org-intro� (to ".find-org-intro")
+;; (find-intro-links "org")
+(defun find-org-intro (&rest pos-spec-list) (interactive)
+ (let ((ee-buffer-name "*(find-org-intro)*"))
+ (apply 'find-estring "\
+\(Re)generate: (find-org-intro)
+Source code: (find-efunction 'find-org-intro)
+More intros: (find-eev-quick-intro)
+ (find-eev-intro)
+ (find-eval-intro)
+ (find-eepitch-intro)
+This buffer is _temporary_ and _editable_.
+Is is meant as both a tutorial and a sandbox.
-4. Eev as an ELPA package
-=========================
-I started to make an Emacs \"package\" for eev but I did not go
-very far. See:
- (find-enode \"Packages\")
- (find-elnode \"Packaging\")
- (find-efaqnode \"Packages that do not come with Emacs\")
+Google Tech talk by Carsten Dominik (2008)
+==========================================
+http://orgmode.org/talks.html
+http://orgmode.org/worg/org-tutorials/org-screencasts/org-mode-google-tech-talk.html
+http://www.youtube.com/watch?v=oJTwQvgfgMM Emacs Org-mode - a system for
note-taking and project planning
+\(find-youtubedl-links \"/sda5/videos/\"
\"Emacs_Org-mode_-_a_system_for_note-taking_and_project_planning\"
\"oJTwQvgfgMM\" \".flv\" \"carsten2008\")
+ (ee-youtubedl-hash-to-fname \"oJTwQvgfgMM\")
+\(setq ee-carsten2008 (ee-youtubedl-hash-to-fname \"oJTwQvgfgMM\"))
+\(code-mplayer \"carsten2008\" ee-carsten2008)
+\(find-carsten2008 \"0:00\")
-Help would be greatly appreciated!
+\(eev-avadj-mode 1)
+\(find-carsten2008 t)
+1:20 Carsten Start
+1:50 History
+2:15 Working with Text Files
+3:58 Notes (not tasks) based project planning
+5:50 Outline mode - fixing
+9:56 Structure Editing
+11:00 Note taking other supports
+13:35 Meta data Intro
+14:57 tags
+15:26 Timeplanning
+15:53 Properties
+16:02 Meta data propagation
+16:49 Special Meta entry interfaces
+17:55 DateTime interface
+18:24 Column view
+19:20 Capture with remember
+23:02 Collect and Display
+23:52 Sparse tree
+25:47 Agenda view
+27:27 Exporting and publishing
+29:05 Tables
+31:34 Calc
+32:44 Radio tables
+34:53 Context sensitive keys
+38:13 How is org used
+40:55 Evolved Software software
" pos-spec-list)))
-;; (find-eev-install-intro)
+;; (find-org-intro)
-;; (find-eev "eev-tlinks.el" "find-eev-update-links")
-;; (find-eev "eev-tlinks.el" "find-eev-install-links")
-;; (find-eev-update-links)
diff --git a/eev-tlinks.el b/eev-tlinks.el
index 7ff85ad..cd8475b 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -535,17 +535,18 @@ sudo dpkg -i *.deb
;; A test: (find-eev-install-links)
(defun find-eev-install-links (&optional dir script comment &rest
pos-spec-list)
-"Visit a temporary buffer containing hyperlinks for foo."
+"Visit a temporary buffer containing an e-script for installing eev."
(interactive)
- (setq dir (or dir "{dir}"))
- (setq script (or script "{script}"))
- (setq comment (or comment "{comment}"))
+ (setq dir (or dir "~/eev2/"))
+ (setq script (or script "~/eev"))
+ (setq comment (or comment ""))
(apply 'find-elinks
`((find-eev-install-links ,dir ,script ,comment ,@pos-spec-list)
- (find-eev-install-links "/tmp/eev2/" "/tmp/eev" "#")
- (find-eev-install-links "/tmp/eev2/" "/tmp/eev")
- (find-eev-install-links "~/eev2/" "~/eev" "#")
(find-eev-install-links "~/eev2/" "~/eev")
+ (find-eev-install-links "~/eev2/" "~/eev" "#")
+ (find-eev-install-links "/tmp/eev2/" "/tmp/eev")
+ (find-eev-install-links "/tmp/eev2/" "/tmp/eev" "#")
+ (find-eev-install-links "{dir}" "{script}" "{comment}")
(find-eev-install-links)
;; Convention: the first sexp always regenerates the buffer.
(find-efunction 'find-eev-install-links)
@@ -556,11 +557,11 @@ sudo dpkg -i *.deb
# This function is explained at:
# (find-eev-install-intro \"1. Running `(find-eev-install-links)'\")
#
-# The default way to use it to install eev in /tmp/ for tests is with:
-# (find-eev-install-links \"/tmp/eev2/\" \"/tmp/eev\" \"#\")
-#
# The default way to use it to install eev in your home directory is with:
# (find-eev-install-links \"~/eev2/\" \"~/eev\" \"#\")
+#
+# The default way to use it to install eev in /tmp/ for tests is with:
+# (find-eev-install-links \"/tmp/eev2/\" \"/tmp/eev\" \"#\")
- [elpa] externals/eev 39a2cea 60/64: New file: eev-template0.el., (continued)
- [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, 2019/04/07
- [elpa] externals/eev a5f9343 30/64: Small changes in `find-eev-install-links' and in eev-intro.el.,
Stefan Monnier <=
- [elpa] externals/eev af88c9b 01/64: Initial commit for eev2, Stefan Monnier, 2019/04/07