(Re)generate: (find-eev-quick-intro)
Source code:  (find-efunction 'find-eev-quick-intro)
More intros:  (find-emacs-keys-intro)
              (find-eev-intro)
              (find-here-links-intro)
              (find-refining-intro)
              (find-eepitch-intro)
              (find-pdf-like-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.
For more material on eev, see:

  http://anggtwu.net/#eev




1. Installing eev

The easiest way to install eev is with `M-x list-packages', as explained in this video: http://anggtwu.net/2020-list-packages-eev-nav.html http://anggtwu.net/2020-list-packages-eev-nav.html#00:01 http://www.youtube.com/watch?v=kxBjiUo88_U The three links in the "Video links:" block below [Video links:] (find-eevnavvideo "00:30" "0.1. M-x package-initialize") (find-eevnavvideo "00:39" "0.2. M-x list-packages") (find-eevnavvideo "02:33" "0.3. M-x eev-beginner") point to positions in that video; to learn how to use links like those, visit this URL: http://anggtwu.net/eev-intros/find-video-links-intro.html (find-video-links-intro) Installing eev does NOT activate eev-mode. To activate eev-mode and open this tutorial, run `M-x eev-beginner'. "Installing" eev doesn't "load" eev. The difference between installing and loading is explained here: (find-eev-levels-intro) TIP FOR BEGINNERS: if you are a real beginner with, say, less than 10 minutes of experience using Emacs, then you will probably be in a stage in which you often get stuck in the middle of something that you don't know how to leave - for example, you may be in the middle of a "complex command", and Emacs may be waiting for the keys that would complete the command. The easiest way to handle that is to leave Emacs and then start it again, and after starting it again you will need to type `M-x eev-beginner' to activate eev again. For an explanation of this in video, see: [Video links:] (find-eevnavvideo "03:46" "0.4. for the beginners: quitting and restarting") (find-eevnavvideo "04:05" "the part of the sequence of keys") (find-eevnavvideo "04:23" "go to the file menu, click quit") (find-eevnavvideo "04:41" "enter emacs again, type M-x eev-beginner") Eventually you will learn how to get out of everything and how to undo almost anything, _BUT THAT WILL NOT HAPPEN IN THE FIRST TEN MINUTES_. This tutorial is intended to make you learn the most essential things in the first ten minutes - including how to navigate in Emacs's manuals.

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 instead of executing it. Try it above. 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 highlight the subsexps `(* 2 3)', `(* 4 5)', and `4'. (+ (* 2 3) (* 4 5))

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 "~/") (find-efunctiondescr 'find-file) (find-eval-intro "5. Going back") (find-fline "/tmp/") (find-man "date") (find-sh "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'. The fourth one opens a directory that contains a part of the source code of Emacs. (find-node "(emacs)Lisp Eval") (find-enode "Lisp Eval") (find-efunction 'find-file) (find-efile "") 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 emacs-el sudo apt-get install emacs-common-non-dfsg may work - but for "...-non-dfsg" packages may need you to enable access to the "non-free" repository... ask for help if you need! An important difference between elisp hyperlinks and browser hyperlinks is discussed here: (find-links-conv-intro "1. Security vs. transparency")

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) ----------| |____________________________________________________________________| [Video links:] (find-eev2020video "29:38" "2. A tale of two `describe-key's") (find-eev2020video "31:31" "the problem with the standard `describe-key'") (find-eev2020video "35:07" "My variant: `find-ekey-links'") (find-eev2020video "37:00" "how `find-ekey-links' generates its links") (find-eev2020video "37:14" "hacker-friendly in the way that I wanted")

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://anggtwu.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) (find-here-links-intro "3. `find-here-links'") (find-here-links-intro "3. `find-here-links'" "beginners") 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") ***UPDATE*** See this: (find-kl-here-intro) for a way of generating "hyperlinks to here" that is usually much more practical than `find-here-links'. NOTE: it was implemented in dec/2023 and is still experimental!

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. 8. `M-h M-k' can also handle some sequences of input events that are not key sequences. For example, if you click on "Help" in the menu bar and then click on "Search Documentation" and then on "Emacs Terminology" in the submenus this will open this page of the Emacs manual: (find-enode "Glossary") If you do `M-h M-k' and then click on Help -> Search Documentation -> Emacs Terminology in the menu bar then `M-h M-k' will generate a buffer in which one of the first lines will be: (eek "M-h M-k <menu-bar> <help-menu> <search-documentation> <emacs-terminology>") For more information on that see: (find-enode "Menu Bar") (find-enode "Glossary" "\nInput Event") (find-elnode "Input Events") (find-elnode "Key Sequence Input" "menu-bar")

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-keys-intro "2. Key sequences") 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 has both a short name and a long name (its title), and they may be different. For example, the hyperlinks below (find-node "(emacs)Intro") (find-node "(emacs)Screen") point to nodes whose titles are "Introduction" and "The Organization of the Screen", d) each manual also has a short name, also called its _filename_, and several kinds of long names and titles. The `find-node' links use the filename in parenthesis followed by the short node name. For example: Manual title elisp hyperlink ---------------------------------------------------------- GNU Emacs Manual (find-node "(emacs)"Top) Emacs Lisp / GNU Emacs Lisp Reference Manual (find-node "(elisp)"Top) An Introduction to Programming in Emacs Lisp (find-node "(eintr)"Top) e) The "Info directory" lists all the installed info manuals. You can access it with: (find-node "(dir)Top") The main Emacs manuals appear grouped together there. Try: (find-node "(dir)Top" "extensible self-documenting") You will see something like this: Emacs * Emacs: The extensible self-documenting text editor. * Emacs FAQ: Frequently Asked Questions about Emacs. * Elisp: The Emacs Lisp Reference Manual. * Emacs Lisp Intro: A simple introduction to Emacs Lisp programming. f) Emacs uses "Info mode" when displaying nodes of manuals in info format. In Info mode the tool bar displays icons meaning "back", "forward", "previous", "next", "home", etc, and you can click on these icons to navigate from the current node to other nodes. The main keys of Info mode are worth learning, though - the full list of keys can be found here, (find-efunctiondescr 'Info-mode) and the main ones are: 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 u move "up" from this node n move to the "next" node of this node p move to the "previous" node of this node [ go backward one node, considering all nodes as forming one sequence ] go forward one node, considering all nodes as forming one sequence d go to the Info directory node. l move back in history to the last node you were at. r move forward in history to the node you returned from after using `l' L go to menu of visited nodes T go to table of contents of the current Info file Try the keys above now - if you execute the `eek' sexp below it will split the window, keep these instructions in the left window and open and Info buffer at the right. (eek "<down> M-3 M-e ;; open the hyperlink below in the right 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'. For more details see: (find-eepitch-intro) (find-wrap-intro "2. <M-T>: produce an eepitch block") [Video links:] (find-eevnavvideo "10:36" "if I type <f8> six times here") (find-eevnavvideo "10:49" "a shell running inside Emacs") (find-eev2021video "00:14" "and if we type f8 several times here") (find-eev2019video "15:13" "Demo: the eepitch block (in red star lines)") (find-eev2019video "15:48" "Demo: eepitch on non-red star lines") (find-eev2019video "15:58" "Demo: eepitch in action")

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()) It is possible to display all the targets at the same time, using advanced features that are explained here: (find-multiwindow-intro "4. Several eepitch targets") (find-multiwindow-intro "7. Eepitch blocks for two targets") Here is a demo: * (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())

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'. It is possible to make other characters play the role of the red star, but to make that work you need to know a bit of Lisp. See: (find-red-star-links) (find-eev "eev-tlinks.el" "find-red-star-links")

