Bidirectional links with eev (@ EmacsConf 2022)

I submitted two proposals for 5-minute talks to the EmacsConf2022.
This one corresponds to this file: eev-kla.el. Its EmacsConf page is here.
My other submission is here - it corresponds to eev-rstdoc.el.
The intro/tutorial for this feature is here: (find-kla-intro).
Links to my older presentations at EmacsConfs: 2021, 2020, 2019.
For a screenshot and subtitles, go here.

Start by this: in 2023 this became much simpler to use!
The simpler feature is explained here: (find-kl-here-intro).

Title: Bidirectional links with eev
Intended duration: 5 minutes
Abstract:

Consider the two sexps below:

(code-c-d "foobar" "/tmp/foo/bar/" :anchor) (code-c-d "fb" "/tmp/foo/bar/" :anchor)

Each one of them defines several "short hyperlink" functions. After running them the three sexps below are roughly equivalent:

(find-file "/tmp/foo/bar/plic.txt") (find-foobarfile "plic.txt") (find-fbfile "plic.txt")

The "code-c-d"s above also define functions with even shorter names -- "find-foobar" and "find-fb" - that point to "anchors" in files in the directory /tmp/foo/bar/. The three sexps below are roughly equivalent -

(find-fline "/tmp/foo/bar/plic.txt" "«bletch»") (find-foobar "plic.txt" "bletch") (find-fb "plic.txt" "bletch")

Until feb/2022 the only way that I had to produce these hyperlinks to anchors quickly required a LOT of muscle memory... I had to type this,

M-1 M-h M-w M-h M-h 9*<down> M-h M-2 M-h M-y M-h M-- M-h M-w M-k

where the number of "<down>"s depended on whether I preferred find-foobar of find-fb - i.e., of on what is my preferred "code" for the "directory" /tmp/foo/bar/; either "foobar" or "fb".

In this presentation I will show a much better way to generate short hyperlinks to anchors and push these short hyperlinks to the kill ring, and how I use that to create bidirectional hyperlinks between my notes on a language $LANGUAGE and programs written in that language.

For more info see the tutorial in eev-kla.el.

To watch the video on youtube, click on the screenshot below. That links points to the copy that is on my channel; the copy at the EmacsConf channel is here.

Note that youtube always converts my videos to a format that is blurry at some points. You can download a local copy of the original video, with subtitles, with the two "wget"s below:

# See:  http://anggtwu.net/eev-videos.html
#       http://anggtwu.net/eev-videos.html#mpv-keys
# Play: (find-eev2022klavideo "0:00")
# Info: (find-1stclassvideo-links "eev2022kla")
# Subs: (find-1stclassvideolsubs  "eev2022kla")

wget -nc http://anggtwu.net/eev-videos/emacsconf2022-kla.mp4
wget -N  http://anggtwu.net/eev-videos/emacsconf2022-kla.vtt
mpv --fs --osd-level=2 emacsconf2022-kla.mp4

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

00:00 Hi! My name is Eduardo Ochs. I'm the author
00:04 of an Emacs package called eev, and the name
00:06 of this presentation is: "Bidirectional links
00:09 in eev".
00:10 Let me present things in a weird order,
00:13 starting by the new feature, and then I'm
00:16 going to explain the whole context.

00:20 One of the main features that we are
00:22 going to see here is this function here,
00:24 M-x kla, and kla is a mnemonic for "kill
00:27 Link to Anchor". Let me explain... let me
00:31 demonstrate how it works. This thing here
00:33 with the green angle brackets is an
00:36 anchor, this thing between the green
00:40 angle brackets is a tag of an
00:42 anchor, and if I type M-x kla here
00:46 it highlights this tag for a second and
00:49 it says "Copied to the kill ring: blah
00:52 blah blah..." and this thing here is a link.
00:54 I can insert the link here, I
00:57 can insert the link in my notes...
01:00 and if I execute this thing this link
01:03 here it goes to this anchor in this file.
01:10 If you have a recent version of eev
01:12 installed then trying this feature
01:13 should be very easy...
01:15 you just need to open the this file here,
01:18 in which everything is defined, and then
01:21 go to this section at the beginning of
01:23 the file, and then run the three blocks
01:26 of tests that are there.
01:28 This block corresponds roughly to what
01:31 we have just done...
01:33 this other block

