(Re)generate: (find-eev-quick-intro)
Source code:  (find-efunction 'find-eev-quick-intro)
More intros:  (find-emacs-keys-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.
The quickest way to open or recreate this is with `M-5 M-j'.

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/video4-eepitch.mp4     (eev's main ideas)

1. Installing eev

Open the page at http://angg.twu.net/eev-intros/find-eev-quick-intro.html 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 rm -Rv ~/eev2/ mkdir ~/eev2/ cd ~/eev2/ rm -fv eev2.tgz wget http://angg.twu.net/eev-current/eev2.tgz tar -xvzf eev2.tgz { echo '#!/bin/sh' echo 'cd ~/eev2/ && emacs -l eev-beginner.el --eval="(find-eev-quick-intro)" $*' } > ~/eev chmod 755 ~/eev } You now have a shell script that you can invoke with ~/eev that starts Emacs, loads eev, and opens a copy of 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. 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. For more on ways to install eev see: (find-eev-install-intro)

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... (+ (* 2 3) (* 4 5)) ^ ^^ | | \ 6 20 26 ...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. 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: (+ (* 2 3) (* 4 5) ) `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.

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 "date") (find-sh "date; sleep 1; date") 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, (eek "<down> C-a H E L L O ! <up> C-e") and some display their output in the echo area: (find-sh0 "date") 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': http://www.lua.org/start.html This will make emacs invoke the default browser on that URL. See: (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, 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)

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. 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) | |# (eek "M-h M-f find-file") | |# (find-eev-quick-intro "4.2. `find-ekey-links' and friends") | | | |# (find-efunctiondescr 'find-file) | |# (find-efunction 'find-file) | |# (find-efunctionpp 'find-file) | |# (find-efunctiond 'find-file) | | | |# (Info-goto-emacs-command-node 'find-file) | |# (find-enode "Command Index" "* find-file:") | |# (find-elnode "Index" "* find-file:") | | | |# (where-is 'find-file) | |# (symbol-file 'find-file 'defun) | |# (find-fline (symbol-file 'find-file 'defun)) | |# (find-estring (documentation 'find-file)) | |# (find-estring (documentation 'find-file t)) | |# (describe-function 'find-file) | | | | | | -:**- *Elisp hyperlinks* All L1 (Fundamental eev) ----------| |____________________________________________________________________|

4.1. `find-here-links'

One standard way of using eev is: a) we keep our current notes in a a file - for example, "~/TODO" 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-eev-quick-intro "4.1. `find-here-links'") | |# (find-emacs-keys-intro "1. Basic keys (eev)" "M-h M-h") | |# (find-here-links-intro "4. `find-here-links-3'") | | | |# http://angg.twu.net/eev-intros/find-eev-quick-intro.html | |# (find-eev-quick-intro) | | | | | | -:**- *Elisp hyperlinks* All L1 (Fundamental eev) --------| |___________________________________________________________________| The elisp hyperlink # (find-eev-quick-intro) at the end opens this tutorial. The best way to learn how to create very quickly these "hyperlinks to things we saw or visited" and to copy them to our notes is explained in a separate tutorial: (find-here-links-intro) Cutting and pasting is explained briefly in section 5.2, below. A way to go quickly to "~/TODO" is explained in section 7.1. A way to "refine" hyperlinks to make them more precise is explained here: (find-refining-intro "2. Refining hyperlinks")

