Quick
index
main
eev
eepitch
maths
angg
blogme
dednat6
littlelangs
PURO
(C2,C3,C4,
 λ,ES,
 GA,MD,
 Caepro,
 textos,
 Chapa 1)

emacs
lua
(la)tex
maxima
git
lean4
agda
forth
squeak
icon
tcl
tikz
fvwm
debian
irc
contact

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