(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.

This intro is being rewritten!
Some parts will be moved to:

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