Linking personal info with Hyperbole implicit buttons

Mats Lidell (he/him/his, matsl@gnu.org)

In this talk, Mats Lidell shares how you can create your own hyperbutton syntax that can be used in any file to trigger any kind of action. After the talk, he will answer your questions via BigBlueButton.

The following image shows where the talk is in the schedule for Sat 2022-12-03. Solid lines show talks with Q&A via BigBlueButton. Dashed lines show talks with Q&A via IRC or Etherpad.

Format: 11-min talk followed by live Q&A (done)
Etherpad: https://pad.emacsconf.org/2022-buttons
Discuss on IRC: #emacsconf-gen
Status: TO_CAPTION_QA

Talk

00:00.000 Introduction
01:01.760 Implicit buttons
01:29.920 Filenames
02:37.080 Other built-in implicit buttons
03:10.120 Creating new implicit button types with defib, defil, and defal
04:13.400 Personal data
04:44.480 Defining an implicit button with defil
07:10.720 Types of link expressions
07:54.520 Another button example
08:32.200 Action buttons
08:57.160 The defal macro
09:29.760 Conclusion

Q&A

00:00.000 Introduction
00:40.600 So with one line of code you can create custom hyperbutton types that are live in any Emacs buffer. Is that right?
02:53.320 Is there a good way to share common patterns for links other than the ones that you shared? shall those be PRs to your repository?
06:27.480 Could you differentiate Hyperbole and Org?
08:27.720 How did you present the right buffer with shortcuts at the right of your buffer?
10:58.200 Working with different support systems
14:14.600 Bob Weiner
19:04.800 Do the links/buttons created in hyperbole (like that one with the url) get exported on org-mode files too? (like when exported to html)

Description

GNU Hyperbole, The Everyday Hypertextual Information Manager, supports hypertext links. Linking is done though buttons that can be either of two types, implicit buttons and explicit buttons.

In this talk I will show how the Hyperbole support of implicit buttons can be used to create links to personal data.

Outline:

1. Short introduction to Hyperbole
2. Description of what an implicit button is
3. Description of how Hyperbole supports creating new implicit buttons using the Hyperbole defil macro
4. Examples of applying the defil macro together with different personal data structures

Discussion

• Hyperbole - https://www.gnu.org/software/hyperbole/
• https://savannah.gnu.org/projects/hyperbole/
• Get a lot of power and put buttons everywhere without having to learn a lot of syntax. This is what is cool about hyperbole. 
• You can expand and collapse trees if you export hyperbole kotl-files (unlike exporting from org-mode)
• These hyperbole buttons looks quite cool!
• the mapping is agnostic if you are looking at the code or any other document, that is quite powerful, thanks for the presentation!
• I was in the other room and just came in at the last moment to hear about hyperbole for the first time!

Questions

• Q: So with one line of code you can create custom hyperbutton types that are live in any Emacs buffer.  Is that right?
  • A: Yes.
• Q:Is there a good way to share common patterns for links other than the ones that you shared? shall those be PRs to your repository?
  • A: 
    • No, I view these buttons first as specific for your application or supporting your way of working so would have less value in sharing. On sharing is that they could be used for collabration between different users where each user would define their own mapping to work in their environment. In the file example in the presentation each users could have has stored the data in different local folders but use the same pattern to link to the data.
    • Thinking about it again now I realize that you mean sharing as examples or for inspiration. That is a good idea. We don't have any example section but we could add that. You can also post ideas and examples to the Hyperbole user mailing list.
