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

1. Installing eev by hand

If you have unpacked eev in a certain directory - for example in ~/eev2/, with: rm -Rv ~/eev2/ mkdir ~/eev2/ cd ~/eev2/ rm -fv eev2.tgz wget http://angg.twu.net/eev-current/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

See: (find-elnode "Init File" ".emacs") (find-elnode "Init Examples") (find-elnode "Init File Examples") (find-eev-install-links "~/eev2/" "~/eev" "" 2 ".emacs")

4. Using the git repository

Eev has a git repository at: https://github.com/edrx/eev.git All recent changes are being made at the "UTF-8" branch and I haven't learned yet how to make the master branch point to UTF-8... so if you clone the repository you'll have to do a "checkout UTF-8" the go to the most recent version. 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/ git checkout UTF-8 # (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 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-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

5.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)

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: (find-eev "eev-template0.el")

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