7. Quick access to one-liners

[Video links:] (find-eevnavvideo "06:29" "M-j: you can forget practically everything...") (find-eevnavvideo "06:41" "if you type just M-j") (find-eevnavvideo "06:49" "has a header that is beginner-friendly") (find-eevnavvideo "08:45" "most of the entries have hyperlinks to the manual") (find-eevnavvideo "09:49" "M-j with numeric prefixes") (find-eevnavvideo "09:59" "M-2 M-j runs (find-emacs-keys-intro)") (find-eevnavvideo "10:06" "M-5 M-j runs (find-eev-quick-intro)")

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") (find-elisp-intro "6. Defining 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) `find-eejumps' is explained in the next section. Let's try to understand `M-j' 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. We will sometimes refer to the one-liner associated to the argument nnn as the "eejump target associated to nnn", or just as the "target associated to nnn".

7.2. The list of eejump targets

If you type `M-j' without a prefix argument it runs `(find-eejumps)', that displays a temporary buffer with a header with help and links and then a list of all the current eejump targets. Try it: (eek "M-j") (find-eejumps) The header is this: ;; Generated by: (find-eejumps) ;; See: (find-eev-quick-intro "7.1. `eejump'" "`M-j'") ;; (find-eev-quick-intro "7.2. The list of eejump targets") ;; (find-emacs-keys-intro "1. Basic keys (eev)") ;; (find-emacs-keys-intro "2. Key sequences") ;; For example, ;; M-5 M-j runs: (find-eev-quick-intro) ;; M-2 M-j runs: (find-emacs-keys-intro) ;; M-1 M-j runs: (find-fline "~/TODO") ;; M-2 M-1 M-j shows the file ~/TODO in the right window ;; M-3 M-1 M-j opens ~/TODO in the right window ;; Current eejump targets: Note that after the "See:" we have four elisp hyperlinks to sections of tutorials, and after the "For example:" we have five examples of how to run `M-j' with numeric prefixes; the first three of these examples are followed by the elisp hyperlink whose action corresponds to running `M-j' with that prefix. That header is very beginner-friendly, and if you are a beginner who only knows how to use `M-e' and `M-j' you can, and should, use that header as your main starting point: every time that you feel lost you can type `M-j' to go back to that header, and you can use its links to navigate to the documentation for Emacs and eev. That header is followed by a section that is very beginner UN-friendly, that contains a series of defuns like these ones: (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") [Video links:] (find-eev2020video "26:48" "1.5.3. `M-J' (meta-uppercase-J)") (find-eev2020video "26:58" "transforms the current line") (find-eev2020video "27:36" "into a defun")

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-pdf-page "/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-enode "M-x") (find-enode "Commands") (find-elnode "Defining Commands") Remember that you can list all current eejump targets with: (find-eejumps) you can list the current commands with very short names with: (find-eeshortdefs) [Video links:] (find-eev2020video "19:03" "commands with very short names") (find-eev2020video "21:07" "commands with very short numbers")

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 something like: _____________________________________________________________________ |# (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

[Video links:] (find-eevfherelvideo "14:18" "4.1. Creating anchors") (find-eevfherelvideo "15:22" "an index at the beginning of the file") (find-eevfherelvideo "15:47" "the tutorial also explains ... `M-A'") (find-eevfherelvideo "16:07" "`M-A' duplicates the line and...") (find-eevfherelvideo "16:19" "`M-B' creates an e-script block")

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) Another way of moving the index line to the index section is described here: (find-edit-index-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.2 - to point to anchors or to e-script blocks in your files. [Video links:] (find-eevfherelvideo "17:02" "4.2. The option :anchor for `code-c-d'")

9. Shorter hyperlinks

See also: (find-code-c-d-intro) [Video links:] (find-eev2020video "08:18" "`code-c-d' defines several new functions") (find-eev2020video "14:43" "1.4. How code-c-d is implemented") (find-eev2020video "17:20" "find-code-c-d shows the code...") (find-eev2019video "17:02" "Demo: `code-c-d'")

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

This section was moved to another tutorial! See: (find-pdf-like-intro "2. Preparation") (find-pdf-like-intro "3. Hyperlinks to PDF files") Here is a very short summary. If you have run the preparation, by executing the eepitch block below with <f8>s, * (eepitch-shell) * (eepitch-kill) * (eepitch-shell) cd wget -nc https://tannerlectures.utah.edu/_resources/documents/a-to-z/c/Coetzee99.pdf then these sexps will be hyperlinks to a page of a PDF, and to some string in it... (find-pdf-page "~/Coetzee99.pdf" 3 "LECTURE I") (find-pdf-text "~/Coetzee99.pdf" 3 "LECTURE I") [Video links:] (find-eev2020video "04:51" "`find-pdf-page' calls an external program") (find-eev2020video "05:26" "`find-pdf-text' converts the PDF to text and")

9.4. Shorter hyperlinks to PDF files

...and the `code-pdf-page' and `code-pdf-text' sexps below (code-pdf-page "livesofanimals" "~/Coetzee99.pdf") (code-pdf-text "livesofanimals" "~/Coetzee99.pdf" -110) define the functions `find-livesofanimalspage' and `find-livesofanimalstext', and the two sexps below (find-livesofanimalspage (+ -110 113) "LECTURE I.") (find-livesofanimalstext (+ -110 113) "LECTURE I.") are now short hyperlinks to a page of a PDF, and to a string in it.

9.5. Hyperlinks to audio and video files

Eev has some support for creating hyperlinks and short hyperlinks to positions in audio files and video files, but it is not as mature as the support for hyperlinks to positions in PDF files. See: (find-audiovideo-intro)

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") That file does not exist, but that is not important in the tests. Note that the last three sexps are short hyperlinks. If you run (eek "<down> M-3 M-e ;; open the hyperlink below in the right window") (find-file-links "/tmp/FOO/BAR/PLIC/bletch") it 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. Remember that `find-here-links' - i.e., `M-h M-h' - can act in several different ways depending on the context, i.e., depending on what is "here". If you type `M-h M-h' in a buffer visiting a file it runs a slight variation of `find-file-links' on that file, and if you visit our test file with, say, (find-plicfile "bletch") and type `M-h M-h' there then one of the hyperlinks that will be shown will be exactly the one with `find-plicfile'. 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)Box Diagrams") (find-node "(elisp)Box Diagrams") (find-elnode "Box Diagrams") Note that the last one is a short hyperlink. If you follow it and then type `M-h M-h' you will see that the last hyperlink in the "*(find-here-links)*" is exactly that short hyperlink. But try this big sexp: (progn (find-elnode "Box Diagrams") (eek "C-h r ;; info-emacs-manual") (eek "M-h M-h ;; find-here-links") ) You will get a "*(find-here-links)*" buffer that points to a page in the "(emacs)" manual instead of to one in the "(elisp)" manual, and that does not have a short hyperlink at the end. What happened? The trick is that the code that produces that short hyperlink uses two global variables and runs conditionally. When you run (find-elnode "Box Diagrams") it sets these two variables: (setq ee-info-code "el") (setq ee-info-file "elisp") You can check that in its source code: (find-efunctionpp 'find-elnode) (find-code-c-d "el" ee-emacs-lisp-directory "elisp") The sub-function of `find-here-links' that is executed when `find-here-links' detects that "here" is an info node only generates the short hyperlink when the current "info file" corresponds to the value saved in the global 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

This section was moved to: (find-pdf-like-intro "9. Generating three pairs")

10.5. Generating short hyperlinks to anchors

See: (find-refining-intro "5. Pointing 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. The old way is with `M-C' (`eewrap-code-c-d') and `M-P' (`eewrap-pdflike'), that transform the current line in a way similar to `M-T' (`eewrap-eepitch'). You can test these key sequences 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 The new way is with `M-h M-e', that is explained here: (find-audiovideo-intro "4.1. `find-extra-file-links'")

11.1. `find-pdf-links'

This section was moved to: (find-pdf-like-intro "8. `find-pdf'-pairs") (find-pdf-like-intro "9. Generating three pairs") (To be continued...)