01:36 is slightly different because it shows
01:40 some variants of kla... one is with `f'
01:44 instead of an `a' here, let me
01:48 show how it works... if we type
01:51 `M-x eeklf' or just `M-x klf'
01:57 we get a link to this file that does not
02:00 point to an anchor, and if we type
02:03 `M-x klt' we get another kind of link that
02:07 is a link to an anchor in the same
02:09 file...
02:11 and the third block
02:16 is more interesting because it lets
02:18 people create links to files that
02:20 are elsewhere, and that do not have
02:23 anchors in them...
02:25 let me execute this... this will
02:29 run this sexp here and display the
02:32 target at the window at the right...
02:35 this is one of the source files of Emacs.

02:41 Let's imagine that I want to create a
02:43 link to this string here... then I can
02:46 type `M-x klfs', and this will create a
02:51 link to a file and to a string in that
02:53 file. So if I type ENTER here
02:56 it says: "Copied to the kill ring: ..."
02:59 and this is a link to this file here,
03:02 and to the first occurrence of this
03:04 string in this file.
03:10 So: how does this work (inside)?...
03:14 when I was trying to write the documentation
03:16 of this I tried to write a summary of
03:19 how the algorithm works, and I failed and
03:21 I tried again, and I failed again,
03:23 several times... and then I gave up and I
03:26 decided to write an intro - a tutorial,
03:29 this one -
03:31 that explains everything with lots of
03:34 details, and with lots of sections

03:35 with "Try it!"s, that
03:39 have examples that you you can run to
03:41 understand things, to examine how some
03:44 functions work, how the data
03:48 structures work, and so on...
03:51 the problem is that sometimes we have
03:54 several hyperlinks that point to the to
03:56 the same file. Let me give an example.
04:00 In the configuration in which I am now,
04:04 in this file here... the old way of
04:07 generating hyperlinks to this file
04:08 with `find-here-links'
04:10 will generate a temporary buffer
04:13 like this, and then I would have to
04:15 choose which one of these hyperlinks I

04:18 find best, which one I prefer, and then
04:21 copy it to my notes... so instead
04:25 of choosing a hyperlink this thing here
04:27 shows all the options.

04:30 And in the new way, in `M-x kla'
04:34 and friends, there's an algorithm that
04:37 chooses the best short hyperlink by
04:39 itself, and this algorithm is a bit hard
04:43 to explain... let me demonstrate it here.
04:46 Again, we have all these options here, of
04:50 hyperlinks to this file...
04:51 and if I type `M-x klf'
04:56 it chooses one of them.

04:58 And of course I can copy it to my notes,
05:01 it's going to work, it's going to point
05:02 to here... and so on.
05:05 Well, the title of this presentation was
05:08 "Bidirectional links with eev"... let me
05:11 show what I mean by bi-directional
05:13 hyperlinks, and how we can use this thing
05:15 to create bidirectional hyperlinks
05:17 very quickly.
05:19 I will have to use a smaller font... let
05:22 me open these two files here. This one at
05:25 the left is a program in Haskell, and
05:27 this one is a file with my notes on
05:30 Haskell.

05:31 How do I create a link from...
05:35 to this file in Haskell
05:39 to put it in this file here? I can put
05:42 the cursor here, in any position
05:45 after this anchor here, and type
05:48 `M-x kla'...
05:49 it copies this link here to the kill
05:51 ring and then I can can go here and
05:54 either insert it with C-y (yank), or
05:59 insert it with `M-k kli', that adds a
06:06 comment prefix here.

06:07 So this is a way to create a link from
06:11 here to there in which every
06:15 command has to be given explicitly...
06:18 but I also implemented a way to
06:21 create the two links at the same time.
06:23 I don't use it much, it's mostly for
06:25 demos, because it's impressive, I wanted
06:27 to show that in this presentation...

06:29 Anyway, let me show it here. Note that
06:33 that in this file here the point is
06:36 here, in this file the point is here...
06:40 My trick is going to create a link to
06:43 this anchor and put it in this file, and
06:47 it's going to create a link to this
06:49 anchor and put it in this file...
06:52 So, here it goes: `M-x kla2'... ta-da!
06:57 it highlighted the two anchors for a
07:01 second, and it created these things here
07:03 and inserted them with the
07:06 right prefixes, I mean, the right
07:09 comment prefixes.
07:10 And that's it!
07:15 So... that's it. If you found this thing
07:18 interesting just
07:22 install a recent version of eev and run
07:25 the tutorial, either with this thing here,
07:28 `M-x find-kla-intro', or by running
07:30 this sexp, or open this file here in the
07:35 eev directory, and follow the
07:37 tutorials...
07:39 most things that there are well
07:42 documented, but the thing that I don't
07:46 use much and that is mostly for demos,
07:48 which is the the thing that creates
07:50 bi-directional hyperlinks, is not yet
07:52 well documented, but the rest is.
07:55 So: that's it! Bye! Have fun! =)