4.2. `find-ekey-links' and friends

Emacs is huge and you will probably want to save in your notes many links about keys and functions that look interesting - using `M-2 M-j' from time to time to visit (find-emacs-keys-intro) and learning the keys listed there will not be enough. Try the eek links below: (eek "M-h M-k C-x 4 0") (eek "M-h M-k C-x 4 0 ;; kill-buffer-and-window") (eek "M-h M-k C-s") (eek "M-h M-k C-s ;; isearch-forward") (eek "M-h M-f isearch-forward") (eek "M-h M-k M-h M-k ;; find-ekey-links") (eek "M-h M-k M-h M-f ;; find-efunction-links") You will notice that: 1. they create temporary buffers with lots of elisp hyperlinks, 2. you can "go back" from these buffers with `M-k', 3. the function name after the ";;" is a comment and is ignored by Emacs (but is useful for humans), 4. you can copy these hyperlinks to your "~/TODO", 5. the "M-h M-k" and "M-h M-f" in the beginning are reminders that we can use `M-h M-k <key-sequence>' and `M-h M-f <function-name>' to create help buffers about other keys and functions, 6. some of the hyperlinks use low-level representations for key sequences - you don't need to understand them. An example: (find-ekey-links "\^X40") 7. for _some_ keys and functions, but not all, the hyperlinks like (Info-goto-emacs-key-command-node "\C-s") (Info-goto-emacs-command-node 'isearch-forward) (find-enode "Command Index" "* isearch-forward:") (find-elnode "Index" "* defun:") that appear near the middle of the elisp hyperlinks buffers, point to relevant points in the Emacs manuals - see the next section.

5. Links to Emacs documentation

Try these links (some of them need the Emacs manuals installed): (find-emacs-keys-intro "Cutting & pasting") (find-node "(emacs)Screen") (find-efunctiondescr 'find-file) (find-efunction-links 'find-file) 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") and I use elisp hyperlinks to create quick reminders for the keys that I only need to remember when I am performing specific tasks. Moral: when you want a quick reference of the main Emacs and eev keys, type `M-2 M-j'.

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 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: 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) Try the keys above now - they are VERY important! Use: (eek "<down> M-3 M-e ;; open the hyperlink below in another window") (find-node "(emacs)Basic") (find-node "(emacs)Major Modes")

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: 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") The "region" where cut & paste operate is always what is between the "point" and the "mark". See: (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

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'. The sections below were adapted from: (find-eepitch-intro "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: ___________________ | | | | our | a | | notes | shell | | | buffer | |_________|_________| 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. 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)"

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: * (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: * (eepitch-shell) * (eepitch-kill) * (eepitch-shell) echo Hello... > /tmp/o * (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())

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

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'.

7. Quick access to one-liners

7.1. `eejump'

Some key sequences in Emacs accept numeric arguments. For example, try typing `M-9 a' (not `M-9 M-a'!) - this will insert 9 copies of the letter `a'. See: (find-enode "Arguments") Eev binds the key `M-j' (`eejump') to a function that jumps to a place that depends on the numeric argument. For example, `M-5 M-j' runs (find-eev-quick-intro), that reloads this intro and goes to the top of it, and `M-2 M-j' runs: (find-emacs-keys-intro) `M-6 M-j' runs: (find-escripts-intro) `M-1 M-j' runs: (find-fline "~/TODO") The way to associate a number to a place to jump to - or, more precisely, to a single-line piece of Elisp code, i.e., a "one-liner" - is through code like this: (defun eejump-5 () (find-eev-quick-intro)) (defun eejump-2 () (find-emacs-keys-intro)) (defun eejump-6 () (find-escripts-intro)) (defun eejump-1 () (find-fline "~/TODO")) The pattern is: (defun eejump-<nnn> () <one-liner associated to the argument nnn>) `defun' is explained here: (find-elnode "Defining Functions" "(defun foo () 5)") (find-eval-intro "10. More on functions") As a special case, a plain `M-j' without a prefix argument runs a special function, `find-eejumps', that shows a help text followed by all the `(defun eejump-<nnn> () ...)'s that are currently active. So: `M-j' runs: (find-eejumps) Let's try to understand this from both a user's point of view and from a technical point of view. We may have elisp one-liners that we want to be able to execute very quickly, and from anywhere. For example, I keep all my notes that I have not organized yet in a file called "~/TODO", and if I type M-1 M-j 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. 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'. 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: (defun eejump-1 () (find-fline "~/TODO")) So `M-1 M-j' runs the one-liner `(find-fline "~/TODO")'. Similarly, `M-5 M-j' runs the one-liner `(find-eev-quick-intro)', and so on.

