path: root/2025/talks/hyperboleqa.md

[[!meta title="Questions and answers to help you fly with Hyperbole"]]
[[!meta copyright="Copyright © 2025 Bob Weiner"]]
[[!inline pages="internal(2025/info/hyperboleqa-nav)" raw="yes"]]

<!-- Initially generated with emacsconf-publish-talk-page and then left alone for manual editing -->
<!-- You can manually edit this file to update the abstract, add links, etc. --->


# Questions and answers to help you fly with Hyperbole
Bob Weiner - Pronunciation: Wine-er, <https://savannah.gnu.org/projects/hyperbole/> , <https://rswgnu.github.io/hyperbole/man/hyperbole.html> , <mailto:rsw@gnu.org>

[[!inline pages="internal(2025/info/hyperboleqa-before)" raw="yes"]]

RSW, the autthor of Hyperbole, will answer your questions on Hyperbole
live and demonstrate how it can make you more productive.

Hyperbole is an extensive, easy-to-use package that brings
hypertextual information management across all of Emacs to files with
minimal or no markup, including source code files.  It works with all
modern versions of Emacs and does not require the use of any
third-party packages or compiled modules.  Its keyboard-driven
minibuffer menus let you learn the key bindings for one set of
features at a time.  Its global minor mode lets you turn on and off
its features with a single command.

Many people express interest in Hyperbole but find its breadth makes
it difficult for them to get started with it.  Or they struggle to
find specific workflows because of its infinite flexibility.  This Q
and A session is intended to help people over this initial hump by
covering introductory topics such as the Action Key and how Implicit
Buttons in your existing documents act as hyperlinks automatically.
If more advanced topics are of interest, we could even answer
questions such as:

-   How can I quickly turn my Lisp expressions into hypertext buttons?

-   Can I point Hyperbole at thousands of Org files and have it quickly
    jump to arbitrary sections in the files without any prior indexing
    or need for a database system?

-   Can Hyperbole build a wiki with Org files, automatically
    highlighting WikiWord references with no special markup and then
    publish it to the web?

-   When programming, can Hyperbole help me rapidly select, move and
    display programmatic information?

-   What if I need an entire outline with builtin hyperlink anchors
    and automatic paragraph numbering?

-   So Hyperbole just augments everything I do in Org mode already?

The session will be driven by the topics that participants want to
know about, so come with your questions and lets dive in together to
see whether its all just Hyperbole.

About the speaker:

Bob Weiner (rsw) has been developing hypertextual systems since the
dawn of the web in 1991 and using Emacs since 1982, though the other
day someone said I look 28-years-old, so neither I nor Hyperbole feel
that old.  We have gained some perspective through the years, so maybe
I can help you learn something new or see something in a new way.

## Discussion / notes

-   Q: I'm excited to know opinion on current state of using MCP and Ai
    for PKM and PIEs. Since they do carry lot of burden out of us and
    ease lot of process. How does hyperbole stand with coming days?
    -   A: We haven't yet done anything specific for MCP-based modes
        but Hyperbole is a toolchest of capabilities for interlinking
        information across Emacs.  You can use existing link types or
        create your own with just a few lines of code.
    -   AI is obviously on everybody's mind. We haven't done a lot of
        integration with any of the popular AI engines, but I think as
        you'll see through this Q&A session, Hyperbole's function is
        really to interlink your information everywhere throughout
        Emacs. And so, whether you're using a chatbot in a specific
        buffer, you can use hyperbole implicit links, implicit buttons
        to activate different actions there as well. So sometimes it
        takes a bit of customization, a small amount of two to seven
        lines of code to do that. As we get to working with more of
        these engines, we'll build that into the core part of
        Hyperbole. But right now, that's left as an extension for users
        who are heavily using MCP or other protocols right now. We have,
        for example, integrated with LSPs, you know, for coding and have
        that interface through xref and basically using the single key,
        the action key, which is made a return. You can jump around to
        any of your source definitions from any reference in almost any
        language that anybody uses today. So you can extrapolate from
        that how that might work with AI as well. And I think you'll
        see later when we talk about HyWiki that we're now enabling
        just just wiki words to be buttons in hyperbole. So those could
        be part of your chat with an AI and you just click on it and you
        jump right to all your references associated with that
        terminology.
