(Re)generate: (find-refining-intro)
Source code: (find-efunction 'find-refining-intro)
More intros: (find-eev-quick-intro)
(find-eev-intro)
(find-emacs-keys-intro)
(find-here-links-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.
This tutorial supposes that you already know how to
create "hyperlinks to here" - see:
(find-here-links-intro)
(find-emacs-keys-intro "and refining them")
1. Pos-spec-lists
Most hyperlinks functions defined by eev can be "refined" by
the addition of extra arguments. These extra arguments are called
a "pos-spec" (or a "pos-spec-list") and they specify a
position in the target buffer. The first argument means a certain
line number, when it is a number, or the first occurrence of a
certain string, when it is a string. Try:
(find-enode "Command Index")
(find-enode "Command Index" "eval-last-sexp")
Further arguments mean either "move down n lines" or "search
for the next occurrence of a string", depending on whether they
are numbers or strings. Try:
(find-sh "seq 2095 2115")
(find-sh "seq 2095 2115" "2100")
(find-sh "seq 2095 2115" "2100" "9")
(find-sh "seq 2095 2115" "2100" 2)
In most cases an empty pos-spec-list, like this,
(find-sh "seq 2095 2115")
means: "if the target buffer already exists then just open it"
- so that following that hyperlink would jump to the current
position of the point in that buffer.
Pos-spec-lists are usually interpreted by the function
`ee-goto-position'. The first argument is interpreted in a
special way, according to its type:
string -> jump to the first occurrence of
that string in the buffer
number -> jump to the n-th line
and the other arguments are interpreted (recursively) by
`ee-goto-rest':
string -> jump to the next occurrence of that string
number -> move down n lines
list -> evaluate the list
Here is an example in which one of the arguments is a list.
Suggestion: execute it with `M-2 M-e'.
(find-sh "seq 2095 2115" "2100" "9" '(eek "!!!"))
There are some variants of `ee-goto-position' in which the first
argument is interpreted in a different way, but we will not
discuss them here. See:
(find-efunction 'ee-goto-anchor)
(find-eev "eev-pdflike.el" "ee-goto-position-page")
If you want to add support for more complex pos-spec-lists, just
replace `ee-goto-rest' with your own extended version.
[Video links:]
(find-eev2019hsubs "01:45" "a string to search for")
(find-eev2019video "01:45" "a string to search for")
(find-eev2020hsubs "02:23" "variants that were better behaved")
(find-eev2020video "02:23" "variants that were better behaved")
(find-eev2020hsubs "02:36" "in the same window")
(find-eev2020video "02:36" "in the same window")
(find-eev2020hsubs "02:52" "pos-spec-lists")
(find-eev2020video "02:52" "pos-spec-lists")
2. Refining hyperlinks
To _refine_ a hyperlink means to add items to its pos-spec-list
to make it point to a more precise location. For example, in the
links below the first one points to an "intro", the second
points to a section in it, and the third points to an important
idea in that section:
(find-escripts-intro)
(find-escripts-intro "5. Tools for writing e-scripts")
(find-escripts-intro "5. Tools for writing e-scripts" "alternate")
The paragraph where the word "alternate" is talks about how to
alternate between a "task" and "taking notes" without losing
focus on the "task". Eev has some keys sequences for doing
that:
M-h M-h - `find-here-links'. See: (find-eev-quick-intro "`M-h M-h'")
M-h M-2 - `ee-duplicate-this-line'
M-h M-y - `ee-yank-pos-spec'
M-h M-w - `ee-copy-this-line-to-kill-ring'
Let me explain them starting by the two middle ones. This sexp
(kill-new "Tools for")
puts the string "Tools for" on the top of the kill ring; we can
use it to simulate what happens when the user marks a region
containing that string and runs `M-w'. See:
(find-enode "Kill Ring")
(find-emacs-keys-intro "3. Cutting & pasting")
Try the first two sexps below:
(kill-new "Tools for")
(eek "<down> M-h M-2 M-h M-y")
(find-escripts-intro)
The `eek' duplicates the line with "(find-escripts-intro)" and
then runs `M-h M-y' (`ee-yank-pos-spec') on it; `M-h M-y' is
based on `C-y' (`yank'),
(find-enode "Yanking")
but `M-h M-y' "yanks" the text at the end of the sexp, in
quotes, as a new argument.
[Video links:]
(find-eevfherelhsubs "10:31" "2.3. Duplicating and refining")
(find-eevfherelvideo "10:31" "2.3. Duplicating and refining")
(find-eevfherelhsubs "10:53" "as a string at the end of the sexp")
(find-eevfherelvideo "10:53" "as a string at the end of the sexp")
3. Three buffers
One very common usage pattern involves three buffers:
1. a buffer where we are storing our notes (the "notes
buffer").
2. a buffer with something interesting that we want to create a
link to (the "target buffer"),
3. a temporary buffer with editable hyperlinks, usually created
by `find-here-links' (the "elinks buffer").
Usually beginners use the file "~/TODO" - that can be accessed
with `M-1 M-j' - for all the e-script notes that they create;
learning to keep notes in several files is a skill that comes
later.
Let's take a concrete example. We found something interesting in
section 4 of `(find-escripts-intro)', and we want to keep a link
to that; we decided to use the string "snip, snip" to refine
the hyperlink -
(find-escripts-intro)
(find-escripts-intro "4. How to read an e-script")
(find-escripts-intro "snip, snip")
and we want to produce the refined hyperlink - using the keys
from the previous section -, copy it to our notes buffer, and go
back to the target buffer. The keys to switch buffers are shown
below,
________ ________ ________ ________
| | : : | | | |
| target | M-h M-h : elinks : M-1 M-j | notes | M-K M-K | target |
| buffer | ------> : buffer : ------> | buffer | ------> | buffer |
|________| :________: |________| |________|
but there are also some things that we need to do inside each one
of these buffers:
a. In the target buffer: mark the string "snip, snip" and
copy it to the kill ring with `M-w' (`kill-ring-save');
b. In the elinks buffer: go to the line with the hyperlink that
points to the target buffer - `(find-escripts-intro)' -,
refine it with `M-h M-2 M-h M-y', copy its line to the kill
ring with `M-h M-w' (`ee-copy-this-line-to-kill-ring');
c. In the notes buffer: insert the refined hyperlink with
`C-y' (`yank').
Note: `M-h M-w' (`ee-copy-this-line-to-kill-ring') is a key
sequence intended for beginners. I prefer to use something like
`C-a shift-<down> M-w'.
[Video links:]
(find-eevfherelhsubs "12:36" "3. Using a single window")
(find-eevfherelvideo "12:36" "3. Using a single window")
(find-eevfherelhsubs "13:21" "go back usually by using")
(find-eevfherelvideo "13:21" "go back usually by using")
4. A tip for beginners
TODO: Rewrite this section! It was mostly superseded by:
(find-here-links-intro "4. `find-here-links-3'")
Some people find the instructions above hard to follow because
they force them to remember lots of things that are off-screen.
If you run the second sexp below,
(define-key eev-mode-map "\M-h\M-h" 'find-here-links)
(define-key eev-mode-map "\M-h\M-h" 'find-here-links-beginner)
it will rebind the key sequence `M-h M-h' to a variant of
`find-here-links' for beginners that creates this window
configuration when invoked as `M-3 M-h M-h':
_____________________
| | |
| | elinks |
| | buffer |
| target |__________|
| buffer | |
| | notes |
| | buffer |
|__________|__________|
You can then try to run the instructions in the last section with
all the three buffers visible, switching from one buffer to
another by clicking on their windows. Note that the order is:
_____________________
| | |
| ==> elinks |
| | buffer |
| target |____||____|
| buffer | \/ |
| | notes |
| <== buffer |
|__________|__________|
and note also that, in the terminology of
(find-escripts-intro "alternate" "task" "notes")
the left side is "task" and the right side is "notes".
To rebind `M-h M-h' to its original function, run this:
(define-key eev-mode-map "\M-h\M-h" 'find-here-links)
or restart Emacs.
The big figure below shows all the key sequences:
_______________________________________
| | |
| | elinks |
| target `M-h M-h' buffer: |
| buffer: ::::::::> `M-h M-y |
| `M-w' | M-h M-w' |
| | |
| | ::`M-1 M-j' |
| |_______ :: __________|
| | \/ |
| | |
| `M-K M-K' notes |
| <:::::::: buffer: |
| | `C-y' |
| | |
|_________________|_____________________|
[Video links:]
(find-eevfherelhsubs "08:56" "2.2. Copying one link")
(find-eevfherelvideo "08:56" "2.2. Copying one link")
(find-eevfherelhsubs "10:09" "when people know a few more keys... C-w and M-w")
(find-eevfherelvideo "10:09" "when people know a few more keys... C-w and M-w")
(find-eevfherelhsubs "10:22" "that correspond to Cut, Copy, and Paste")
(find-eevfherelvideo "10:22" "that correspond to Cut, Copy, and Paste")
5. Pointing to anchors
We saw in
(find-eev-quick-intro "8. Anchors")
(find-eev-quick-intro "8.1. Introduction: `to'")
(find-eev-quick-intro "8.3. Creating index/section anchor pairs")
(find-eev-quick-intro "8.4. Creating e-script blocks")
how to create anchors and how to point to anchors in the same
file with `to', and we saw briefly in
(find-eev-quick-intro "9.2. Extra arguments to `code-c-d'")
(find-eev-quick-intro "9.2. Extra arguments to `code-c-d'" "to anchors")
that the extra argument `:anchor' in
(code-c-d "eev" ee-eev-source-directory :anchor)
lets us abbreviate the link below, that points to an anchor,
(find-eevfile "eev-blinks.el" "«find-wottb»")
to just this:
(find-eev "eev-blinks.el" "find-wottb")
Let's now see how to put this all together. WARNING: this is an
advanced topic!
If you are in a file that has anchors you can use the key
sequence `M-1 M-h M-w' to copy the "preceding tag" to the kill
ring, and you can you use an `M-h M--' after the `M-h M-y' in the
hyperlinks buffer to shrink the first sexp below to the second
one:
(find-eevfind "eev-blinks.el" "find-wottb")
(find-eev "eev-blinks.el" "find-wottb")
The preceding tag and shrinking are explained here, with
exercises:
(find-anchors-intro "2. Shrinking")
(find-anchors-intro "2. Shrinking" "`M-h M--'")
(find-anchors-intro "3. The preceding tag")
(find-anchors-intro "3. The preceding tag" "`M-1 M-h M-w'")
Here is a diagram of key sequences:
_____________________________________________
| | |
| | |
| target buffer | elinks |
| with anchors | buffer |
| ::::::> |
| M-1 M-h M-w, | M-h M-2, |
| M-h M-3 or | || M-h M-y, |
| M-h M-h | || M-h M--, |
| | || M-h M-w or |
| | || M-w |
| | || |
| |----||----------------|
| | || |
| | \/ notes |
| | buffer |
| | |
| | C-y |
| | |
| | |
|______________________|______________________|
If you are intending to learn this, here is a suggestion: do it
in two steps! Start by learning how to create hyperlinks to
anchors in the directory that has the source files of eev, i.e.,
(find-eevfile "")
and only then do things like
(code-c-d "mnwa" "~/MYNOTESWITHANCHORS/" :anchor)
but with better names, of course, and learn how to create links
to the anchors in the files in that directory.
NOTE: I use this so much that I got used to typing this sequence
of keys VERY quickly,
M-1 M-h M-w
M-h M-h
(<down> several times)
M-h M-2
M-h M-y
M-h M--
M-h M-w
but I don't touch-type, and for me it became natural to hold the
meta key down with my left thumb while I type `M-1hwhh' and
`M-h2hyh-hw' _by moving my hands over the keyboard a lot_...
It would be nice to have a way to do this same series of actions using
keys that are good for touch typists. One possibilty is to use a
hydra; see the experimental code here:
(find-eev "eev-hydras.el")
If you are interested in discussing how to make this more usable,
please get in touch!
[Video links:]
(find-eevfherelvideo "14:18" "4.1. Creating anchors")
(find-eevfherelvideo "15:22" "an index at the beginning of the file")
(find-eevfherelvideo "15:47" "the tutorial also explains ... `M-A'")
(find-eevfherelvideo "16:07" "`M-A' duplicates the line and...")
(find-eevfherelvideo "16:19" "use `M-B' to create something like this block here")
(find-eevfherelvideo "17:02" "4.2. The option :anchor for `code-c-d'")
(find-eevfherelvideo "17:21" "here I have one of the source files")
(find-eevfherelvideo "17:30" "here we have an index")
(find-eevfherelvideo "17:47" "this sexp is equivalent to")
(find-eevfherelvideo "18:12" "not all functions created by code-c-d behave in that way")
(find-eevfherelvideo "18:36" "let me give the short explanation")
(find-eevfherelvideo "18:57" "is a button that defines new functions")
(find-eevfherelvideo "19:04" "and this sexp here shows the code")
(find-eevfherelvideo "19:24" "this defun that defines find-eev")
(find-eevfherelvideo "20:04" "4.3. Shrinking hyperlinks")
(find-eevfherelvideo "20:25" "it has a demo here")
(find-eevfherelvideo "21:07" "4.4. The preceding tag")
(find-eevfherelvideo "21:35" "a variant of `M-h M-w'")
(find-eevfherelvideo "22:06" "it also explains in the echo area what it does")
(find-eevfherelvideo "22:43" "in this example the refined hyperlink is not useful")
(find-eevfherelvideo "22:48" "but here is a demo that makes more sense")