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

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.

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

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 | | | |_______________| |__________|__________| |________________|

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

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