(Re)generate: (find-windows-beginner-intro)
Source code: (find-efunction 'find-windows-beginner-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.
The quickest way to open or recreate this is with `M-3 M-j'.
This is a tutorial on how to install Emacs and eev on M$ Windows,
and on the basic steps for learning Emacs and eev after
installing them. If you're a W$ user you should start by reading
this tutorial online in a browser, at
http://anggtwu.net/eev-intros/find-windows-beginner-intro.html
while you run Emacs in another window (see section 1). After
getting eev installed on your machine (see section 3) you will be
able to access this tutorial from Emacs by typing `M-3 M-j'.
The main tutorial on eev is this one,
(find-eev-quick-intro)
http://anggtwu.net/eev-intros/find-eev-quick-intro.html
The sections from 5.6 onwards were written in nov/2021 and they
cover how to install some external programs to make almost all
features of eev work on M$ Windows. Feedback on them would be
greatly appreciated!
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://anggtwu.net/emacsconf2019.html
http://anggtwu.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 of the video on youtube, plus two related links that are
harder to explain:
http://www.youtube.com/watch?v=86yiRG8YJD0#t=15m11s
(find-eev2019video "15:11" "Demo: the eepitch block")
http://anggtwu.net/.emacs.videos.html#eev2019
I don't have easy access to Windows machines, so I have to rely
on friends to test some things for me. I also don't have easy
access to people who use Windows and who do have experience using
terminals, so from time to time I give workshops for "total
beginners" like the one described here,
(find-video-links-intro "8. Windows")
and I see that the people on those workshops get stuck on ideas
that I thought that were obvious, and I change my approach, and I
rewrite lots of things.
This is my N-th attempt to rewrite this tutorial.
Version of these instructions: 2022nov28.
1. Download and install Emacs
You can install a recent version of Emacs for Windows with the
"installer.exe" below:
https://www.gnu.org/software/emacs/
https://www.gnu.org/software/emacs/download.html#windows
https://ftp.gnu.org/gnu/emacs/windows/
https://ftp.gnu.org/gnu/emacs/windows/emacs-28/
https://ftp.gnu.org/gnu/emacs/windows/emacs-28/emacs-28.2-installer.exe
You may need to create a desktop icon or shortcut to
<emacsdir>/bin/runemacs.exe.
1.1. Using Emacs 27.2 on Windows
Long story short: DON'T DO THAT! =(
Installing eev - or any other package from ELPA - on Emacs 27.2
on Windows may be tricky. For details, see:
(find-eev-install-intro "5. Ways to download eev")
(find-eev-install-intro "5. Ways to download eev" "2.")
(find-eev-install-intro "5. Ways to download eev" "because of this bug")
So: please upgrade to Emacs28 if you can!
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, do this:
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)
There's a video about these basic steps here:
"How to install eev with M-x list-packages and how to navigate its tutorials"
http://anggtwu.net/eev-videos/2020-list-packages-eev-nav.mp4
http://anggtwu.net/2020-list-packages-eev-nav.html
http://anggtwu.net/.emacs.videos.html#eevnav
http://www.youtube.com/watch?v=kxBjiUo88_U
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 what 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
5.6. Eshell
The manual of Eshell - here,
(find-node "(eshell)Top")
describes it as: "Eshell is a shell-like command interpreter
implemented in Emacs Lisp".
This feature of eev:
(find-psne-intro "1. Local copies of files from the internet")
needs to run wget on a unix-like shell, and it turns out that
this can be achieved easily using Eshell. For a discussion of the
tecnhical details, see:
https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00051.html
https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00058.html
https://lists.gnu.org/archive/html/help-gnu-emacs/2021-10/msg00126.html
5.6.1. Echo in Eshell
Note that the "echo" of Eshell has a quirk: if you run these
lines
echo http://foo.bar/ >> ~/.psne.log
echo http://qux.bletch/ >> ~/.psne.log
echo http://plic.ploc/ >> ~/.psne.log
on a "normal" unix shell these URLs will be appended to
~/.psne.log with newlines separating them, but if you run that in
Eshell they will be appended without newlines. One way to fix
that is to invoke the (built-in!) echo of Eshell with the "-N"
option, like this:
echo -N http://foo.bar/ >> ~/.psne.log
echo -N http://qux.bletch/ >> ~/.psne.log
echo -N http://plic.ploc/ >> ~/.psne.log
The option "-N" ("terminate with a newline") is only
explained in the source of eshell:
(find-efile "eshell/em-basic.el" "defun eshell/echo" "?N")
`find-psne-links' accepts two optional arguments after the URL.
The first of them is called `wget-options', and when it is not
given it defaults to "-nc" ("no-clobber"). The second
optional argument is called `echo-options', and _ideally_ it
should default to "" on "normal" unix shells, and to "-N"
on eshell. When it is not given eev runs the function
`ee-find-psne-echo-options' to decide what to do, and the default
definition of that function is:
;; See: (find-eev "eev-tlinks.el" "ee-find-psne-echo-options")
;;
(defun ee-find-psne-echo-options ()
(if (eq system-type 'windows-nt) "-N" ""))
which means: if a person is "on Windows", suppose that she is
using Eshell, and that she needs "echo -N"; is a person is on
"non-Windows", suppose that she is using a "normal" unix
shell, and that she needs just "echo", without the "-N". The
exact definition of the term "on Windows" can be found here:
(find-evardescr 'system-type "windows-nt")
(find-elnode "System Environment" "windows-nt")
The suppositions above are often wrong. Here is the easiest way
to fix them: if you are "on Windows" but you use a "normal"
unix shell, you can put these two lines in your ~/.emacs to
override the definition above:
;; See: (find-windows-beginner-intro "5.6.1. Echo in Eshell")
(defun ee-find-psne-echo-options () "")
and if you are "on non-Windows" but you use mostly Eshell, you
can put this in your ~/.emacs instead:
;; See: (find-windows-beginner-intro "5.6.1. Echo in Eshell")
(defun ee-find-psne-echo-options () "-N")
If you use both Eshell and "normal" unix shells you can try to
redefine `ee-find-psne-echo-options' in other ways. If you find a
smarter way that works well, please get in touch!!!
6. Video links
If you're on Windows you need to start by configuring your
browser and the path to it. The old instructions for that are
here...
(find-video-links-intro)
(find-video-links-intro "3. `find-youtube-video'")
(find-video-links-intro "4. Configuring the browser")
...but in may/2022 I created a better way. It is explained in
the next section.
7. eev-wconfig.el
NOTE: until may/2022 this section was about this module:
(find-eev "eev-on-windows.el")
that became obsolete, and was superseded by:
(find-eev "eev-wconfig.el")
(find-eev "eev-wconfig.el" "intro")
To run eev-wconfig you need to run these sexps:
(require 'eev-wconfig)
(find-wconfig-links)
`(find-wconfig-links)' shows a temporary buffer with links to
several "sub-wconfigs". The main ones are:
(find-wconfig-browser-links)
(find-wconfig-wget-links)
(find-wconfig-shell-links)
(find-wconfig-lua-links)
(find-wconfig-mpv-links)
(find-wconfig-exercises-links)
Each one of these sub-wconfigs has detailed instructions for
configuring the thing/word after it: browser, wget, (E)shell,
Lua, Mpv. The best way to understand how to use these
sub-wconfigs is by watching the video about eev-wconfig, that is
here:
Page: http://anggtwu.net/eev-wconfig.html
Index: (find-1stclassvideoindex "2022eevwconfig")
Info: (find-1stclassvideo-links "2022eevwconfig")
Play: (find-2022eevwconfigvideo "0:00")
(find-2022eevwconfigvideo "17:29" "(find-wconfig-browser-links)")
(find-2022eevwconfigvideo "26:52" "...a long digression...")
(find-2022eevwconfigvideo "39:20" "(find-wconfig-wget-links)")
(find-2022eevwconfigvideo "53:41" "(find-wconfig-shell-links)")
(find-2022eevwconfigvideo "57:45" "(find-wconfig-lua-links)")
(find-2022eevwconfigvideo "59:17" "(find-wconfig-mpv-links)")
(find-2022eevwconfigvideo "1:06:16" "(find-wconfig-exercises-links)")
Note that I've included links to the parts of the video that
describe each one of the sub-wconfigs, and note that you will
only be able to use the `find-2022eevwconfigvideo' links _to play
local copies of the videos_ after configuring mpv... so it's
better to start by accessing this section in a browser, at:
http://anggtwu.net/eev-intros/find-windows-beginner-intro.html#7
7.1. `ee-use-windows'
(Obsolete, deleted)
7.2. Testing wget.exe
(Obsolete, deleted)
(Obsolete, deleted)
7.4. Downloading videos
The default behavior for a video link like this one
(find-eevtestblsvideo "2:33" "if I run f8 here")
is to download a local copy of the video if it hasn't been
already downloaded, and then play the local copy with mpv. The
downloading is not automatic; the user has to "psne" it - see
the section 7.2 and this video:
(find-eevvlinksvideo "6:09" "if I execute this `find-eevtestblsvideo'")
(find-eevvlinksvideo "6:15" "the last line says `Local file NOT found'")
Now that you understand psne-ing, try the three standard
behaviors for video links. First make sure that we don't have a
local copy of the "eevtestbls" video, by running this:
* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
rm -fv $S/http/anggtwu.net/eev-videos/2021-test-blocks.mp4
ls -l $S/http/anggtwu.net/eev-videos/2021-test-blocks.mp4
Then run these sexps:
(ee-use-local-videos)
(find-eevtestblsvideo "2:33" "if I run f8 here")
(setq ee-find-eev-video-function 'find-eevlinks-video)
(find-eevtestblsvideo "2:33" "if I run f8 here")
(ee-use-youtube-videos)
(find-eevtestblsvideo "2:33" "if I run f8 here")
The three behaviors are explained here:
(find-video-links-intro "7. `find-eev-video'")
(find-video-links-intro "The default is `find-eevlocal-video', but")
7.5. Downloading PDFs
(Obsolete, deleted)
7.6. Saving your settings
(Obsolete, deleted)
7.7. Testing your settings
(Obsolete, deleted)
7.8. Saving your settings to your ~/.emacs
(Obsolete, deleted)
8. Summary
[Unfinished!!!]