Warning: this is an htmlized version!
The original is across this link,
and the conversion rules are here.
(Re)generate: (find-eev-quick-intro)
Source code:  (find-efunction 'find-eev-quick-intro)
More intros:  (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:

  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/
  mkdir  ~/eev/
  cd     ~/eev/
  rm -v eev2.tgz
  wget http://angg.twu.net/eev-current/eev2.tgz
  tar -xvzf eev2.tgz
  {
    echo '#!/bin/sh'
    echo 'cd ~/eev/ && emacs -l eev-readme.el --eval="(find-eev-quick-intro)"'
  } > ~/e
  chmod 755 ~/e
}

You now have a shell script that you can invoke with

  ~/e

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 "~/e" 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.




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 "<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!




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.




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            (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 imporant! 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
-----------
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 "<down> 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'.






(To be continued...)