How to create hyperlinks to "here" with `find-here-links' (2020)

The index of this video is here.
Its subtitles in Lua are here.
The rest of this page contains a conversion of the subtitles in Lua
to a slightly more readable format.

This video is a tutorial on how to create an elisp hyperlink to "here" - where "here" is the current Emacs buffer, or a position on the current Emacs buffer - and how to copy it to our notes, all this with few keystrokes.

For more on eev see http://anggtwu.net/#eev.

I recorded this video without rehearsing it first, so it's a bit messy... sorry!

00:00

00:01 Hi! My name is Eduardo Ochs,
00:03 this person here...
00:06 and the title of this
00:08 video is: How to create hyperlinks to
00:10 here with find-here-links.
00:12 I'm going to suppose that everyone
00:15 knows what is Emacs and what is eev,
00:16 at least vaguely... and
00:18 one of the main ideas of eev
00:20 is that when you are taking executable
00:23 notes of something that you're doing
00:27 if you find something interesting you
00:29 want to to be able to
00:31 create a hyperlink to that something...
00:34 and usually you're going to be doing
00:37 doing things with Emacs, so if you
00:40 find something interesting this
00:42 is going to be in an Emacs buffer,
00:44 usually...
00:45 and you want to create a hyperlink to
00:47 that Emacs buffer, and to
00:49 some position in that buffer.

1. The tutorials
00:53 Ok, let me start. All the tutorials
00:57 in eev have headers, like these
01:02 headers here... sorry, the header is all
01:05 this thing here,
01:05 but the headers always have a
01:08 part like this, that recommends other
01:10 tutorials...

01:12 we are going to use a bit of this
01:14 tutorial here,
01:16 that is not a real tutorial, it's an index
01:19 of the basic keys of eev and of Emacs,
01:21 with hyperlinks to the documentation...

01:24 we are going to use these two sections in it...
01:30 and we are also going to use a bit of
01:33 this tutorial here, that is
01:36 about `find-here-links', and that explains
01:39 these ideas of switching between
01:41 tasks and notes, creating hyperlinks to
01:45 important things, and so on...
01:49 and we are going to use a bit of this
01:51 tutorial here, about refining hyperlinks.

01:54 Let me start with the two sections of
01:56 the tutorial that is not a real tutorial,
01:59 it's just and index of keys -
02:01 these two sections...
02:01 I've copied them here...

02:04 and we are going to start with the
02:09 beginner's way of creating "hyperlinks to
02:11 here", except that we are going to start with
02:13 this thing here, that is very simple.

02:17 So: there's a sequence of keys, `M-h M-2',
02:19 that just duplicates the current line.
02:23 Remember that the key for help for keys
02:26 in eev is `M-h M-k',
02:30 and if you type `M-h M-k M-h M-2'
02:34 you get a buffer like this,
02:36 with lots of links...

02:38 this one is exactly this link here,
02:41 and one of the other links
02:45 is the link to the source code of this
02:47 function...
02:49 no, sorry, for the description of
02:51 that function...
02:53 and it says that it just duplicates the
02:55 current line without
02:56 any changes to the kill ring.

03:02 There's an example
03:05 in the tutorial (find-refining-intro),
03:08 in the introduction about refining
03:10 hyperlinks...
03:12 and this example has an executable part,
03:15 here... it says "try blablablah" -
03:18 try these two sexps...

03:22 Let's suppose that we execute this.
03:26 The effect of executing this is exactly
03:28 the same as
03:30 marking a region and typing `M-w',
03:33 which copies that to the kill ring...
03:38 and in this line here of the example...
03:43 well, this is a sequence of keys and this
03:45 sexp executes that sequence of keys...
03:48 and what it does is: it goes down,
03:52 it duplicates this line, and then it runs
03:55 `M-h M-y', which is something
03:57 that I'm going to explain soon.

