(Re)generate: (find-eev-install-intro)
Source code: (find-efunction 'find-eev-install-intro)
More intros: (find-eev-quick-intro)
(find-eval-intro)
(find-eepitch-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.
This intro is being rewritten!
Some parts will be moved to:
(find-eev-levels-intro)
0. Loading eev
Now - late 2022 - versions of Emacs in which `M-x list-packages'
works well are trivial to install in all OSs, including Windows,
and this makes most of the other sections of this intro mostly
irrelevant...
If you have installed eev with a package manager - either
`list-packages', that comes with Emacs and is explained here,
(find-enode "Packages")
or alternative ones like use-package or straight.el, then the
package manager will put the eev directory in your load-path, and
it will declare `eev-beginner' as an autoload. This means that
your Emacs will recognize `eev-beginner' as a command, and
running `M-x eev-beginner' will load all modules of eev and enter
the main tutorial. Autoloading and the load-path are explained
here:
(find-enode "Lisp Libraries")
0.1. Installing
_Installing_ eev with a package manager only does this:
a. this directory is put in the load-path:
(find-eevfile "")
b. the function `eev-beginner' is declared as an autoload.
0.2. Loading
_Loading_ eev does a few things more. They are explained here:
(find-eev-intro "1. `eev-mode'")
(find-eev-intro "1. `eev-mode'" "invasive")
(find-eev "eev-load.el" "autoloads")
(find-eev "eev-load.el" "load-the-main-modules")
If you want to make your Emacs _load_ eev on startup, then the
best way to do that is to put either this
;; See: (find-eev-install-intro "0. Loading eev")
(require 'eev-load)
(eev-mode 1)
or this
;; See: (find-eev-install-intro "0. Loading eev")
(require 'eev-load)
;; (eev-mode 1)
in your init file - see:
(find-enode "Init File")
Use the version with "(eev-mode 1)" if you want to turn
eev-mode on on startup, and the version with ";; (eev-mode 1)"
if you prefer to start with eev-mode off.
0.3. Activating
_Activating_ eev means "turning eev-mode on". Activating eev
does very little - see:
(find-eev-intro "1. `eev-mode'" "Turning on eev-mode")
Note that "installing", "loading", and "activating" eev are
different things, and each one does less than the next one.
TODO: rewrite the other sections of this intro!
They are old and obsolete! =(
1. Beginners and experts
When I teach Emacs and eev to beginners in workshops I install
Emacs and eev in their machines using a "beginners setup" like
the one described here,
(find-eev-quick-intro "1. Installing eev")
that lets them start Emacs displaying the main eev tutorial and
with eev-mode on; then I teach them how to use `M-e' to follow
elisp hyperlinks, and I show them that if they type just `M-j'
they get a page with some nice & important hyperlinks at its
header... then usually in less that five minutes - with a bit of
help - they figure out how to navigate the documentation and how
to do the exercises.
When I show eev to long-time Emacs users I recommend them to
install eev using an "expert setup" that is very non-intrusive,
and that does not turn eev-mode on. With eev installed but
eev-mode off all elisp hyperlinks functions are still available,
even the ones that define "shorter hyperlinks", like the ones
described in these sections,
(find-eev-quick-intro "9. Shorter hyperlinks")
(find-pdf-like-intro "7. Shorter hyperlinks to PDF files")
and people can execute sexps with `C-x C-e'. People using the
expert setup can turn eev-mode on and off - i.e., activate and
disactivate its keybindings - with `M-x eev-mode', and when
`eev-mode' is on they can go to the main tutorials with:
`M-5 M-j' - (find-eev-quick-intro)
`M-2 M-j' - (find-emacs-keys-intro)
or by following the links at the header of the page displayed by
`M-j'. Try:
`M-j' - (find-eejumps)
I try to assume that long-time Emacsers are too busy with their
other things, and that it's ok if they only spend 5 minutes per
month playing with the eev tutorials.
2. The expert setup
The "expert setup" described above corresponds to downloading
eev and then running something equivalent to this:
(add-to-list 'load-path "~/path-to-the-eev-source/")
(require 'eev-load)
If you installed eev with `M-x list-packages' - see:
(find-enode "Packages")
then the line that adjusts the load-path should not be needed.
Here's what `(require 'eev-load)' does:
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 variable "S" is set.
4) An innocuous wrapper is installed around an internal
function used by `man'. See:
(find-eev "eev-blinks.el" "find-man")
Eev has very few autoloads, so eev-load.el loads all source files
except for eev-beginner.el. See:
(find-eev "eev-load.el")
(find-eev "eev-load.el" "autoloads")
3. The beginner setup
The "beginner setup" corresponds to the expert setup plus this:
(eev-beginner)
where `eev-beginner' turns eev-mode on and runs:
(find-eev-quick-intro)
See:
(find-eev "eev-beginner.el")
If you have installed eev by following these instructions
(find-eev-quick-intro "1. Installing eev")
then the script "~/eev" will run `(eev-beginner)' for you.
In the beginner setup for Windows people have to execute `M-x
eev-beginner' by hand when they start Emacs.
4. `eev-mode'
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.
See:
(find-eev "eev-mode.el")
(find-eev "eev-mode.el" "eev-mode")
(find-efunctiondescr 'eev-mode)
(find-eminormodekeymapdescr 'eev-mode)
(find-efunctiondescr 'eev-avadj-mode)
(find-eminormodekeymapdescr 'eev-avadj-mode)
5. Ways to download eev
These are the current ways to download and install eev:
5.1. With `M-x list-packages'
This way install the version of eev that is in ELPA. See this
video for _very detailed_ instructions:
http://anggtwu.net/2020-list-packages-eev-nav.html
http://anggtwu.net/2020-list-packages-eev-nav.html#00:01
The second link goes to the subtitles of the video.
5.2. With `package-install'
This is equivalent to the previous way, but it uses sexps.
You need to copy and paste these lines to an Emacs buffer,
and then execute each one with `C-e C-x C-e':
(package-initialize)
(package-refresh-contents)
(package-install 'eev)
(eev-beginner)
5.2. With `package-vc-install'
This installs the version of eev that is in the git repository.
Copy and paste these lines to an Emacs buffer, and then execute
each one with `C-e C-x C-e':
(package-vc-install "https://github.com/edrx/eev")
(eev-beginner)
This will install eev in "~/.emacs.d/elpa/eev/". Try:
(find-fline "~/.emacs.d/elpa/eev/")
(find-fline "~/.emacs.d/elpa/eev/ChangeLog")
(find-eevfile "")
(find-eevfile "ChangeLog")
(find-eevfile "VERSION")
5.3. From the tarball in ELPA
[This section is very old! TODO: rewrite it!]
...as an Emacs package, by downloading a file named
eev-YYYYMMDD.tar from either ELPA or anggtwu.net using
links like these ones - but you'll have to correct the date:
https://elpa.gnu.org/packages/eev.html
https://elpa.gnu.org/packages/eev-20211205.tar
and then running `M-x package-install-file'.
If you're on M$ Windows and using Emacs 27.2 then you will
probably need this method, because of this bug:
https://lists.gnu.org/archive/html/bug-gnu-emacs/2021-10/msg00482.html
https://lists.gnu.org/archive/html/bug-gnu-emacs/2021-10/msg00530.html
https://lists.gnu.org/archive/html/bug-gnu-emacs/2021-10/msg00556.html
https://lists.gnu.org/archive/html/bug-gnu-emacs/2021-10/msg02148.html
There is a link to download Emacs28-pretest here:
(find-windows-beginner-intro "1. Download and install Emacs")
5.1. Using the tarball
[Obsolete, deleted, except for this last paragraph:]
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.
5.2. Using the git repository
The git repository for eev is at:
https://github.com/edrx/eev.git
Try this:
* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
rm -Rfv /tmp/eev2
mkdir /tmp/eev2/
cd /tmp/eev2/ && git clone https://github.com/edrx/eev.git .
cd /tmp/eev2/
# (find-gitk "/tmp/eev2/")
{
echo '#!/bin/sh'
echo 'cd /tmp/eev2/ && emacs -l eev-readme.el --eval="(find-eev-quick-intro)"'
} > /tmp/eev
chmod 755 /tmp/eev
/tmp/eev
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.3. Installation quirks
There were a couple of situations around may/2019 which I was
helping friends who had installed eev on Windows with `M-x
list-packages' and we found out that we had to add
a `(package-initialize)' to their ".emacs"s to make things
work... I still need to understand this. See:
(find-es "emacs" "package-initialize")
If you have installed both an eev from ELPA and an eev from the
.tgz or from the git repo then one of them will be found first in
the load-path. Check which one!
5.4. `package-install-file'
If installing the latest version of eev from ELPA with `M-x
list-packages' doesn't work you can download the latest version
of eev as a .tar file directly from its ELPA page - here:
http://elpa.gnu.org/packages/eev.html
and then run `M-x package-install-file' and give it the name of
the local copy of the .tar. See:
(find-enode "Package Files" "M-x package-install-file")
5.5. `use-package'
Some people use non-default package managers for Emacs, like
straight.el and use-package. I have very little experience with
them, but it SEEMS that this is a good recipe for using eev with
`use-package':
;; From:
;; https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00031.html
;; https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00034.html
;; See: (find-eev-install-intro "5.5. `use-package'")
;;
(use-package eev
:straight (:host github :repo "edrx/eev")
:config (progn
;; See: (find-eev "eev-load.el" "autoloads")
;; http://anggtwu.net/eev-current/eev-load.el.html#autoloads
(require 'eev-load)
;; (eev-mode 1) ; optional
;; (eev-beginner) ; optional
))
6. `find-eev-install-links'
There is this,
(find-eev-install-links)
but I sort of forgot it, and I haven't updated it recently...
note that it is somehow similar to this,
(find-eev-quick-intro "7.5. `find-latex-links'")
and follows most of the same conventions. See:
(find-elnode "Init File" ".emacs")
(find-elnode "Init Examples")
(find-elnode "Init File Examples")
(find-eev-install-links "~/eev2/" "~/eev" "" 2 ".emacs")
7. 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-enode "Packages")
(find-efaqnode "Packages that do not come with Emacs")
and submitted it to the emacs-devel mailing list:
http://lists.gnu.org/archive/html/emacs-devel/2019-03/msg00433.html
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
beginner-UNfriendly.
UPDATE: in 2019apr14 eev became a part of ELPA even despite its
quirks!!! Its ELPA page is here:
http://elpa.gnu.org/packages/eev.html
7.1. Byte-compilation
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.
See:
(find-eevgrep "grep --color -nH -e no-byte-compile: *.el")
(find-elnode "Byte Compilation" "no-byte-compile: t")
(find-elisp-intro "11.1. Why eev avoids byte-compilation")
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)
(find-efunction-links 'find-efile)
(symbol-function 'find-efile)
(find-efunctionpp 'find-efile)
(find-efunctionpp 'ee-efile)
(find-evardescr 'ee-edir)
These functions are not byte-compiled, so the contents of their
function cells are lambda expressions, which are easy to read.
Compare:
(symbol-function 'find-efile)
(find-efunctionpp 'find-efile)
(symbol-function 'find-file)
(find-efunctionpp 'find-file)
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."
(From: <http://anggtwu.net/miniforth-article.html>)
7.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 _default_ function that eev uses for template strings is
intrinsically incompatible with lexical binding. See the comments
in its source file:
(find-eev "eev-template0.el")
(find-eev "eev-template0.el" "lexical-binding")
It is possible to use a replacement for it that works in lexical
binding, but I prefer to not make this replacement the default.
See:
(find-eev "eev-template0.el" "ee-template0-lex")
See also this tutorial:
(find-lexical-intro)
I decided to make all the elisp files in eev use dynamic binding
for simplicity, even though this is frowned upon.
7.3. Autoloads
I decided to mark only one function in eev as autoloadable -
instead of hundreds - and this is very non-standard. See the
comments in:
(find-eev "eev-load.el")
and also:
(find-eev "README")
(find-eev "eev-beginner.el")
See:
(find-eev "eev-load.el")
(find-eev "eev-mode.el")