(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-eev2019video "1:08" "a string to search for") (find-eev2020video "2:25" "variants that were better behaved") (find-eev2020video "2:36" "in the same window") (find-eev2020video "2:53" "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 an new argument. [Video links:] (find-eevfherelvideo "10:30" "2.3. Duplicating and refining") (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-eevfherelvideo "12:35" "3. Using a single window") (find-eevfherelvideo "13:19" "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-eevfherelvideo "8:56" "2.2. Copying one link") (find-eevfherelvideo "10:10" "when people know a few more keys... C-w and M-w") (find-eevfherelvideo "10:21" "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")