04:00 So: `M-h M-2' just duplicates
04:02 the current line... you can use it
04:04 with the cursor at any point,
04:07 and it does not change the top of the
04:09 kill ring... it is still "Tools for",
04:13 that we have killed 30 seconds ago.

04:19 So, the first most basic key is this one,
04:26 and I've demonstrated - without explaining -
04:29 what is this other key, that is going
04:32 to be very important later...
04:34 but it's not something that beginners
04:35 learn in the first 30 minutes, say.

2. The beginner's way
2.1. The 3-window setting - and going back from it
04:40 When I explain these things to
04:42 beginners
04:43 I usually start by explaining things in
04:46 a three-window setting...
04:49 I'm going to use this figure here to
04:51 explain what these things are,
04:52 and let me just tell a story about
04:56 what I mean by "beginners".

04:58 I sometimes teach Emacs to people that
05:02 have never tried Emacs before,
05:04 and I've had an opportunity to teach
05:06 a mini-course on LaTeX in which I could
05:10 choose the editor that I would force the
05:12 students to use...

05:14 and I wanted to use Emacs,
05:19 and my excuse for using Emacs was that
05:23 if you are going to learn LaTeX then
05:25 most of the time when you want to learn
05:27 how to do something, and you look
05:28 at the internet how to do that something...
05:31 the answer is usually going to be, like,
05:34 uh, use the package such and such...

05:38 and the easiest way of using these things
05:42 and to learn how to use all these
05:44 packages is to install a full distribution
05:47 of TeX and LaTeX in your system...
05:50 and then you're going to get about 4000
05:53 packages,
05:54 and then you're going to need a way
05:56 to navigate by these packages,
05:59 look at their documentation, look at
06:00 the examples, try the examples, and so on...

06:03 and Emacs and eev are the perfect thing for
06:06 that. So, I've had the opportunity to give
06:10 this course, and so I taught Emacs and eev
06:14 to, say 10 people, and I got a lot of
06:16 feedback... and it was very useful to me -
06:19 and they liked it!

06:23 So... this is one trick that is mainly
06:27 meant for people that don't know
06:29 the keys of Emacs -
06:31 when we don't want to force them
06:33 to memorize many things at once.

06:38 I will need to switch to a smaller font...
06:40
06:47 I'm going to explain these two sequences
06:49 of keys: `M-h M-3' switches to a certain
06:51 configuration with three windows,
06:54 and `M-h M-1' goes back to the configuration
06:59 that we had before.

07:01 If I type `M-h M-3' here - now -
07:03 I get this configuration with three
07:06 windows, in which
07:08 this thing here is the target buffer,
07:11 this thing here is the Emacs hyperlinks buffer,
07:15 and this thing here is the buffer with notes...
07:21 and if I type `M-h M-1' I go back to the
07:26 original window configuration, and the
07:29 original window configuration can be
07:31 anything... for example,
07:33 if I run this sexp here I get this
07:36 very weird window configuration, and if I
07:39 type `M-h M-3' I get this one,
07:42 and if I type `M-h M-1'
07:45 I go back to my weird configuration
07:48 that I had before.

07:52 So, in the window configuration with
07:55 three windows
07:59 if I want to create a hyperlink to "here" -
08:02 to this file, where is the script for this video...
08:06 well, at this moment
08:10 I want to create a hyperlink to "here",
08:13 but when I create this configuration with three
08:16 windows it is no longer practical to refer
08:19 to this thing as "here",
08:20 because sometimes my cursor is
08:24 going to be here, sometimes here...
08:26 so I need another terminology.

08:28 This thing becomes the "target
08:32 buffer", and I want to
08:33 to create a hyperlink that points to
08:37 this "target buffer", and copy it to my
08:40 "notes".

08:42 So this is a hyperlink that points to
08:45 that "target buffer" here... and...
08:52 I can copy it to my "notes".

2.2. Copying one link
08:56 But let me explain how I teach this
08:58 to beginners.
09:03 Besides teaching them how to use `M-h M-3'
09:06 and `M-h M-1',
09:08 I also teach them how to use `M-h M-w',
09:11 which is copy the current line...
09:15 `ee-copy-this-line-to-the-kill-ring'.

09:17 So, my cursor is here, and if I type `M-h M-w'
09:23 I get this message in the echo area...
09:26 "Copied the current line to the kill ring -
09:28 use C-y to paste"...

09:31 and I can go to my buffer with notes,
09:34 I can copy this thing with C-y,
09:36 and now I can return to the previous
09:40 configuration.

09:44 So, this is what I teach to the students
09:46 in the first moment,
09:48 when I give these mini-courses, or when
09:50 I'm teaching Emacs to
09:52 someone who have never used Emacs before...
09:54 I mean, Emacs and eev, sorry.

09:56 We get the target buffer,
10:00 we copy the right line to the
10:03 kill ring with `M-h M-w',
10:06 and then we paste that line with `C-y'.

10:09 When people know a few more keys
10:12 they can also use `C-w' or `M-w',
10:15 and remember that in Emacs the terminology
10:18 is very different
10:19 from cut, copy, and paste...
10:22 and here are hyperlinks to the
10:25 keys in Emacs that corresponds to cut,
10:27 copy, and paste.

