(Re)generate: (find-saving-links-intro)
Source code:  (find-efunction 'find-saving-links-intro)
More intros:  (find-eev-quick-intro)
              (find-here-links-intro)
              (find-refining-intro)
              (find-eev-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.


"Taking executable notes" consists mainly on:
  a. recording commands sent to shell-like programs,
  b. saving elisp hyperlinks to everything interesting
     that we find.
"(Generating and) saving links" is the harder half.
This intro is about how to do that fluently.
It is based on ideas that I tested in this workshop:
  http://angg.twu.net/2021-workshop.html

THIS IS A WORK IN PROGRESS AND IS CURRENTLY A MESS.
This was split from:
  (find-eev-exercises-intro)
Pre-requisites:
  (find-here-links-intro)
  (find-refining-intro)




1. Reading diagrams aloud

I will use 2D diagrams to represent sequences of actions. In beginning of this tutorial these diagrams will have lots of details, but they will become progressively more and more streamlined; in the last exercises of this intro we will work with diagrams in which only the details that are very hard to infer are written down explicitly.

1.1. Key sequences

I will suppose that you are familiar with the first few sequences of keys below, and that you are trying to become familiar with the other ones. The pronounciations at the right are the ones that we will use in the text of this intro and in its videos. Pronounciations C-w cut M-w copy, or copy into the kill ring C-y paste, or copy from the kill ring, or yank C-x 0 delete window C-x 1 one window M-k kill buffer M-K bury buffer M-j meta-jay, or list of jumps M-1j jump to notes M-2j jump to emacs keys M-5j jump to main tutorial M-21j show notes at the right M-31j jump to notes at the right M-h3 find here links beginner M-h1 go back (to the previous window configuration) M-hh find here links M-hk find key links M-hf find function links M-he find extra links M-h2 duplicate M-hy refine, or yank into pos-spec M-h- shrink M-hw copy line M-1hw copy last tag Exercise: all the key sequences above are mentioned here: (find-emacs-keys-intro) check that their pronounciations above make sense. Find the link to the documentation of each key sequence, follow it, and read the explanation. A few of the explanations have exercises that show in practice how those key sequences work - do these exercises.

1.2. Windows and buffer names

We will use two ways to explain what our abbreviations for buffer names, like [EX], [EH], and [N], mean: pronounciations and sexps. For example: [EX] exercises (find-saving-links-intro) [HL] here-links (find-here-links) [N] notes (find-fline "~/TODO") A diagram like this _________________ ____________ | | | | | | | [HL] | | | | [EX] | | | [EX] | | |________| ---> | | | | | | | | | [N] | | | | | | | | |________|________| |____________| We mean that we started in a window configuration with three windows, with [EX] at the left half, [HR] at the upper right, and [N] at the lower right, and then we switched to a window configuration with a single window displaying [EX].

1.3. Adding keys

Look at this diagram: _________________ ____________ | | | | | | [EX] | [HL] | | [EX] | | M-w | M-h2 | | | | | M-hy | | | | | M-w | M-h1 | | | |___::___| ---> | | | | \/ | | | | | | | | | | [N] | | | | | C-y | | | |________|________| |____________| We added key sequences to the diagram of the previous section, and we did that in a way that lets us deduce from the diagram in which buffer each key sequence was typed, and in which order. For me these diagrams become easy to understand and to remember if I translate mentally each key sequence to its pronounciation - like this: In the buffer with exercises, copy a string to the kill ring; (1) In the buffer with here-links, duplicate, refine, copy; (2) go to the buffer with notes, and paste; (3) go back to the previous window configuration. This is somewhat similar to reading a score sheet. In the steps (1), (2), and (3) some information hard to put in words was omitted from the pronounciation. In (1) we copy to the kill ring exactly the string that will be used in the refining step; in (2) we copy to the kill ring two links, one "original" and one that it is refined version; in the step (3) we copy these two links to the right place in our notes, but the pronounciation doesn't say where.

2. The base cases

All the methods to create and save elisp hyperlinks that we will see can be regarded as variants of the base cases 1, 2, and 3. The base cases 1, 2, and 3 all follow this pattern: _______________ _____________________ ________________ | | | | | | | | | | ::> elinks | | | | | | | buffer | | | | target | M-h3 | target |____::____| M-h1 | target | | buffer | ---> | buffer | \/ | ---> | buffer | | | | | notes | | | | | | | buffer | | | |_______________| |__________|__________| |________________| They only use two key sequences that change the window configuration - M-h3 - find here links beginner M-h1 - go back (to the previous window configuration) and they differ in the steps for editing the link in the elinks buffer before copying it to the notes buffer. In the base case 1: we do no editing, we just copy one link to the notes buffer, In the base case 2: we duplicate and refine, and we copy two links to the notes buffer, In the base case 3: we duplicate, refine, and shrink, and we copy two links to the notes buffer. The base cases 2 and 3 require us to copy to the kill ring a string that will be used for the refining. The operation "copy a string from the target buffer to the kill ring" consists of: In the base case 1: nothing In the base case 2: copy (with M-w) In the base case 3: copy last tag (with M-1hw) Let's see each one of the three base cases in detail and do one exercise for each one.

2.1. The base case 1

The base case 1 is just this: _____________ _____________________ _____________ | | | | | | | | [T] | | [T] ::> [EH] | | [T] | | | | | M-hw | | | | | M-h3 | |____::____| M-h1 | | | | ---> | | \/ | ---> | | | | | | [N] | | | | | | | C-y | | | |_____________| |__________|__________| |_____________| In this case the arrow "::>" means just "switch to the buffer with elisp hyperlinks". In the [EH] buffer we copy the line with the hyperlink that points to the target to the kill ring with `M-hw' ("copy this line"), and then we switch to the notes buffer and we paste the hyperlink with `C-y' ("yank"). If we treat the steps `M-h3', `M-hw' ("copy this line"), `C-y' ("yank"), and `M-h1' as "obvious" we can omit them from the diagram, and we get this: _____________ _____________________ _____________ | | | | | | | | [T] | | [T] ::> [EH] | | [T] | | | | | | | | | | | |____::____| | | | | ---> | | \/ | ---> | | | | | | [N] | | | | | | | | | | |_____________| |__________|__________| |_____________| One of my reasons for preferring this diagram with less information is that now the step that means "copy the hyperlink to the kill ring" does not say how to do that - and we can use either `M-hw' or a more standard way to copy a line to the kill ring, like `C-SPC <down> M-w'. Exercise 2.1a: Treat this intro as the target buffer. Use the method above to generate a link to this target and to copy it to your notes. Let me introduce another abbreviation that I will use. In the exercises 2.1b, 2.2b, and 2.2c below we will use a target buffer that is different from the buffer with the exercises, and instead of representing what happens in the exercise with five window configurations, as ________ _______ ____________ _______ ________ | | | | | | | | | | | | [EX] | -> | [T] | -> | [T]::>[EH] | -> | [T] | -> | [EX] | | | | | | |__::__| | | | | | | | | | | \/ | | | | | | | | | | | [N] | | | | | |________| |_______| |_____|______| |_______| |________| I will omit the second and the fourth window configurations and draw something equivalent to this: ________ ____________ ________ | | | | | | | | [EX] | --------------> | [T]::>[EH] | --------------> | [EX] | | | | |__::__| | | | | | | \/ | | | | | | | [N] | | | |________| |_____|______| |________| or, even worse, I will simply expect that people will be able to take the diagram of the previous exercise, i.e., of the exercises 2.1a, 2.2a, and 2.3a, that are like this, _______ ____________ _______ | | | | | | | | [T] | -> | [T]::>[EH] | -> | [T] | | | | |__::__| | | | | | | \/ | | | | | | | [N] | | | |_______| |_____|______| |_______| and convert it mentally to a diagram with "[EX]" in the extremities. So: Exercise 2.1b: Follow this link: (find-enode "Setting Mark") it will open an info page. Treat that info page as the "target" and use the method above to create a link to that target and to copy it to your notes. After that come back to this intro using `M-K*' - i.e., "bury buffer" as many times as needed - or using any other method. Note that this exercise starts and ends with a window configuraton in which only the buffer "[EX]" is shown, so it uses implicitly the abbreviation that I've just described. [Video links:] (find-2021workshop1video "0:22" "The base case 1 is described here") (find-2021workshop1video "0:52" "The instructions are here")

2.2. The base case 2

The base case 2 is similar to the base case 1 but here we duplicate and refine the hyperlink. Its diagram is: _____________ _____________________ _____________ | | | | | | | | [T] | | [T] ::> [EH] | | [T] | | | | | M-h2 | | | | | | | M-hy | | | | | | |____::____| | | | | ---> | | \/ | ---> | | | | | | [N] | | | | | | | | | | |_____________| |__________|__________| |_____________| Here many obvious (?!?!) steps were omitted. Here's how to read it aloud including the omitted steps: find here links beginner In the target buffer: copy a string to the kill ring In the elisp hyperlinks buffer: find the hyperlink to the target duplicate refine copy the original and the refined links to the kill ring In the notes buffer: paste go back to the previous window configuration Exercise 2.2a: Treat this intro as the target buffer and the "(?!?!)" as the string that will be used in the refinement. Use the method above to generate two links - one to this intro and one to the first occurrence of "(?!?!)" in it - and copy these two links to your notes. Exercise 2.2b: Follow this link: (find-enode "Setting Mark" "C-x C-x") it will open an info page and search for the first occurence of "C-x C-x" in it. Treat that info page as the "target" and use the method above to create: 1. a link to that target 2. a refinement of that link that points to the "C-x C-x" then copy this pair of links to your notes. After that come back to this intro using `M-K*' - i.e., "bury buffer" as many times as needed - or using any other method. Note that here the initial and the final window configurations are just "[EX]", so we are using implicitly the abbreviation that omits some window configurations that was explained before the exercise 2.1b. [Video links:] (find-2021workshop1video "1:24" "The base case 2") (find-2021workshop1video "1:39" "What I need to do is slightly") (find-2021workshop1video "1:55" "This is not yet the link that I want")

2.3. The base case 3

In the base case 2 we edited the hyperlink by doing duplicate and refine; in the base case 3 we will will edit it by doing duplicate, refine, _and shrink_. Very few other sections of this intro depend on this one - so you may skip this. The base case 3 will only make sense to people who understand: anchors, short hyperlinks to anchors, using `M-1hw' to copy the preceding tag to the kill ring, and using `M--' to shrink a hyperlink to make it point to an anchor. You can learn these extra prerequisites here: (find-eev-quick-intro "8. Anchors") (find-eev-quick-intro "8.1. Introduction: `to'") (find-eev-quick-intro "8.5. Hyperlinks to anchors in other files") (find-eev-quick-intro "9. Shorter hyperlinks") (find-eev-quick-intro "9.1. `code-c-d'") (find-eev-quick-intro "9.2. Extra arguments to `code-c-d'") (find-eev-quick-intro "9.2. Extra arguments to `code-c-d'" ":anchor") (find-eev-quick-intro "9.2. Extra arguments to `code-c-d'" ":anchor" "3)") (find-anchors-intro "2. Shrinking") (find-anchors-intro "3. The preceding tag") Also, the base case 3 will only _look useful_ to people who can imagine using anchors in their own files. The main techniques for creating anchors are described in the two first links below, and the other three links point to an experimental feature of eev that I use to move the first half of an index/section pair to the index section of a file with few keystrokes. (find-eev-quick-intro "8.3. Creating index/section anchor pairs") (find-eev-quick-intro "8.4. Creating e-script blocks") (find-refining-intro "5. Pointing to anchors") (find-refining-intro "5. Pointing to anchors" "but I don't touch-type") (find-eev "eev-hydras.el") The diagram for the base case 3 is this one. Note - ta-da! - that we are introducing another abbreviation: we are omitting the window settings in the extremities. _____________________ | | | | [T] ::> [EH] | | M-1hw | M-h2 | | | M-hy | ---> | | M-h- | ---> | |____::____| | | \/ | | | [N] | | | | |__________|__________| One way to pronounce that diagram is: go to the target buffer find here links beginner in the target buffer: copy last tag in the elisp hyperlinks buffer: duplicate refine shrink copy the original and the refined links to the kill ring In the notes buffer: paste go back to the original window configuration Exercise 2.3a: Omitted. Try to understand why! =) Exercise 2.3b: This hyperlink (find-eev "eev-videolinks.el" "ee-1stclassvideos-field") points to an anchor in one of the source files of eev. Use it to go to that anchor, and pretend that you arrived there by accident, found that anchor interesting, and decided that you had to put a link to it in your notes. Use the method above to create 1. a link to that file 2. a link to that anchor in that file and then copy the two links to your notes. ***The rest will be rewritten*** [Video links:] (find-2021workshop1video "0:22" "The base case 1 is described here") (find-2021workshop1video "0:52" "The instructions are here") [Video links:] (find-2021workshop1video "1:24" "The base case 2") (find-2021workshop1video "1:39" "What I need to do is slightly") (find-2021workshop1video "1:55" "This is not yet the link that I want")

3. Copy from left to right

3.1. Two basic exercises

In the diagrams below the names of the buffers are abbreviated: [EX] - (find-eev-exercises-intro) [J] - (find-eejumps) [N] - notes, i.e., (find-fline "~/TODO") [EK] - (find-emacs-keys-intro) ________ _______ ______________ ________ | | | | | | | | | | [EX] | M-j | [J] | M-21j | [J] | [N] | C-x 1 M-K* | [EX] | | | ----> | | -----> | M-w ::> C-y | ----------> | | |________| |_______| |_______|______| |________| ________ _______ ______________ ________ | | | | | | | | | | [EX] | M-2j | [EK] | M-21j | [EK] | [N] | C-x 1 M-K* | [EX] | | | ----> | | -----> | M-w ::> C-y | ----------> | | |________| |_______| |_______|______| |________| `M-21j' is `M-2 M-1 M-j' written in an abbreviated form - mnemonic: "hold the meta key, type 21j, lift meta" - and `M-K*' means "type M-K as many times as needed". Watch this video and try to reproduce what happens in it: (find-2021workshop5video "0:00")

3.2. `find-extra-file-links'

Here you will need to understand `code-c-d' and `find-extra-file-links'. See: (find-eev-quick-intro "9. Shorter hyperlinks") (find-eev-quick-intro "9.1. `code-c-d'") (find-audiovideo-intro "4.1. `find-extra-file-links'") The diagram will be this one: ________ _______ _______ ______________ ________ | | | | | | | | | | | | [EX] | | [D] | M-he | [EH] | M-21j | [EH] | [N] | C-x 1 M-K* | [EX] | | | --> | | ----> | | -----> | M-w ::> C-y | ----------> | | |________| |_______| |_______| |_______|______| |________| Where [D] is a dired buffer. Watch this video and try to reproduce what happens in it: (find-2021workshop6video "0:00") Do this twice. In the first time you should create elisp hyperlinks pointing to this directory and this file, (find-efile "play/") (find-efile "play/" "life.el") and in the second time you should create elisp hyperlinks to a directory and a file that you find interesting.

3.3. Invisible text

Run this sexp: (eek "3*<up> C-a C-SPC C-e") and then use `M-w' to copy the region to the kill ring and `M-hy' to yank it into this sexp: (insert "\n") Instead of getting the first sexp below you will get the second one: (insert "\n" "2.3. Invisible text") (insert "\n" "2.3. Invisible text\n-------------------") That's because the title line contains some invisible text, and the `M-hy' clears all the properties of the text that it inserts, including the invisibility property. Invisible text is explained here: (find-elnode "Invisible Text") When you type `C-e' on the title of a section of an "intro" the `C-e' takes you to the right of the line _after_ the invisible text. If you type `<left> <right>' there this moves the point to a position before the invisible text. So, if you want to copy the title of a section of an intro to use in a refinement, use C-a C-SPC C-e <left> <right> M-w instead of: C-a C-SPC C-e M-w Exercise: create a pair of elisp hyperlinks, the first one pointing to this intro and the second pointing to this section, and copy the pair to your notes. You'll have to watch the video to understand some tricky points and you will have to follow the diagram below. ________ _______ _______________ ________ | | | | | | | | | | [EX] | M-hh | [EH] | M-21j | [EH] | [N] | C-x 1 M-K* | [EX] | | M-w | ----> | | -----> | M-h2 ::> C-y | ----------> | | | | | | | M-hy | | | | |________| |_______| |________|______| |________| [Video links:] (find-2021workshop4video "0:00")

3.3. Copy from `find-ekey-links'

1. use M-5j to go to (find-eev-quick-intro) - a.k.a. "the main tutorial", 2. go to the section 4.2 in that main tutorial, and find where it says "Try the eek links below", 3. run the eek link that says: (eek "M-h M-k C-s ;; isearch-forward") 4. it should open a temporary buffer whose buffer name is "*Elisp hyperlinks*". Find the two lines in that buffer that say: # (Info-goto-emacs-command-node 'isearch-forward) # (find-enode "Command Index" "* isearch-forward:") 5. mark and copy those lines, 6. use `M-21j' or `M-31j' to open your notes buffer in the right window, 7. paste those lines to your notes buffer. In a diagram: __________ __________ ________________ | | | | | | | M-5j | [MT] | M-e | [EH] | M-21j | [EH] | [N] | -----> | sec. 4.2 | ----> | | ---------> | ::> | | | | | or M-31j | | | |__________| |__________| |________|_______|

3.4. A variant

Someone who knows how to use `M-h M-k' (`find-ekey-links') and who doesn't need to split windows can do essentially the same as we did in the previous section with fewer keystrokes. Let's see how. Exercise: 1. Type `M-hk C-s' to open a temporary buffer with elisp hyperlinks on the key `C-s', 2. mark, and copy with `M-w', the lines that say: # (Info-goto-emacs-command-node 'isearch-forward) # (find-enode "Command Index" "* isearch-forward:") 3. use `M-1j' to go to your notes buffer, 4. paste those lines to your notes buffer with `C-y'. In a diagram: ___________ ___________ | | | | M-hk C-s | [EH] | M-1j | [N] | ---------> | mark, M-w | -----> | C-y | | | | | |___________| |___________|

4. A two-window setting (hard)

Exercise: copy the diagram below to your notes, ____________ _____________ ____________ _____________ | | | | | | | | | | | | | [EX] | [T] | M-hh | [EX] | [EH] | M-21j | [EH] | [N] | M-K* | [EH] | [EX] | | | M-w | ----> | | M-h2 | -----> | | C-y | ---> | | | | | | | | M-hy | | | | | | | | | | | | M-w | | | | | | | |______|_____| |______|______| |______|_____| |______|______| then come back here and type `C-x 1 C-x 3' to split the window. In the window at the right, go this directory, (find-efile "") find the subdirectory "play", enter it, find the file "life.el", and inside the file "life.el" find the line that starts with this string, with a space at its end: "(defun life " Then follow the instructions in the diagram above to create a link to the file "life.el". Refine that link to make it point to the first occurrence of the string "(defun life " inside the file "life.el", and copy the original link and the refined one to your notes. [Video links:] (find-2021workshop2video "0:00")

1. Saving interesting links

The documentation of eev says at several places that people should "save all interesting links to their notes". It is easier to learn that if we split it into these tasks: a. save links to your notes b. test these links c. mark the links that you don't understand d. undestand what each link does (with M-h M-f) e. recognize which links are interesting