Source code: (find-efunction 'find-eev-install-intro)
More intros: (find-eev-quick-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.
The installation instructions in
(find-eev-quick-intro "1. Installing eev")
describe a way to install eev that uses the directory "~/eev2/"
for elisp files and that creates a secript "~/eev" that starts
Emacs, loads eev, and runs `(find-eev-quick-intro)'. Here we
describe several ways to install eev in other places and how to
change your .emacs to make it load eev at startup, but lots of
things are obsolete or incomplete in this intro - many things
have changed since eev become an ELPA package!
1. Installing eev by hand
If you have unpacked eev in a certain directory - for example in
rm -Rv ~/eev2/
rm -fv eev2.tgz
tar -xvzf eev2.tgz
then you can try it with:
(add-to-list 'load-path "~/eev2/")
(require 'eev-load) ; (find-eev "eev-load.el")
(eev-mode 1) ; (find-eev "eev-mode.el")
and you can install it permanently by copying the three lines
above to your .emacs. Note that eev-mode.el has this commentary:
;; Turning on eev-mode simply activates the eev-mode-map keymap, and
;; adds an "eev" to the mode line to remind you this. Turning off
;; eev-mode deactivates the keymap and the reminder.
If you prefer to start with eev-mode off, omit the
line `(eev-mode 1)' above or change it to `(eev-mode 0)'. To
toggle eev-mode on and off, use `M-x eev'. The keybindings in
eev-mode are listed here:
(find-eev "eev-mode.el" "eev-mode-map-set")
Years ago eev was a very invasive package that changed several
global settings; now it's the opposite. If you load eev the only
things that happen are:
1) Several functions and variables become defined. They ALL
have the prefixes "find-", "ee", "code-" or "br",
except for one: "to".
2) The standard-display-table is changed to make three
characters be displayed as colored glyphs: "*" (char 15),
"«" (char 171), and "»" (char 187).
3) The environment variables "S" and "EEVDIR" are set.
4) An innocuous wrapper is installed around an internal
function used by `man'. See:
(find-eev "eev-blinks.el" "find-man")
2. Running `(find-eev-install-links)'
The shell commands in
(find-eev-quick-intro "1. Installing eev")
and the previous section can be obtained by running
`find-eev-install-links' with these arguments:
(find-eev-install-links "~/eev2/" "~/eev")
Note that `(find-eev-install-links)' is somehow similar to this,
(find-eev-quick-intro "7.3. `find-latex-links'")
and follows most of the same conventions.
If you want to install eev in a more permanent place the default
way is to run `(find-eev-install-links)' with these arguments,
(find-eev-install-links "~/eev2/" "~/eev" "#")
and execute its eepitch block.
3. Changing your .emacs
(find-elnode "Init File" ".emacs")
(find-elnode "Init Examples")
(find-elnode "Init File Examples")
(find-eev-install-links "~/eev2/" "~/eev" "" 2 ".emacs")
3.1. Adding directories to the load-path
(find-es "emacs" "package-initialize")
3.3. Keeping both the git and the ELPA versions
4. Using the git repository
Eev has a git repository at:
rm -Rfv /tmp/eev2
cd /tmp/eev2/ && git clone https://github.com/edrx/eev.git .
# (find-gitk "/tmp/eev2/")
echo 'cd /tmp/eev2/ && emacs -l eev-readme.el --eval="(find-eev-quick-intro)"'
} > /tmp/eev
chmod 755 /tmp/eev
and run the script in /tmp/eev if you want to.
Note the "cd ... && git clone URL .". This is needed because if
we don't specify a directory after the URL in "git clone" then
git will create a directory /tmp/eev/, and that would be
incompatible with our convention of creating a script called
"eev" ("/tmp/eev" in this case).
5. Eev as an ELPA/MELPA package
In march 2019 I prepared a first version of an emacs package for
eev to make it installable by `M-x list-packages' - see:
(find-efaqnode "Packages that do not come with Emacs")
and submitted it to the emacs-devel mailing list:
Stefan Monnier answered, and the rest of the discussion happened
off-list. Apparently eev could go into GNU ELPA, but some changes
and clean-ups were needed. I implemented most of what he
proposed/requested, but three of the things that he asked for
would demand changes that would make eev far less elegant and far
less useful for beginners... in rough terms, the code should 1)
be byte-compilable, 2) be compatible with lexical binding, and 3)
have all the autoloads. My reasons for not complying - or for not
complying NOW - are explained in the subsections below.
Btw: except for Stefan's e-mails ***100%*** the feedback that I
received about eev in the last three years came from beginners.
I am not willing to make changes that will make eev
UPDATE: in 2019apr14 eev became a part of ELPA even despite its
quirks!!! Its ELPA page is here:
In standard packages all elisp files should be byte-compilable
unless there is a very strong reason - but all eev source files
have a "no-byte-compile: t" in their local variables section.
(find-eevgrep "grep --color -nH -e no-byte-compile: *.el")
(find-elnode "Byte Compilation" "no-byte-compile: t")
Here is why. Each call to a `code-*' function defines some
functions dynamically - for example, `(code-c-d "e" ...)'
defines `find-efile' - and the best way to inspect a function
defined in this way is by using `find-functionpp'. Try:
(find-eev-quick-intro "9.1. `code-c-d'")
(find-eev-quick-intro "9.1. `code-c-d'" "(find-code-c-d")
(find-code-c-d "e" ee-emacs-lisp-directory "emacs" :gz)
These functions are not byte-compiled, so the contents of their
function cells are lambda expressions, which are easy to read.
The relevant sections in the manual are:
(find-elnode "What Is a Function")
(find-elnode "What Is a Function" "lambda expression")
(find-elnode "What Is a Function" "byte-code function")
(find-elnode "Lambda Expressions")
(find-elnode "Function Cells")
If we don't byte-compile the modules of eev then beginners will
have a reasonable corpus of functions for which
`find-efunctionpp' shows something readable, which is good to
help them understand the innards of Emacs.
Here is an excerpt of one of my e-mails to Stefan:
I have the impression - please correct me if I'm wrong - that
you're proposing to replace the `find-efunctionpp' by something
more modern. My view is that we have a "new" Emacs, that
enforces byte-compilation and uses several data structures that
are relatively opaque, built on top on an "old" Emacs that
uses lots of simpler data structures, but in which many things
are messier and more error-prone. I would love to add to eev
functions to inspect these new data structures, but the "old"
Emacs is the one that made me fell in love with Free Software
and that made me spend years trying to convert people... and
one of the underlying messages of eev is "look, you can still
use these simpler things". Maybe I'm using "simpler" in a
sense that is not very usual, so let me quote a paragraph from
an article that I wrote about implementing a Forth in Lua:
"I've met many people over the years who have been Forth
enthusiasts in the past, and we often end up discussing what
made Forth so thrilling to use at that time - and what we can
do to adapt its ideas to the computers of today. My personal
impression is that Forth's main points were not the ones that
I listed at the beginning of this section, and that I said
that were easy to quantify; rather, what was most important
was that nothing was hidden, there were no complex data
structures around with "don't-look-at-this" parts (think on
garbage collection in Lua, for example, and Lua's tables -
beginners need to be convinced to see these things
abstractly, as the concrete details of the implementation are
hard), and everything - code, data, dictionaries, stacks -
were just linear sequences of bytes, that could be read and
modified directly if we wished to. We had total freedom,
defining new words was quick, and experiments were quick to
make; that gave us a sense of power that was totally
different from, say, the one that a Python user feels today
because he has huge libraries at his fingertips."
5.2. Dynamic binding
Dependency on dynamic binding should be avoided - see:
(find-elnode "Dynamic Binding")
(find-elnode "Dynamic Binding Tips")
(find-elnode "Lexical Binding")
but the main function that eev uses for template strings is
intrinsically incompatible with lexical binding. See the comments
in its source file:
I decided to mark only one function in eev as autoloadable -
instead of hundreds - and this is very non-standard. See the