2.3. Duplicating and refining
10:31 Ok, next step.
10:35 I've mentioned briefly that we can use
10:37 `M-h M-y' to refine a hyperlink
10:39 in a certain way.
10:42 We saw this tutorial here,
10:43 in which I copied this "Tools for"
10:46 to the kill ring,
10:50 and then with this sexp here I
10:53 duplicated this line, and then I refined
10:56 it in a certain way
10:58 by adding the top of the kill ring as a
11:02 string at the end of the sexp...

11:05 So this is what we are going to do now.
11:13 Just let me show an example
11:16 without that much clutter in the screen...
11:19 suppose that I've
11:20 copied this thing to the kill ring with `M-w',
11:23 then I can duplicate this line and use
11:26 `M-h M-y'.

11:30 So, at this stage what we are going to do
11:33 is that we are going to you to switch to the
11:36 three-window setting with `M-h M-3'...
11:39 and then I'm going to find the right
11:41 hyperlink, I'm going to duplicate it,
11:43 I'm going to refine it by adding the string
11:45 at the end of the sexp...
11:48 i'm going to copy the two lines to the
11:52 kill ring, and I'm going to copy
11:54 them to the "notes" buffer.

11:56 Let me demonstrate this. Suppose that I
11:59 want to create a hyperlink to this
12:01 string here, so `M-h M-3'...
12:05 then this is the hyperlink that I want to use,
12:10 but I'm going to duplicate it,
12:12 refine it, and then I'm going to copy
12:14 these two lines to my notes...

12:16 so, this hyperlink here
12:20 points exactly to this string in this
12:24 file, with the script for my video...

12:27 Let me go back to the previous window
12:29 setting, and let me use a bigger font again...

3. Using a single window
12:36 Obviously all these things can be done
12:38 using a single window, I'm not doing
12:41 that just because it's simpler to explain
12:43 that to newcomers by using
12:45 the three window setting...

12:49 but I can just type `M-h M-h' to
12:51 get a buffer with hyperlinks,
13:00 I can duplicate this line,
13:02 I can refine this line,
13:04 I can copy these two lines
13:06 to the kill ring,
13:07 I can go to my buffer with notes,
13:10 and I can copy these to my notes...

13:12 and then suppose that I delete
13:15 the links that are not very relevant...

13:21 and I can go back
13:26 to the buffer where I was before -
13:29 usually by using `M-K' twice.

13:33 `M-K' is similar to `kill-this-buffer',
13:36 but it doesn't kill the buffer,
13:38 it just buries the buffer
13:40 at the bottom of the pile of buffers
13:43 associated to a certain window.

13:48 This hyperlink here is just to
13:51 remember me that I copied this diagram
13:54 from this tutorial, in this position...

4. Advanced usage: anchors
14:00 Ok, next step.
14:03 This is something very advanced
14:04 that only makes sense to people that
14:07 have been using eev for at least some hours,
14:10 and they have created their own anchors,
14:13 and they want to create hyperlinks to
14:16 those anchors.

4.1. Creating anchors
14:18 Let me start by
14:22 showing the part of the tutorial that
14:24 explains what anchors are.
14:26 There's this section here that explains
14:28 that this thing here
14:30 is what we are going to call an "anchor"...
14:33 and this string inside the green
14:38 double angle brackets is what we call a "tag".

14:43 And when we run a sexp like this
14:47 this sexp searches for this tag wrapped
14:50 in the green double angle brackets...
14:54 so this sexp here
14:57 searches for this string,
15:00 this sexp here searches for this string,
15:05 this sexp - sorry, this sexp here
15:08 searches for this string here,
15:09 and this sexp here
15:12 searches for this string here...

15:15 so if I execute `M-e' several times here
15:18 I get this behavior, which is not very
15:22 useful...
15:23 but in many cases I have an index in the
15:25 beginning of the file,
15:26 which is full of lines that are
15:30 of this form: a dot, an anchor with a dot,
15:33 and then a tag pointing to this anchor here,
15:36 so these two anchors
15:39 point to one another...

15:40 if I type `M-e' in each one
15:44 I go to the other one,
15:48 and the tutorial also explains how to
15:50 create these pairs, made of an
15:55 an index and a section...
15:58 a "section anchor" - well, whatever...
16:02 it's by using `M-A'. If I use `M-A'...
16:06 sorry, if I use `M-A' in this line here
16:10 it duplicates the line and it converts
16:12 this line into this thing here...

16:15 and it also explains how to use `M-B',
16:22 that creates something like this
16:25 block here...

16:29 and my files with notes are full of blocks
16:33 formatted in this way, but I move this line
16:35 to the beginning of the file -
16:37 to the index.

16:46 So, again, this part of the tutorial
16:48 explains what anchors are and how to
16:50 create anchors...
16:52 but it only explains how to use `to',
16:56 which is this thing here.