7.2. The list of eejump targets

If you type `M-j' without a prefix argument then it runs `(find-eejumps)', that displays a help text followed by all the current eejump targets as defuns, one in each line. Try it: (eek "M-j") (find-eejumps) You will see that two of those entries are: (defun eejump-1 () (find-fline "~/TODO")) (defun eejump-5 () (find-eev-quick-intro))

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: (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.") 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")

7.4. 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) [c]ompile "foo.tex" into a "foo.pdf", d) [d]isplay the resulting "foo.pdf", e) jump to "foo.tex" from anywhere to [e]dit it. If our "/tmp/foo.tex" starts with these lines % (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: (find-node "(emacs)M-x") (find-node "(emacs)Commands") (find-node "(elisp)Defining Commands")

7.5. `find-latex-links'

The easiest way to put the three defuns of the last section in the header of a LaTeX file is with: (find-latex-links "/tmp/foo") `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. 1) Run `M-x find-latex-links'. You will get a buffer whose top line is: # (find-latex-links "{stem}") 2) Edit that, and change the "{stem}" to "/tmp/foo". 3) Execute that top line, which is now: # (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) | |_____________________________________________________________________| 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)________________| 5) Go to the window on the right and type `C-y'. You should get this, ______________________________________________________________________ |# (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 | |_____________________________________________________________________| 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'. A detailed explanation of `ee-copy-rest' can be found here: (find-eev "eev-tlinks.el" "ee-copy-rest")

8. Anchors

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: (ee-format-as-anchor "foo") (ee-goto-position (ee-format-as-anchor "foo")) 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_. In a case like this, «.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")

8.2. Creating anchors by hand

One way to type the chars `«' and `»' is with `C-x 8 <' and `C-x 8 >'. Try: (eek "RET C-x 8 < t a g C-x 8 >")

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 /tmp/ ls /tmp/ ls 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/ (eek "<down> M-S") ls /tmp/ (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 # <first-test> 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)

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 nine (!) lines instead of two. If we type `M-B' on the line below second-test Long description it becomes this - the header of an "e-script block": ##### # # 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)

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: (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»") 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.

9. Shorter hyperlinks

See also: (find-code-c-d-intro)

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)") work as abbreviations for (find-fline "~/eev2/") (find-fline "~/eev2/eev-blinks.el") (find-fline "~/eev2/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, (code-c-d "ud" "/usr/share/doc/") 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, (find-code-c-d "ud" "/usr/share/doc/") 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, (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: (find-eevfile "eev-code.el" "code-c-d \"e\"") 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)

9.2. Extra arguments to `code-c-d'

If you compare the buffers generated by (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: 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") 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 1) makes (find-enode "") work as an abbreviation for (find-node "(emacs)") 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") For the technical details of the implementation, see here: (find-code-c-d-intro "Extra arguments to `code-c-d'")

9.3. Hyperlinks to PDF files

If you run this e-script * (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 you will download a local copy of J.M. Coetzee's "The Lives of Animals" into this directory: (find-fline "$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/") (find-fline "~/snarf/https/tannerlectures.utah.edu/_documents/a-to-z/c/") The full idea behind these "local copies" is explained here: (find-psne-intro) If you have xpdf installed then the second sexp here, (setq l-o-a "$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf") (find-pdf-page l-o-a) 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: 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". You can use these two sexps (ee-find-pdf-text l-o-a) (ee-find-pdf-page l-o-a) 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'. 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.

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-livesofanimalspage) (find-livesofanimalstext) (find-livesofanimalspage (+ -110 113)) (find-livesofanimalstext (+ -110 113)) (find-livesofanimalspage (+ -110 113) "LECTURE I.") (find-livesofanimalstext (+ -110 113) "LECTURE I.") (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") The sexps like `(+ -110 113)' are a bit mysterious at first sight. We are accessing a PDF that is an excerpt of a book. The third page of the PDF has a "[113]" at its footer to indicate that it is the page 113 of the book. Let's use the terms _page number_ and _page label_ to distinguish the two numberings: in this case, the page whose page number is 3 is the page whose page label is 113. These two sexps (find-livesofanimalspage (+ -110 113)) (find-livesofanimalspage 3) are equivalent, but the first one is more human-friendly: the 113 is a page label, and the -110 is adjustment (we call it the "offset") to convert the 113 that humans prefer to see intto the 3 that xpdf needs to receive. Note that the sexp (find-livesofanimalstext 3) converts the PDF of the "Lives of Animals" book to text and goes to "page 3" on it by counting formfeeds from the beginning of the buffer, as explained here: (find-enode "Pages" "formfeed") In this pair of sexps, (find-livesofanimalspage (+ -110 113) "LECTURE I.") (find-livesofanimalstext (+ -110 113) "LECTURE I.") the first one goes to page 3 of the PDF and ignores the string "LECTURE I." (that is there just for humans, as a reminder of what is important in that page); the second sexp goes to the page 3 of the PDF converted to text, searches for the string "LECTURE I." and places the cursor right after the end of it. In section 10.4 we will see how to generate with just a few keystrokes a short hyperlink to a page of a PDF and a short hyperlink to a string in a page of a PDF.

10. Generating short hyperlinks

10.1. Generating short hyperlinks to files

If you run this (code-c-d "foo" "/tmp/FOO") (code-c-d "bar" "/tmp/FOO/BAR/") (code-c-d "plic" "/tmp/FOO/BAR/PLIC/") then these five links will all point to the same file: (find-file "/tmp/FOO/BAR/PLIC/bletch") (find-fline "/tmp/FOO/BAR/PLIC/bletch") (find-foofile "/BAR/PLIC/bletch") (find-barfile "PLIC/bletch") (find-plicfile "bletch") Note that the last three are short hyperlinks. If you open that file and then type `M-h M-h' this will run `find-here-links', that will run: (find-file-links "/tmp/FOO/BAR/PLIC/bletch") and this will create an elisp hyperlinks buffer in which the last sexps will be the three different short hyperlinks to "/tmp/FOO/BAR/PLIC/bletch" above. This works for all files. If you visit a file and type `M-h M-h' then the last hyperlinks in the temporary buffer will be the short hyperlinks to that file.

10.2. Generating short hyperlinks to info nodes

If you run this (code-c-d "el" ee-emacs-lisp-directory "elisp") then these three hyperlinks will point to the same info node: (info "(elisp)Top") (find-node "(elisp)Top") (find-elnode "Top") Note that the last one is a short hyperlink. If you open that info node and type `M-h M-h' this will run `find-here-links', that will run something similar to: (find-einfo-links "(elisp)Top") The code that produces the short hyperlink to an info node is not currently very smart. If you look at the definition of `find-elnode' here (find-code-c-d "el" ee-emacs-lisp-directory "elisp") you will see that it saves the "el" and the "elisp" in global variables by running this: (setq ee-info-code "el") (setq ee-info-file "elisp") The short hyperlink to an info node is only produced when Info is visting a node in a manual whose name matches the variable `ee-info-file'.

10.3. Generating short hyperlinks to intros

Let's see an example. If you follow this link and type `M-h M-h', (find-multiwindow-intro) you will get an "*Elisp hyperlinks*" buffer whose last line will be: # (find-multiwindow-intro) which is a short hyperlink to the intro.

10.4. Generating short hyperlinks to PDFs

We saw in sections 9.3 and 9.4 that after the right preparations the first of these hyperlinks (find-livesofanimalspage (+ -110 134) "woke up haggard in the mornings") (find-livesofanimalstext (+ -110 134) "woke up haggard in the mornings") opens a PDF in a certain page using xpdf, and the second one opens in an Emacs buffer the result of converting that PDF to text, goes to a certain page in it an searches for a string. It is difficult to make xpdf send information to Emacs, so this trick uses the second link. Run this, (find-livesofanimalstext (+ -110 134) "woke up haggard in the mornings") mark a piece of text in it - for example, the "no punishment" in the end of the first paragraph - and copy it to the kill ring with `M-w'. Then type `M-h M-p' (`find-pdf-links'); note that `M-h M-h' won't work here because `find-here-links' is not smart enough to detect that we are on a PDF converted to text. You will get an "*Elisp hyperlinks*" buffer that contains these links: # (find-livesofanimalspage 24) # (find-livesofanimalstext 24) # (find-livesofanimalspage (+ -110 134)) # (find-livesofanimalstext (+ -110 134)) # (find-livesofanimalspage 24 "no punishment") # (find-livesofanimalstext 24 "no punishment") # (find-livesofanimalspage (+ -110 134) "no punishment") # (find-livesofanimalstext (+ -110 134) "no punishment") Remember that we called `code-pdf-page' and `code-pdf-text' as: (code-pdf-page "livesofanimals" l-o-a) (code-pdf-text "livesofanimals" l-o-a -110) The extra argument "-110" to `code-pdf-text' tells `M-h M-p' to used "-110" as the offset. See the section 11.1 for more on `M-h M-p'.

10.5. Generating short hyperlinks to anchors

11. Generating `code-c-d's and friends

There are two main ways to generate lines like these (code-c-d "asy" "/usr/local/texlive/2019/texmf-dist/doc/asymptote/") (code-pdf-page "asy" "/usr/local/texlive/2019/texmf-dist/doc/asymptote/asymptote.pdf") (code-pdf-text "asy" "/usr/local/texlive/2019/texmf-dist/doc/asymptote/asymptote.pdf") without having to type much. One way, that is somewhat confusing, is with `M-C' (`eewrap-code-c-d') and `M-P' (`eewrap-pdflike'); you can test it by running the `eek' sexps below: (eek "<down> M-C") asy /usr/local/texlive/2019/texmf-dist/doc/asymptote/ (eek "<down> M-P") asy /usr/local/texlive/2019/texmf-dist/doc/asymptote/asymptote.pdf We will only discuss here the other way.

11.1. `find-pdf-links'

Let's call a pair of lines like this, (code-pdf-page "asy" "/usr/local/texlive/2019/texmf-dist/doc/asymptote/asymptote.pdf") (code-pdf-text "asy" "/usr/local/texlive/2019/texmf-dist/doc/asymptote/asymptote.pdf") in which we have a call to `code-pdf-page' and a call to `code-pdf-text', both pointing to the same PDF file, a "code-pdf pair". One quick way to generate a code-pdf pair is to visit the directory where your PDF file is, put the point on the line of the PDF, and type `M-h M-p' (`find-pdf-links'). Try it here: (find-fline "$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/") The exact action of `M-h M-p' depends on the major mode. If you're in dired mode then it supposes that you want links to the current directory and to the PDF on the current line - including a `code-c-d' and a code-pdf pair - and it runs `find-code-pdf-links'. The first line of the buffer will be something like: ;; (find-code-pdf-links "$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf" "{c}") where the "{c}" is something that you have to adjust by hand and then execute the first line again to regenerate the buffer - like in `find-latex-links', that was described in section 7.5. If you're not it dired mode then `find-pdf-links' supposes that you're in a buffer generated by a short hyperlink to the text of a PDF file, and it runs the function `find-pdflike-page-links'. Try `M-h M-p' in the buffer generated by the sexp below: (find-livesofanimalstext (+ -110 134)) `find-pdflike-page-links' is not very smart. It has to guess the stem ("livesofanimals"), the offset (-110), the current page, and the string that you want to use in the pos-spec. It takes the stem and the offset from the global variables `ee-page-c' and `ee-page-offset', that probably were set by the last call to a function of the form `find-___text', and it guesses the current page by counting formfeeds, and guesses that the pos-spec string is in the top of the kill ring. (To be continued...)