(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)
(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)
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 -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
}
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 "cat")
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 " C-a H E L L O ! 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!
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) |
|# (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)--|
|___________________________________________________________|
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
# (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:
(find-eval-intro "Producing and refining hyperlinks")
5. Links to Emacs documentation
===============================
Try these links (some of them need the Emacs manuals installed):
(find-emacs-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 (11->1.1->1.2->2->3->3.1->...->Index)
[ backward-node (Top 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 " C-a C-SPC C-w C-y 3*")
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 `' 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: ")
6.1. The main key:
-----------------------
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 .
Here's what does:
When we type on a line that starts with a red
star (""), it executes the rest of the line as Lisp, and
moves down; when we type 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 at
the target buffet.
Please try that in the example after this paragraph, by typing
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)"
Note (for ADVANCED USERS):
if the above does not work as expected then the code below MAY fix it -
try it and copy it to your .emacs if it works...
;; See: (find-eevfile "eepitch.el" "defun eepitch-window-show")
(defun eepitch-window-show ()
"An emergency hack for Emacs versions where `display-buffer' is buggy"
(find-2a nil '(find-ebuffer eepitch-buffer-name)))
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
-----------
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.
Internally, what happens is that:
`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"))
Note that if you type `M-J' (i.e., meta-uppercase-j) on the line below
then it will be converted into the "(defun eejump-1 ...)" above,
1 (find-fline "~/TODO")
and note also that if you type `M-j' without a prefix argument then it
runs `(find-eejumps)', which displays all the current eejump targets,
as defuns. Try it:
(eek "M-j")
(find-eejumps)
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 " M-J")
e (find-fline "/tmp/foo.tex")
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.
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.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:
(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 `M-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'.
8. Anchors
==========
See (old version): (find-anchors-intro)
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 '. 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 " M-F")
/tmp/
(eek " M-S")
ls /tmp/
(eek " 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 "
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 seven (!) 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
-----------------------------------------
[Explain code-c-d, find-code-c-d, :anchor and M-h M--]
(find-eevfile "")
(find-eevfile "eev-tlinks.el")
(find-eev "eev-tlinks.el")
(To be continued...)