(Chapa 1)


Installing Emacs and eev on M$ Windows

This is a tutorial on how to install Emacs and eev on M$ Windows.
If you're a W$ user you should start by reading it online, at:


After getting eev installed on your machine you can access it
from Emacs by typing `M-3 M-j'.

0. Introduction

My favorite exposition of what eev is is this presentation, called "How to record executable notes with eev - and how to play them back": http://angg.twu.net/emacsconf2019.html http://angg.twu.net/LATEX/2019emacsconf.pdf (slides) http://www.youtube.com/watch?v=86yiRG8YJD0 (video) The video ends with a demo that shows a non-trivial example of "executable notes". The most interesting part of that demo shows how to use eev to send commands to an external program - a unix shell, being run in interactive mode. Here's a link to that part (the t=938 tells youtube to jump to 15:38): http://www.youtube.com/watch?v=86yiRG8YJD0&t=938 These notes are an attempt - ongoing, and work in progress! - to help Windows users with installing Emacs, eev, and Lua, and with trying to use Emacs on Windows to send commands to external programs - currently first to the crappy shell that comes with Windows, and after that to Lua. A future version of these instructions will also include how to install Python, how to run it interactively from Emacs, and how to send commands to it. I don't have easy access to Windows machines, so I'm having to ask friends to try this for me. Also, Linux/*NIXes are Windows are totally different planets - it's common for Windows people, even programmers, to have practically zero experience with terminals, a.k.a. with "the Command Line"... in *NIXes this is so inconceivable that after discovering that many Windows programmers don't know how to use terminals I spent more than one week trying to figure out how to proceed. Version of these instructions: 2021sep20.

1. Download and install Emacs

Read the README below and then install Emacs using either the link to the .exe or the link to the .zip: http://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-28/ http://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-28/README-windows-binaries http://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-28/emacs-28.0.50-snapshot-2021-01-15-installer.exe http://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-28/emacs-28.0.50-snapshot-2021-01-15.zip If you prefer Emacs27, use these links: https://ftp.gnu.org/gnu/emacs/windows/emacs-27/ https://ftp.gnu.org/gnu/emacs/windows/emacs-27/README-windows-binaries https://ftp.gnu.org/gnu/emacs/windows/emacs-27/emacs-27.2-x86_64-installer.exe https://ftp.gnu.org/gnu/emacs/windows/emacs-27/emacs-27.2-x86_64.zip You may need to create a desktop icon or shortcut to <emacsdir>/bin/runemacs.exe. Note: don't use Emacs25 on Windows - it can't access the package repository! The details are here: https://emacs.stackexchange.com/questions/233/how-to-proceed-on-package-el-signature-check-failure/52823#52823

2. Key sequences and how to quit

Most people who use Emacs do many things by using key sequences - for example `C-x C-s' to save the current file. `C-x C-s' is the Emacs notation for "control-x control-s". This notation is explained here: (find-enode "User Input" "<Ctrl>" "a" "C-a") (find-enode "User Input" "<Meta>-a" "M-a" "<Alt>") The best way to learn key sequences when you are a beginner is by using the menu bar: (find-enode "Menu Bar") for example, in the "File" menu the last option is: Quit C-x C-c If you type just `C-x' and wait the `C-x' will be displayed in the "Echo area" at the bottom of the screen. This is explained here: (find-enode "Echo Area") The line at the very bottom of the frame is the "echo area". It is used to display small amounts of text for various purposes. The echo area is so-named because one of the things it is used for is "echoing", which means displaying the characters of a multi-character command as you type. Single-character commands are not echoed. Multi-character commands (*note Keys) are echoed if you pause for more than a second in the middle of a command. Emacs then echoes all the characters of the command so far, to prompt you for the rest. Once echoing has started, the rest of the command echoes immediately as you type it. This behavior is designed to give confident users fast response, while giving hesitant users maximum feedback. The echo area is also used to display an "error message" when a command cannot do its job. Error messages may be accompanied by beeping or by flashing the screen. There are several ways to abort a key sequence in the middle. They are explained here, (find-enode "Quitting") but what I recommend to beginners is: if you are stuck in the middle of a key sequence and don't know how to abort it, just go to the "File" menu, use the option "Quit", and restart Emacs.