-   Q: As a normal user who codes and takes notes, I really want to
    deep-dive and learn Hyperbole, but always end up winding back up to
    embark and org-mode being the better system. For me hyperbole looks
    like over-engineered (or over-configured) system which other
    individual packages do well. And outside emacs there is no system
    supporting hyperbole nor any usability.
    -   A: Listen to this Q&A session and take it one bite at a time. 
        Across time, you will see how the parts of Hyperbole integrate
        together and why they are all there.
    -   Right, Hyperbole is large, but there's reasons behind that.
        We're just trying to link all your information in Emacs. So I
        think you can see my screen here in Emacs. So for example, you
        can take any Lisp expression, even a variable like here we have
        in Hyperbole, hyperb:dir variable, and I just hit the action key
        M-RET, and in my minibuffer, I see the value of that variable,
        but I could just as well take any other expression and take the
        outer parens off and change them to angle brackets and now
        that's a live hyperbutton. Could be in a comment in a
        programming buffer in this case. It's in Koutliner buffer,
        which is a an auto-numbered outliner part of hyperbole. So
        let's just try this and say M-RET. I pressed and it ran occur
        and found all the occurrences of buttons. And similarly in here,
        I could just jump and go to any of these lines directly by
        hitting M-RET in that buffer as well. So all your text, all your
        sort of what we call implicit links become live in Hyperbole.
        And you didn't have to learn much. You just learn, you know, if
        you know a little Lisp or how to type any expression, then you
        just change the outer brackets. And all of a sudden, you have
        hyperbuttons. So Hyperbole, you can learn a little bit at a
        time. And although it seems daunting at first because it has so
        much functionality, very large and rich architecture. But what
        we do is teach people one piece at a time.
    -   So just to continue on that a little bit, implicit buttons are
        buttons that exist just from the text pattern in the buffer. So
        you saw an example of changing Lisp into implicit buttons right
        there. I could do keystrokes. I can just type them out in my
        buffer and surround them with braces. So here's something,
        let's see, this is actually a command in the K Outliner to jump
        to the cell numbered four. So let's just do that. And it took
        me right there, right? So I'm just pressing M-RET to activate
        these buttons. Similarly, any sort of, this is a complex
        example, but any path name I can surround with double quotes,
        and it's a live hyperbutton. In this case, I want to jump to a
        path name called readme.md, but it's in a directory that's
        specified by an actual list variable. And then I want to go
        directly to a headline within that file called Hyperbole manual.
        And within that headline, I wanna go to the eighth line relative
        to that. So all I have to do, M-RET again, and boom, I'm in
        that, I'm directly linked to that. And Hyperbole has ways that
        you can just split your windows like this and create that
        reference in the source buffer right there. You just press a few
        keys and it'll embed that link. We'll see that a little later.
    -   Another example, so all of these buttons, if I just show you
        here, you can press C-h A anytime. and it will show you exactly
        what M-RET will do in that context. In this case, it's an
        implicit button, and it shows you even where the button starts
        and ends, what type of action it will run, it's a link to a
        file line, and then what arguments it takes. So Hyperbole
        extracts all this meta information just from the text in your
        buffer and displays it to you conveniently so you can know
        before you ever touch a hyper button if it will do something
        that you want it to do. Here we have a fairly advanced button
        that's very simple to do. You just specify a bug in Emacs that
        you want to reference to. Notice no delimiters, just bug pound,
        whatever, M-RET. And I'm in Gnus reading the conversation for
        that bug. And I can just, you know, move through all the
        conversation. I can quit out of there and go back to where I
        was. So very, very easy to use these implicit buttons because
        they're already there throughout your Emacs buffers. I
        described the C-h A, what that does. And there's other types of
        buttons that we can get into as questions go on, but you can
        create your own explicit buttons that have a little slightly
        different delimiter than you see in the implicit buttons. And
        this one I just put in here to show you that If you use it and
        you go, this is the hyperbole to do list, which is an org
        buffer. But I wanted to show in here that similarly, we have
        implicit buttons for TODOs in the work. And when we hit M-RET,
        it just changes the state of that to do. And I can cycle through
        those but even better with the prefix argument if I have
        multiple sequences of TODOs because there's Bob and Mats that
        maintain hyperbole so I can shift to Bob's TODOs with C-u M-RET
        and then cycle through the states for me So very very easy to
        use, you know something that's a little bit more difficult to
        do I think in org without it.
    -   So that's an explicit button where I had to actually say I want
        to create this button, and I had to specify what type it is. If
        I show you the information there again, you see it has a little
        different type called a keyboard key, which runs just the key
        sequence. So you're starting to see already that explicit
        buttons have a type that's connected to an action that an
        implicit button can do as well. So all of this ties back
        together.
    -   And finally, there's a homepage that Hyperbole has, a personal
        homepage that you have. You hit C-h h, which is our mini-buffer
        menu, and then you hit what is it, b for button file and then p
        for personal file. And that just brings you to basically a set
        of links that you can create buttons in any format you want.
        There's no structure that you see here. But the nice thing is
        that all of these buttons that have these names, as we call
        them, with the delimiters here, can be referenced now as what we
        call global buttons wherever you are in Emacs. So I'm in a
        separate buffer here and say I want to jump to that to-do button
        that's labeled td on line 10 down there. No matter what I have
        on screen, I can hit C-h h g for global button, a for activate,
        and then it gives me a list of those. So I know it's td, I just
        put td in. Okay, that's a path link problem I have, but when I
        fix the link, it would go to it. So you can create buttons that
        you can access in any mode, anywhere, and just give them quick
        names, and it's very easy. So that kind of gives you an idea of
        how you can get very productive with hyperbole with just a few
        simple techniques. 
