(Re)generate: (find-eev-install-intro)
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.

Note: this intro contains lots of very technical information!
If you're a beginner you should skip this - but if you use
Windows then this page may be relevant to you:

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 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") 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: 1. as an Emacs package, with `M-x list-packages'; 2. as an Emacs package, by downloading a file named eev-YYYYMMDD.tar from either ELPA or angg.twu.net using links like these ones - but you'll have to correct the date: http://elpa.gnu.org/packages/eev.html http://elpa.gnu.org/packages/eev-20201013.tar http://angg.twu.net/eev-current/ http://angg.twu.net/eev-current/eev2.tar http://angg.twu.net/eev-current/eev-20201013.tar and then running `M-x package-install-file'; 3. by using the script in section 5.1 below, that downloads a .tgz from http://angg.twu.net/eev-current/eev2.tgz , unpacks it in the directory ~/eev2/ and creates a script called "~/eev" that starts Emacs loading eev and opening the main tutorial, 4. by downloading the .tgz above and unpacking it, and then running these lines yourself: (add-to-list 'load-path "~/path-to-the-eev-source/") (require 'eev-load) (autoload 'eev-beginner "eev-beginner") (eev-mode 1) ; optional 5. by downloading the git repo from https://github.com/edrx/eev.git and then running this: (add-to-list 'load-path "~/path-to-the-eev-source/") (require 'eev-load) (autoload 'eev-beginner "eev-beginner") (eev-mode 1) ; optional

5.1. Using the tarball

This way of installing eev is recommended for people who can't or who don't want to use Emacs's `M-x list-packages' (from `package.el') and who are on a *NIX-based system. To install eev using this method, you should copy and paste the block of shell commands below into a terminal, { rm -Rv ~/eev rm -Rv ~/eev2/ mkdir ~/eev2/ cd ~/eev2/ rm -fv eev2.tgz wget http://angg.twu.net/eev-current/eev2.tgz tar -xvzf eev2.tgz { echo '#!/bin/sh' echo 'cd ~/eev2/ && emacs -l eev-beginner.el --eval="(find-eev-quick-intro)" $*' } > ~/eev chmod 755 ~/eev } and then execute the commands in it. This is explained in this somewhat outdated video (from 2016!): http://angg.twu.net/eev-videos/video-eev-quick-0.mp4 In short: you will have to open this URL in a browser, http://angg.twu.net/eev-intros/find-eev-install-intro.html#5.1 in a browser, and open a terminal running a shell; then mark the multi-line "{ ... }" block above, copy it to the clipboard with ctrl-C, and paste it into the shell to run its commands. You will now have a shell script that you can invoke with ~/eev that starts Emacs, loads eev, and opens the main tutorial - i.e., runs `M-x eev-beginner'. Note that if you install eev using this method then all the files related to eev will be in the directory ~/eev2/, except for the script in ~/eev; if you start Emacs in the default way then it will not know that it has to look for stuff in ~/eev2/, and commands like `M-x eev-beginner' or sexps like (require 'eev-load) (load "eev-beginner") will not work. 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://angg.twu.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") 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://angg.twu.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 main 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") and 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")