3. Using M-x and installing eev

We can run commands by name by using `M-x'. `M-x' uses the last line of the screen as a "minibuffer" - see: (find-enode "Minibuffer") (find-enode "Basic Minibuffer" "it appears in the echo area") (find-enode "M-x" "Running Commands by Name") To install eev, 1. run `M-x package-initialize', 2. run `M-x list-packages', 3. select "eev" at the list of packages, 4. click on "install". To load eev and enter its tutorial, run `M-x eev-beginner'. The tutorial looks like this: (find-eev-quick-intro)

4. Understanding buffers and the mode line

It's good to be able to interpret the mode line - it gives a lot of information about where we are. See: (find-enode "Mode Line") For example, after running `M-x eev-beginner' the mode line says this: -:**- *(find-eev-quick-intro)* Top L1 (Fundamental eev) --- The best way to understand what each component means is by moving the mouse pointer onto it and looking at the help that is displayed. The main components in this case are: "**" - this buffer is read-write and has been modified. See: (find-enode "Mode Line" "**") "*(find-eev-quick-intro)*" - the name of this buffer. A curiosity: this buffer is not associated to a file! If you try to save it with `C-x C-s' or with the "Save" option in the "File" menu you will get a prompt in the minibuffer that starts with: File to save in: For more information on buffers and files, see: (find-enode "Mode Line" " BUF " "name of the buffer") (find-enode "Buffers" "Most buffers are made by visiting files") (find-enode "Basic Files") "Top L1" - see: (find-enode "Mode Line" "Top") (find-enode "Mode Line" "line number at point") (find-enode "Point") "(Fundamental eev)" - see: (find-enode "Mode Line" "(MAJOR MINOR)") (find-enode "Mode Line" "major mode") (find-enode "Mode Line" "minor modes")

5. More on modes

The "eev" in the mode line means that the key bindings defined by eev are "active". The main key bindings of eev are listed here, (find-emacs-keys-intro "1. Basic keys (eev)") and if you want more details about whats is an "active keymap" you can read these sections of the manual: (find-enode "Key Bindings") (find-enode "Keymaps") (find-enode "Local Keymaps") The five main major modes that beginners need to learn about are the Fundamental Mode, the Help Mode, the Info Mode, Dired Mode, and Shell mode. In the Fundamental Mode most "basic" keys are interpreted as editing keys - see: (find-enode "Major Modes" "Fundamental mode") (find-enode "Keymaps" "self-inserting character")

5.1. Eev mode

The three main keys of Eev Mode are these ones: M-e - to follow a hyperlink. Mnemonic: "(e)valuate"/"(e)xecute". See: (find-eev-quick-intro "2. Evaluating Lisp") (find-eev-quick-intro "3. Elisp hyperlinks") M-j - to jump to certain predefined places. In particular, `M-j' takes you to a buffer with basic help and a list of jump targets. See: (find-eev-quick-intro "7.2. The list of eejump targets") `M-2 M-j' takes you to this help page. `M-5 M-j' takes you to: (find-eev-quick-intro) M-k - to go back. Mnemonic: "(k)ill buffer". See: (find-eev-quick-intro "3. Elisp hyperlinks" "M-k") The text above was taken from: (find-emacs-keys-intro "1. Basic keys (eev)") From this point onwards I will suppose that the reader knows how to use at least `M-e' and `M-j'. Note the Eev mode is a global minor mode. The next subsections are about the other four main major modes - besides Fundamental mode.

5.2. Help Mode

Most help commands in Emacs display buffers in Help Mode. For example, if you run `C-h f Info-mode' or execute one of the sexps below (find-efunctiondescr 'Info-mode) (find-efunctiondescr 'help-mode) (find-efunctiondescr 'dired-mode) you will get buffers in Help Mode - they are read-only, and if you type `q' in them this be interpreted as `quit' rather than as "insert the character `q'".

5.3. Info Mode