-   Q: I've been using "activities.el" and "Bufferlo" to save
    dedicated workspaces (open buffers, window positions) in tabs and
    frames for tasks/projects across Emacs sessions. Could I do
    something similar with Hyperbole?
    -   A: We plan to have Hyperbole activities.el integration in about
        another month, so stay tuned for that.  In the meantime, there
        is the Win/ minibuffer menu, that lets you save window and frame
        configurations by name or onto a window config ring similar to
        the kill-ring.
    -   Yes, you can. And activities is a nice package from alphapapa.
        We've actually been working with it lately. So we're probably
        in the next month or so we'll have a specific integration to
        activities built into Hyperbole. But right now, we don't. But
        of course, you can call any of its functions or key bindings
        using the techniques that I just showed you earlier. But what we
        do have built in if you go to the menu again. and you see C-h h,
        and then there's a w, Windows, WinConfig menu, and there's two
        types of window configurations that you can save here. They are,
        right now, they're per Emacs session. They're not stored
        beyond that, but we'll probably add that in as well, or we'll
        use activities for that. so the two types are you can either
        just save a window configuration in a frame... Actually, it
        stores the frame configuration to a ring just like the kill
        ring. So you have the three commands at the right. you can save
        with an s, you can pop one off the ring with p, or you can just
        yank and keep cycling through with a y and it will restore the
        frame configuration that you saved. Similarly, you can just do
        it by name, and you can say "I want to add a name" and then
        just give it a name again, winc, and store it and it stores it
        there and then you can get back to it by name as well. So fairly
        easy to use as well and again integrated in the same simple menu
        system. S
