(Re)generate: (find-here-links-intro)
Source code:  (find-efunction 'find-here-links-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 will be merged with
at some point...

Eev's central idea is that you can keep "executable logs" of
what you do, in a format that is reasonably readable and that is
easy to "play back" later, step by step and in any order. We
call these executable logs, or executable notes, "e-scripts".

[Video links:]
  (find-eev2019video "5:41" "e-scripts")
  (find-eev2019video "12:54" "A demo")

1. Alternating between "task" and "notes"

In the old days log books were always made of paper, and there was nothing automatic in taking notes with them. We would have to decide what to write and how to write it, and we would have to alternate between the "task" and "taking notes". After many years of practice _some_ people would learn how to take notes without distracting themselves much from the task at hand, and they would learn how to make their notes at the same time concise and readable enough. Nowadays, with computers, there are _some_ ways to write logs automatically - for example, most shells record the commands given to them - but the output is of low quality. Eev takes an intermediate stance between "notes by hand" and "automatic notes". It is possible to do "task"+"notes" with just a few more keystrokes than for doing just "task", but that requires learning some tricks, and having some practice.

1.1. Reading and writing

Learning eev is like learning to read and write. We first learn _how to read_, and we learn _how to write_ in a second stage, when we have read a lot and we are able to read what we write. Learning eev is also like learning to use paper notebooks. It is much easier to understand the notes and ideas what we wrote ourselves in our notebooks than to understand what other people wrote in their notebooks... when we go back to what _we_ wrote we are able to reconnect with what we were thinking, even when our notes are quite terse because we did not write down all details - and we can't do that with other people's notes. So: we have to first learn how to _read_ executable notes in order to be able to _write_ our own executable notes, but after learning the basics we will usually find it much easier to read our own executable notes than to read other people's notes... This is very similar to what happens in programming. Programmers usually takes years, and a lot of effort, to learn to write code and comments that other people find readable, and what they do after that is not that they write super-readable code all the time - instead they _adjust_ the level of readability of their code depending on the situation: they write the code that will be used and read by other people in a cleaner, more readable style with lots of comments, and they write "throwaway code" that they will only run once in a very terse, and often messy, style. Most of my executable notes are written - or rather, "appear" - when I am learning something and I am switching rather mindlessly between "task" and "notes" as I explained in the previous section. What I write looks like throwaway code, only worse - because I usually leave lots of unfinished parts intermixed with the parts that run, without marking clearly which are which... but when I go through my notes about a task again I usually clean my notes a bit. For me going through my executable notes about a task again always involves a bit of _rewriting_ - which is something that programmers often do with their own code, but that we don't do much with paper notebooks. Anyway: be prepared to create executable notes that are almost unreadable, even by you when you go back to them a few hours later - that's normal, that's how things are, and you can, and WILL, rewrite the most useful parts... Note that this "intro" is about writing elisp hyperlinks. The tricks for writing eepitch blocks and index-anchor pairs are discussed elsewhere.

2. "Here"

In this tutorial we will learn the basic technique for creating an elisp hyperlink to "here" and copying it to our notes. "Here" means the current Emacs buffer; we saw in the main tutorial that elisp hyperlinks like (find-eev-quick-intro "4. Creating Elisp Hyperlinks") (find-emacs-keys-intro "3. Cutting & pasting") (find-fline "~/") (find-eevfile "") (find-eevfile "eev-blinks.el") (find-efunctiondescr 'find-file) (find-enode "Modes") (find-elnode "Defining Functions" "(defun foo () 5)") (find-man "date") open eev tutorials (`find-xxx-intro's), directories, files, descriptions of emacs functions, sections of manuals in "info" format, and manpages. All the elisp hyperlinks above are of the kind described in the first paragraphs of this section of the main tutorial: (find-eev-quick-intro "3. Elisp hyperlinks") They (usually) create a new buffer, and it is possible to "go back" from that buffer with `M-k' of `M-K': (find-eval-intro "5. Going back") [Video links:] (find-eev2020video "2:25" "variants that were better behaved") (find-eev2020video "2:36" "in the same window as before")

3. `find-here-links'

Eev has a function, called `find-here-links' and bound to `M-h M-h', that is able to distinguish several kinds of "here"s. When we run it it creates a temporary buffer with lots of elisp hyperlinks, and when we have enough practice we can spot in a second which of its hyperlinks is the "hyperlink to here" that we want to copy to our notes. This tutorial is about a _variant_ of `find-here-links' that is more suitable for beginners.

4. `find-here-links-3'

Suppose that you are in a buffer with something interesting - "here" -, and you want to generate a hyperlink to it and copy that hyperlink to your notes. Some terminology: 1. The target of that hyperlink will be the "here" buffer, so let's call the "here" buffer the "target buffer" from now on. 2. `find-here-links' creates a temporary buffer with several elisp hyperlinks - let's call that buffer the "elinks buffer". 3. Beginners start by putting all their (executable) notes in a single file, "~/TODO"; remember that `M-1 M-j' jumps to that file. The "notes buffer" is a buffer visiting the file "~/TODO". The key sequence `M-h M-3' saves the current window configuration in a variable called `ee-window-configuration-before-M-h-M-3', creates a 3-window setting like this, _____________________ | | | | | elinks | | | buffer | | target |__________| | buffer | | | | notes | | | buffer | |__________|__________| and puts the cursor at the elinks buffer.

5. `find-here-links-1'

After creating the three windows described above we will usually want to select a line from the elinks buffer - the right one, i.e., the one with a hyperlink to the target buffer - and copy it to the notes buffer; the next section explains how to do this. After copying the hyperlink - or after deciding that we don't want to copy it - we want to restore the original window configuration that we had before typing `M-h M-3'. We can do that by typing `M-h M-1' (`find-here-links-1'); I chose to use the suffix "1" because in most cases the original window configuration has a single window with the target buffer in it, and the "1" is a reference to this: (find-emacs-keys-intro "6. Windows" "C-x 1") Note that `M-h M-1' undoes what `M-h M-3' did. In a figure: _______________ _____________________ ________________ | | | | | | | | | | | elinks | | | | | | | buffer | | | | target | M-h M-3 | target |__________| M-h M-1 | target | | buffer | ------> | buffer | | ------> | buffer | | | | | notes | | | | | | | buffer | | | |_______________| |__________|__________| |________________| [Video links:] (find-eevfherelvideo "4:40" "2. The beginner's way") (find-eevfherelvideo "4:40" "2.1. The 3-window setting - and going back from it") (find-eevfherelvideo "6:47" "`M-h M-3': three windows; `M-h M-1' goes back") (find-eevfherelvideo "7:29" "the original configuration can be anything")

6. Copying the hyperlink

When you are a beginner, the easiest way to copy an elisp hyperlink from the elinks buffer to the notes buffer is to put the cursor on the line with the hyperlink, then type `M-h M-w' (`ee-copy-this-line-to-kill-ring'), and then go to the notes buffer and copy it to there with `C-y' or with the entry "Edit -> Paste" in the menu bar. Note that in the three-window setting copying a hyperlink from the elinks buffer to the notes buffer means copying it from the upper right window to the lower right window: _____________________ | | | | | elinks | | | buffer | | target |____||____| | buffer | \/ | | | notes | | | buffer | |__________|__________| When you become a slightly more advanced user the easiest way is the one with the key sequences described here: (find-eev-quick-intro "5.2. Cutting and pasting") [Video links:] (find-eevfherelvideo "8:56" "2.2. Copying one link")

7. Refining your hyperlinks

After learning the technique above, that was based on the keys: M-h M-3 -- find-here-links-3 M-h M-w -- ee-copy-this-line-to-kill-ring C-y -- yank, i.e., paste; see: (find-enode "Kill Ring") M-h M-1 -- find-here-links-1 The next steps are to learn how: a) Refine hyperlinks. See: (find-refining-intro "1. Pos-spec-lists") (find-refining-intro "2. Refining hyperlinks") b) Work with a single window. See: (find-refining-intro "3. Three buffers") c) Use other keys that create buffers with hyperlinks. See: (find-emacs-keys-intro "Some other keys that create")

8. Debugging

The best way to understand the innards of `find-here-links' is to call it in "debug mode". This is explained here: (find-eevfile "eev-hlinks.el" "Debug mode")