The key sequence `C-h r' opens the Emacs manual in Info Mode. This is a read-only mode like Help Mode, but more keys become navigation keys. The main ones are: q Quit Info: reselect previously selected buffer. RET Follow a node reference near point. n Move to the "next" node of this node. p Move to the "previous" node of this node. u Move "up" from this node. Also, the tool bar changes completely, and it shows icons corresponding to the main navigation keys. See: (find-enode "Tool Bars")

5.4. Dired Mode

Dired Mode lets you navigate the directory structure. You can enter it by typing `C-x C-f RET'. If you type `RET' on a line that shows a directory this will be interpreted as "enter that directory", and `RET' on a line that shows a file is interpreted as "open that file". See: (find-enode "Dired") (find-enode "Dired Enter" "C-x C-f") (find-enode "ls in Lisp")

5.5. Shell Mode

Emacs can run terminals inside its buffers - and by default that terminal runs the default shell. In Windows the default shell is "cmd.exe", that is reminiscent of MS-DOS, and is VERY clumsly. See: https://en.wikipedia.org/wiki/Windows_Console https://en.wikipedia.org/wiki/Command-line_interface https://en.wikipedia.org/wiki/MS-DOS#Windows_command-line_interface https://en.wikipedia.org/wiki/Cmd.exe https://en.wikipedia.org/wiki/Batch_file https://en.wikipedia.org/wiki/Terminal_emulator If you run `M-x shell' you will get a shell buffer. See: (find-enode "Interactive Shell") especially this part of the first paragraph: To give input to the subshell, go to the end of the buffer and type the input, terminated by <RET>. As an exercise, try to give these commands to the Windows shell: dir cd cd .. dir

6. Eepitch on Windows

The main tutorial of eev explains the best way to use shells from Emacs in this section: (find-eev-quick-intro "6. Controlling shell-like programs") The default shell on Windows is a very bad one - cmd.exe, that we saw in section 5.5 - and by default `eepitch-shell' uses cmd.exe. One alternative is to use Eshell: (find-node "(eshell)Top") Most people who use Windows have very little experience with shells, and I am trying to use eev to create tutorials to save them... *** This is a project that is still in a VERY early stage!!! *** *** I will describe its current state, and I will end this *** *** section with a "please test this and get in touch!". *** I am preparing a one-session workshop for Windows users that should happen in the middle of oct/2021. Most of my material about it is in Portuguese, but In 2021oct03 I sent these two e-mails to the help-gnu-emacs mailing list, in which I explained it in English and asked for help: https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00037.html https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00045.html Many features in eev require a program called wget, and I need to prepare instructions for installing wget that can be executed by people who have never used a terminal or a shell in their lives. I _have the impression_ that it will be better to use PowerShell for that. The Wikipedia page about PowerShell is here: https://en.wikipedia.org/wiki/PowerShell It seems that every recent version of Windows comes with PowerShell, and it seems that one of the ways of running PowerShell is to open a terminal and run the command "pwsh" in it... [please, people, can you test this and tell me if it works?] In 2021oct04 I added support for PowerShell to eev, but I was only able to test it on Linux, using a version of PowerShell that runs on Linux...

6.1. `eepitch-pwsh': a test

Please, people, can you test the eepitch block below with <f8>s and tell me if you get something similar to what I got in this screenshot? Link to the screenshot: http://angg.twu.net/2021.1-projeto/eepitch-pwsh.png Here is the eepitch block: * (eepitch-pwsh) * (eepitch-kill) * (eepitch-pwsh) mkdir -p ~/bin/ cd ~/bin/ rm -fv ~/bin/wget.exe wget http://angg.twu.net/2021.1-projeto/wget.exe ls -l wget.exe

7. Lua

Lua is a programming language that many people - like me - find much better and much simpler than Python. The examples of "controlling shell-like programs" in the main tutorials of eev use Python because it comes installed by default in all modern *NIXes... see: (find-eev-quick-intro "6.2. Other targets") (find-eepitch-intro "1.1. Another target") but on Windows Lua is easier to install than Python, so let's start by it and leave Python to a second stage. Try to follow the instructions here: (find-windows-eepitch-lua-links nil) [Unfinished!!!]