4.2. The option :anchor for `code-c-d'
17:02 But let's see a more realistic example.
17:04 most of the source files in eev have
17:07 anchors.
17:09 Here's an example... oops, sorry -
17:12 here's an example.
17:18 Here I have the one of the source files...
17:22 that defines "many hyperlinks to
17:24 temporary buffers generated by templates".

17:27 It's called eev-tlinks.el, and
17:30 here we have an index...
17:34 and each line of this index points
17:37 to the corresponding definition...

17:47 So, this sexp here is equivalent to this
17:50 sexp here, and note that when I've reduced
17:54 the name by dropping this "file"
17:55 at the end of the function...
17:59 this reduced sexp points to an anchor,

18:03 So, if I execute this it searches
18:06 for this string, wrapped as an anchor.

18:12 Not all functions created by `code-c-d'
18:15 behave in that way - only the functions
18:18 that have this extra argument here,
18:20 `:anchor'... and one of the tutorials
18:22 explains how this thing...
18:26 how this extra argument works.
18:28 I'm not going to explain this in details,
18:31 but the thing is that if we execute...
18:34 if you... ok, let me give the short
18:36 explanation.

18:38 If we execute this then... sorry -
18:42 then this function is going to produce a
18:46 certain string, and then is going to
18:49 interpret that string as Lisp code,
18:50 and this string is a series of
18:54 definition of functions.

18:57 So this sexp here is like a button
19:00 that defines several new functions...
19:04 and this sexp here shows the code that
19:07 this sexp produces, but this one does not
19:10 execute the code - it just shows the code.

19:13 The code is here. So, we can see that it
19:16 has a `setq', and then a series of
19:21 `defun's that define functions, and
19:24 it also has this `defun' at the end,
19:27 that defines `find-eev', without...
19:33 it's not `find-eevfile', it's just
19:35 `find-eev'...

19:37 and `find-eev' without the suffix "file"
19:41 at the end uses another function,
19:44 called `find-anchor',
19:47 to point to this file here
19:52 in the position specified by the
19:54 pos-spec-list.

19:57 Ok, so this explains how the function
20:00 `find-eev' was defined,

4.3. Shrinking hyperlinks
20:04 and this tutorial also explains how to
20:06 shrink this hyperlink to something like
20:09 this hyperlink here...

20:11 It explains what is my meaning
20:16 of the term "shrinking"
20:18 in the context of eev, and it has a demo
20:24 here...

20:27 it explains that we can shrink the
20:29 hyperlink at the current line
20:30 with `M-h M--'...
20:34 if we execute `M-h M--' in this line
20:38 here it shrinks it in a certain way...

20:43 and if we type `M-h M--' in this line
20:49 here it does nothing.

20:51 So, here it shrinks - it deletes the
20:54 "file", and it reformats the rest...
20:57 and here it does nothing... and whatever.

4.4. The preceding tag
21:07 And we also have an advanced key that
21:10 lets us copy to the kill ring
21:12 the preceding tag.

21:14 Let me explain what is that.
21:18 Remember that `M-h M-w' copies
21:21 the current line to the kill ring...
21:24 remember that after copying it to the
21:26 key ring we can insert it with C-y...

21:34 There's a variant of `M-h M-w'
21:39 that works like this. When we invoke `M-h M-w'
21:42 with a numeric argument - usually as this:
21:46 `M-1 M-h M-w' - then
21:49 instead of copying the current line it
21:51 just copies the the tag
21:53 of the previous anchor, so if the cursor
21:57 is here the previous anchor is here...
22:00 the preceding anchor is this one, and the
22:02 preceding tag is this one...

22:03 and it also explains in the echo area
22:08 what it does. So let's try it here...
22:11 `M-1 M-h M-w'... ta-da!
22:15 It flashes this string for a fraction of
22:18 a second
22:19 and it says "Copied blablah..." it says
22:22 this string here... "to the kill ring."

22:24 If I type `C-y' here
22:28 I see copies of that hyperlink...
22:32 of that string... and if I use `M-h M-y'
22:36 here I refine this hyperlink to include
22:40 this thing here.

22:44 In this example the refined hyperlink
22:45 is not very useful,
22:48 but here is a demo that makes more sense.

22:55 Let me go back to this source file here.
22:58 If I type `M-1 M-h M-w' here then it
23:02 copies this string here to the kill ring.

23:07 Let me switch to the three-window
23:09 setting, and to a smaller font...

23:14 I'm going to take this hyperlink here,
23:18 I'm going to duplicate this line,
23:21 refine it,
23:22 and then shrink it,
23:25 and then this is a hyperlink
23:27 that points to this file here,
23:32 eev-tlinks.el,
23:35 to this anchor, with this tag...

23:39 so if I execute this sexp here
23:44 this thing opens eev-tlinks.el
23:47 and goes to this anchor.

23:52 Let me go back to the
23:56 one window setting, let me go back...
24:01 yeah, yeah, that's it! That's all that
24:04 I wanted to show in this video.
24:05 So that's it! Bye! =)

24:07