• Q: I liked the link to evaluate Calc expressions. Any way to get the outcome into the buffer and not just in the message window? It could replace embedded calc mode with more control... I guess any elisp code can be used for the target evaluation. -ericsfraga
  • A: You can mix Hyperbole buttons with Org source blocks too, so you could get things in a buffer that way too.
  • The example uses a lambda expression to get the result displayed. To get the result inserted in the buffer would just require a function to do that instead of displaying it in the message window.
  • This would be a simple example of this (It will insert the result after the button, removing rest of the line but keep the point in the button allowing you to change it to calculate a new result.) (defil demo-do-math "<<" ">>" ".*" '(lambda (x) (save-excursion (search-forward ">>") (kill-line) (insert " " (calc-eval x) " "))))
• Q: How did you present the right buffer with shortcuts at the right of your buffer? -- a lot of people are wondering.
  • A:  interaction-log mode - https://github.com/michael-heerdegen/interaction-log.el
  • In combination with displaying it in a separate frame.
• Q:What kind of cool actions do you use in Hyperbole?
  • A: Among other things... 
    • You can expand and collapse trees if you export hyperbole kotl-files (unlike exporting from org-mode) kotl-files are Hyperbole outliner files.
    • I use implicit button defined with the defib macro that allows me to match to text with no start and stop  delimiters. That way I can match on identifiers used in other systems verbatim, such as identifiers in ticketing systems. Much like the in Hyperbole built in debbugs for the pattern "bug#id-number"
• Q: Does the links/buttons created in hyperbole (like that one with the url) get exported on org-mode files too? (like when exported to html).
  • A: There is currently no support for turning the implicit buttons into html-links on export. In practice I would think that to be hard and would only support parts of the functionality but is an interesting idea.

Transcript

[00:00:00.000] Hi everyone! I'm Mats Liddell. In this talk, I will show how you can link to personal data using Hyperbole's support for implicit button types. Before starting, a few words about me. I work as a software engineer, and in my spare time I'm co-maintaining the Hyperbole package together with the package author Bob Weiner. Hyperbole dates back to 1993, and have had some inactive years in the past, but work is now active again. The package is available through the GNU ELPA package archive. The talk will focus on creation of implicit button types. For more info on Hyperbole, listen to other presentations and check out the package documentation. What I want you to take with you from this talk is that the implicit button types can make patterns in your files into buttons; and that new implicit button types can quickly be created by using the defil and the defal macros.

[00:01:01.760] So what is an implicit button type? I think of it as a text pattern that has some extended meaning. When you see the pattern in the text, you can think of it as a button type. When you press the button, something related to that meaning happens. It can be jumping to some place, opening an external tool, doing some computation. So there can be some action associated with the pattern.

[00:01:29.920] To make it clear, let's look at some examples. Let's start with something that is maybe so obvious that you don't even think of it as a pattern: a file name. When you see such a string in text, you will naturally associate it with a file on disk, and if you would click on it, you would probably expect that file to open. In the first sentence on the slide, you might recognize the file name for the bash initialization file, ~/.bashrc. Hyperbole comes with built-in support for recognizing files and directory path names as implicit button types in text. For Hyperbole to take action on the button type, you move the cursor within the button and press M-RET or use a mouse click. So let's try that. Similar for the path, /usr/local in the next sentence. That will open the corresponding directory using dired-mode.

[00:02:37.080] Other examples of built-in implicit button types that Hyperbole recognizes are email addresses, web addresses, requests for comment documents in the form of RFC followed by a number, GNU debbugs issues, plus many more. These are some examples of implicit button types with built-in support. I list them here to give you an idea how the text pattern in itself is enough for the system to recognize it as something actionable.

[00:03:10.120] So as shown, Hyperbole has built-in support for implicit buttons. There's only one problem here. The behavior is predefined. There is of course a trade off. It is convenient to get many button types out of the box with likely good standard behavior and that works in many places. But what if you would want to create your own completely new mapping, possibly to your own data? It is here that Hyperbole's support for creating new implicit button types comes in. For the full pattern matching button type, like for the filename and examples we just looked at, you need to define the implicit button using the macro, defib. The downside of that is you need to code at the elisp level. However, if you are creating a new pattern that has well-defined delimiters, there is support for that in an easier way. These support functions, or rather macros, are defil and defal. We will look at those macros soon, but first, my definition of personal data.

[00:04:13.400] I think of personal data as something that you would like to link to, but it's not necessarily in a form supported by any known tool. It might be stored on a web server, local storage, or could even be some computation rather than a link. What all these cases have in common is that you want to be able to reference it in a short, and for you, descriptive way. So when you write text, you can use a new implicit type to create the connection.

[00:04:44.480] This might be a bit abstract, so let's look at an example. Suppose you have a flat file structure with some notes in each file. It can look like this. In the data folder, we have two files that represents the notes we have taken. We now want to be able to link to these notes from outside of the data folder. Let's make an implicit button type that opens a file in this structure. To make the pattern stand out in text, we use double braces as start and stop delimiters. An implicit button instance would then look like this. We can create that using the defil macro like this. This invocation of the field creates a button type "demo-link-to-file" with the start delimiter of "{{" and then delimiters of "}}", the regular expression ".*" pattern to match everything between the delimiters, and finally, the action defined by the link expression. Pattern substitution is performed on the link expression before evaluation so that the text that is in between the delimiters is inserted where the "&" is in the link expression. So all in all, implicit type instance will result in the link expression of "~/data/FileA", which we recognize as a file path. With a single-line expression, we have created our own hyperbutton syntax that we can use in any Emacs buffer to link to this custom set of data. So let's evaluate the defil and use it. I have prepared the files so that they already contain some text and implicit links. So from the presentation, we can go to FileA, and from there to fileB. Since the Hyperbole path expression supports outline structures, we can, as an extra bonus, reference directly the headers in the files, so we can, for example, link directly to "More Notes" in FileB. We have now created a simple info system.

[00:07:10.720] Looking deeper at the link expression, it can be of four different types: A file path expression, as we have already looked at; a brace-delimited key series, that is, a series of command keys for performing some action, much like a keyboard macro; An URL; or a function that takes one argument, which will be given the button text as input. The URL link expression allows you to link to web pages. So if the data you want to link to is accessible through the Web and the URL can be constructed from the button text in a meaningful way, it is possible to do that.

[00:07:54.520] Let's create the button type that links to GNU software. The URL to the GNU software catalog is www.gnu.org/software, and with what we know about the field, it is easy to create the button type for that. It can look like this. And here are two possible buttons linking to Emacs and Hyperbole. So let's again evaluate the defil and use it. Please note that not all GNU software is under that URL, so this simple definition will not work to link to everything.

[00:08:32.200] To highlight the fact that the button action does not have to be a link, but can be any action, let's look at a math example. Here is the button type that does some math and writes the result in the message area. Let's evaluate and use it.

[00:08:57.160] Before ending, I would like to mention the defal macro. It is similar to the defil macro, but simpler, since it uses a form of the implicit button type with no delimiters. It is simply . So the implicit button type contains the link type in clear text. Our recent FSF software button would be created like this. And it would be instantiated in text like this.

[00:09:29.760] I have shown how you, with the help of the defil macro in Hyperbole, quickly can create implicit buttons. With those buttons, you can link to your personal information in the form it may have. By the nature of the implicit buttons, those can be used from any file in Emacs. The button types can be created to be used long term, but even short term use within the session is possible, since the creation is simple and quick. Inspired by this, I hope you will find ways to create implicit buttons that will support you getting to your information. For the simplest cases, the field and the file macros might be enough. For more complicated cases, using a tailor-made function can be an option. If you know Elisp, use the defib macro which gives you full control over the button type. Thank you.

Captioner: sachac

Questions or comments? Please e-mail emacsconf-org-private@gnu.org