-   Q: How well do Hyperbole and org-mode work together? Is there any
    kind of integration?
    -   A: Hyperbole is very well integrated with Org mode and most
        Hyperbole capabilities are live within Org mode buffers.  We did
        an EmacsConf talk in an earlier year about the integration. 
        Find it here: 
        [https://emacsconf.org/2022/talks/hyperorg/](https://emacsconf.org/2022/talks/hyperorg/)
    -   How well do hyperbole and org mode work together? Is there any
        kind of integration? Yes, in fact, that's really good. I'll
        just mention something. Let me go back to my homepage. I just
        stored that here. So we gave a talk at an earlier Emacs
        conference right here on org and hyperbole integration. So
        that's a good one to go back to. And I believe it's in this
        files included with hyperbole as well. So you can learn various
        techniques of how the action key helps you in org. It does
        special things in tables. And there's some nice support for,
        for example, working with code blocks. Let me see where that is.
        Okay, so right back here. So you can run them with the action
        key. You can refresh the output and do things like that. So
        again, if I just hit C-h A, it'll tell me that it's in smart
        org, and it'll give me all the different contexts that that
        operates within. So there's a lot that it does in here. And you
        can see it would point on the dir value of a code block
        definition that will actually display a summary and all sorts of
        functionality. So the integration is quite tight. And one of the
        things we do since M-RET is used in org, we have a customization
        setting, c then o. And you have these three settings where you
        can say, I want M-RET to... I want hyperbole to control that
        and everything that the action key does I want to happen, or I
        only want hyperbole to control when I'm over a hyperbole
        implicit/explicit button, or I want org to control that key and
        never use hyperbole. So you just set that once, it's persistent
        across sessions and you're good to go. And again, it's built
        right into the menus.
    -   But even following that we've the latest addition to hyperbole
        is something, and this is the first time we're really showing
        it publicly, is the Hywiki, which is a new subsystem as we call
        it, and this is I think the best wiki capability in Emacs. Now
        what it does is it automatically highlights... Let me turn it
        on. I have to turn on hywiki mode. And you see those wiki words
        now got highlighted, so any any wiki word which is the
        capitalized alpha word you know, so you can have multiple
        capitals in there and it'll get recognized, can be used as a
        wiki word. So for example when I just type HyWiki here, it
        automatically recognizes it, and you see it turned it into a
        hyperlink button, which again, C-h a will tell me exactly what
        it does there. But I can just hit the action key, M-RET, and
        it'll display my hywiki.org file. All wiki pages are org files.
        So we're using that for the wikis, and you have You can export
        an entire wiki using essentially the org export capability with
        a little extra set of features that we've added in, but let's
        say, even better. You see I have this heading here, so let me
        just change this. You go back here, and I'll say go to heading,
        so you just put a pound on it, and now that whole thing is a
        reference to a specific org section. Notice there's no org IDs
        here. There's nothing other than the text that you're seeing.
        There's not even a delimiter. So we have automatic implicit
        hyper buttons being added in any buffer. Could be a comment in a
        programming buffer with all you You don't have to add anything.
        I'll show you how to create a new page in a minute. But you see
        I can link to any org section without any IDs. And then I can
        also do like org-roam does, but without the indexing or database
        that it requires. I can scan over all of my wiki files and
        headings. find a match really quickly. So we can get into some
        of that a little later as well. But, you know, very convenient.
        There's nothing that you change on org to do this. So how do I
        create a wiki word? Well, let's say I wanted, you know, wiki
        word for me. So that's already, that was a wiki word, but now
        this is a new one. So you see it doesn't highlight because I
        haven't created a wiki page yet. So all I hit is the action
        key, and boom. Now it created it as a new wiki word. It created
        the .org file. If I don't edit this file, it won't save it,
        and it'll not become a word in case you made an accident. But
        let's just say I want to say it. So, you know, heading. That's
        it. I'm just in org mode. Now anytime that hywiki mode is
        active, in any buffer essentially, I can type that out and
        it'll recognize it. Notice so that's not a wiki word. So it's
        highlighting and it's unhighlighting right as I type. So,
        again, you can embed these as org links in org. There's a
        special format like this, HyWiki word that you can make an org
        link if I was in org mode, just like that. So there's all sorts
        of compatibility, but basically it's just words, and HyWiki
        takes care of the rest for you. So there's a directory where
        all these, it's HyWiki, hywiki, ~/hywiki is the default place
        where all these would be found, and there's a menu now in
        hyperbole for hywiki, h, and you can see, it has a lot of
        capabilities. But I can say, b, go into the directory of all the
        files, just pull them up, and any of these you'll see... Let
        me give you one like this. Okay. So you can see the other wiki
        words being highlighted in here. It's very fast too. There's
        almost no delay for anything, and yet very flexible, and you
        have this ability where you could type emacs#section-1-2 and if
        you didn't have delimiters around it, but you can put any
        delimiters like double quotes or parentheses, and then it'll
        match without you having to change the header at all with the
        spaces included, and all of those will get recognized. I don't
        know if the section exists right there. So anyway a lot of
        capability you can see that here where I did the hy... it
        actually highlights as an org link because it is an org link,
        and it'll operate just like any other org link even though
        it's a hywiki word link as well. So very powerful stuff and
        totally integrated with Org Mode throughout. Great. 
-   Q: Are there any talks from this year's emacsconf that discussed
    things that would work well with Hyperbole?
    -   A: Had to work yesterday so I haven't followed the talks. Pick
        your favorite mode/type of information. Can Hyperbole work with
        that? The answer is yes.
    -   Demo of how to create an implicit button type.  See
        documentation here:
        [https://rswgnu.github.io/hyperbole/man/hyperbole.html#Creating-Types](https://rswgnu.github.io/hyperbole/man/hyperbole.html#Creating-Types)
    -   No. Unfortunately, I had to work yesterday, so I haven't been
        following the conference as much as I do. Maybe somebody else
        could comment on that. But I think, you know, again, it's like
        pick your favorite mode, pick your favorite type of information.
        Can hyperbole work with that? You know, the answer is almost
        always yes. So, you know, if I show you just a little bit, if I
        show you some of these implicit button types, just so you know
        the amount of code involved to create a type. So here's like a
        mail, recognizing an email address as a button. It's a little
        long, so that it creates a lot of things, but you know it's
        less than 15 lines of code for that. Path names are complicated,
        so that's a longer one, but let's look at... So here's one
        recognizing a bibliography entry. So it can be between two and
        20 lines of code to create an entirely new button type. And you
        create it once, and you just add it to the set of types, just
        like at the fun, except it's done with this macro called def
        implicit button type, and defib. And it's part of your
        hyperlinking system forever then. So say you got dumped with
        5,000 documents that were in this weird text format, and they
        all had cross-references among them, but it was, again, using a
        weird format. You could just write your own little type for
        that, and then those 5,000 documents are hyperlinked for you
        every time you're browsing them in Emacs automatically. So we
        do that all the time, create small things, but all of these are
        built into Hyperbole. Markdown links, texinfo links, all of
        that's automatic. I could even be in a shell mode, and I just
        say ls, and these are hyperlinks that Hyperbole understands,
        right? It just jumps right to the file. So grep -n, you know,
        looking at any line numbers, you don't have to remember all
        these different commands anymore. You just hit M-RET, and
        Hyperbole does the right thing in all these different contexts,
        including following cross-references in code. So I would say
        that's your answer. Most things that people are talking about,
        we've already probably integrated with Hyperbole or with a
        little bit of custom coding. You can do it. 
-   Comment: Interesting, but the many different link formats makes
    reading and analyzing my notes much harder and less usable outside
    Emacs. 
    -   Well, I mean, the different formats that you're saying, like
        angle brackets or curly braces, are just so that you can utilize
        many different types. of buttons, but if you just want to use
        key sequences, there's only one markup format. With org,
        you've got the square brackets, which are consistent, but in
        order to have different types, you have to type a prefix name,
        like you see the HY for the HyWiki buttons in org mode. So I
        think the trade-off is pretty much the same, but Hyperbole
        always, always works to minimize the amount of markup. Markdown
        is pretty simple. A lot of people like that. But I think you'll
        find in hyperbole texts, they read just like regular language. I
        mean, the delimiters are fairly invisible. So I'm not sure what
        the issue is there. And again, you can choose your own. You can
        make your own types with your own delimiters. There's even a
        custom macro that instead of using that defib where you have to
        type out Lisp code, you can use regular expressions. And in one
        line, you can define your own type of button with its own
        delimiters. So, you know, depending on what works well for your
        eyes, you can make Hyperbole adapt quite well to that. And
        again, if you start using the HyWiki, there's literally zero
        markup on that. So you're just reading text, and when you want
        something hyperlinked, it's like a glossary or a dictionary
        entry. It's just there, and it's just highlighted in the text.
        So I don't see much barrier to using it with many different
        types of documents.
-   Q: Is there any doc on Hyperbole's design and architecture?
    -   A: See this very interesting AI-generated document with a bunch
        of diagrams covering Hyperbole's architecture: 
        [https://deepwiki.com/rswgnu/hyperbole/1-gnu-hyperbole-overview](https://deepwiki.com/rswgnu/hyperbole/1-gnu-hyperbole-overview)

-   interesting but the many different link formats makes
    reading/analysing my notes much harder, and less usable outside
    emacs
-   Hyperbole is designed to minimize the markup necessary on
    hyperbuttons and with HyWikiWords there is literally no markup.  Org
    has uniform link delimiters but requires different link prefixes to
    embed different link types.  Hyperbole uses different delimiters for
    different types instead, but they are always easy to read and not
    heavyweight like some Org markup is, e.g. drawers and IDs.


[[!inline pages="internal(2025/info/hyperboleqa-after)" raw="yes"]]

[[!inline pages="internal(2025/info/hyperboleqa-nav)" raw="yes"]]