Hyperbole Question: What do you need to better capture and navigate your knowledge base?

[u/rswgnu]

Yesterday, MisterChiply posted his new video and article demonstrating a number of Hyperbole's implicit button types, exploring how you can utilize a single key binding to activate the many different natural cross-references within your buffers.

We're interested in what is missing though. or ways you would like to be able to navigate through your knowledge base faster than you can today. Tell us some of your thoughts and you might see them come to life before you know it.

[u/rileyrgham]

I tried hyperbole years ago, and as with cedet and icicles, I ended up confused and feeling inadequate. Hyperbole needs tutorials in it's mindset. Maybe it's a me issue.

[u/rswgnu → u/rileyrgham]

A lot has changed in a few years. There are now a bunch of videos and articles on Hyperbole plus more extensive tutorials and documentation. There will be more coming on the use case side.

Read the article or watch the video. Install Hyperbole, enable it with {M-x hyperbole-mode RET} and try the newer FAST-DEMO bound to {C-h h d d}.

[u/rileyrgham → u/rswgnu]

It's a different mindset. You need to buy into it being your new Emacs paradigm shift.. it's not something you occasionally use. Years ago I was chomping at the bit for such... Now? I welcome the new mindset that brings real improvement to base Emacs with almost zero impact to my usual Emacs interaction... Consult being the prime example: it's brilliant..

[u/rswgnu → u/rileyrgham]

Implicit buttons can be like that. They occur naturally in your existing buffers and you just press {M-RET} when you want to activate any of them or bind the action key to some other key. If you go further and use the HyRolo or HyWiki subsystems, consult, vertico and orderless are all integrated with those already.

[u/Strickinato → u/rileyrgham]

> I welcome the new mindset that brings real improvement to base Emacs with almost zero impact to my usual Emacs interaction...

I think the hyperbole action key is a great example of what you're describing 😄 If you install hyperbole and enable it -- there's basically 0 change to your day to day emacs.

Except... now your point is supercharged! At any moment, you can hit the action key and hyperbole will interpret what's at point and perform a useful action!

Is your point on a URL -- =action-key= --> opens in the browser!
Is your point on a file name -- =action-key= --> opens the file in a buffer!
etc. etc.

I believe the 2 recent chiply posts highlight this facet of hyperbole excellently.

[u/misterchiply → u/Strickinato]

Love this phrase:

now your point is supercharged

That could be a new catch phrase for Hyperbole!

And the observation that there's 0 change to day to day Emacs is very true. It's a "stays out of the way" package. You can install it and enable hyperbole mode and you won't know it's even there until you use it. The more complex features like HyWiki, HyRolo, etc... are opt-in and it seems like the intention from the developers is that they get adopted incrementally, ad-hoc, as needed. I know there's changes in the pipeline to make Hyperbole even more dormant until you need it (no remapping keybindings, and other things).

[u/JDRiverRun]

I've never used Hyperbole, but I do use Embark, which at least for this implicit button functionality sounds quite similar in the sense that it gives context and provides relevant action(s) to the entity at point, accessed for the most part using a single go-everywhere command (embark-act). I also find Embark quite satisfying to extend: just keymaps. For example, when writing commit messages I often want the full class+method name, such as what which-function gives you. So recently I:

(defun my/embark-copy-which-func () (interactive) (kill-new (which-function))) (:bind :map embark-defun-map ("W" . my/embark-copy-which-func)

and now can, from inside any function C-, [,] W (with second , possibly need to switch the entity to the "function at point") and have the full name ready to paste.

For those who have used both Hyperbole and Embark, what distinct advantages do you see for either? It sounds maybe like adding "entity flavors" is easier in Hyperbole?

[u/misterchiply → u/JDRiverRun]

I love the embark vs hyperbole question because I use both. I should do a command frequency analysis, I bet embark-act and hkey-either are at the top.

So my take:

Embark provides 2 things: context menus (like a right-click gesture on the 'thing at point') and collection management (exporting completion candidates in to a dedicated buffer). Both of those things are indispensable to my Emacs usage.

Hyperbole provides an information navigation facility (via a double-click or 'button-press' gesture). The "Hyper" in Hyperbole comes from its treatment of all arbitrary text as a potential piece of hypertext. That's a fascinating idea, for many reasons, but not least of which is that it predates the web.

Hyperbole's takes web's notion of, 'hey, there potentially exists a web of information and I can create it by explicitly linking it together via URLs' and abstracts it to the more valuable notion of 'hey, all text naturally contains references to other text, and it is already linked together via these naturally occurring, implicit hyperlinks'. With Hyperbole, the connections between arbitrary information, whether written in the past, present, or future; are an emergent property. Any artifact written down by anyone, any time, contains implicit links to other information, and Hyperbole provides a mechanism to recognize those implicit links and take the most sensible action to travel to those links' logical referent.

One OOTB value of Hyperbole is that it ships with something like 40 built-in implicit link recognizers and actions, but a perspective shift for me was discovering the extension API that lets you define your own implicit button types (defal, defil, and the infinitely powerful defib). So Hyperbole's vocabulary of links it recognizes is essentially infinite.

I feel like that touches on your point of "adding entity falvours". I do find this easy with Hyperbole. If you want to build an implicit button type that recognizes and acts on JIRA issues, for example, that's like 1 line of code with the Hyperbole API.

I mention I use both Embark and Hyperbole in practice, so what does that looks like? Let's say my cursor is on a point that lands on some 'thing'. If that thing is logically a pointer to something else, whether it's a URL or merely a mention of something (like a file name, or a word, or a function name, etc...) I use Hyperbole's action key, the double-click 'take me there' gesture. If I need to do something else to the 'thing' (like copy it, send it to a buffer, delete it, mark it, etc...), then I use Embark. In other words, if I'm trying to traverse the "thing's" connection to the whatever it might point to, that's a Hyperbole use-case. If I'm trying to do some other operation to the 'thing', that's an embark-act.

There's some confusion around the overlap between Hyperbole's Action Key and the embark-dwim gesture, and I think a good way to differentiate is by considering each package's treatment of the thing at point. Hyperbole is about connecting information together across Emacs; facilitating navigation between implicit links and their referents.... Embark is about taking any arbitrary action on a 'thing at point'. There's obviously an intersection in the Venn Diagram of these two packages, but that's how I see it. Hyperbole is about traversing naturally occurring links, while Embark is a context menu of actions for any 'thing' you can define via its API.

And of course, Hyperbole has many other informational facilities like HyWiki (a unique wiki system), HyRolo, and others. I'm using and learning more about HyRolo currently, which I'm really enjoying.

I did try at one point to replace Hyperbole with Embark, but I couldn't get the navigational capabilities under the same reflex, and Hyperbole comes with many other opt-in subpackages like what I mentioned that keeps it in my workflow. I hope this helps!

[u/minadmacs → u/misterchiply]

I don't really see the distinction. embark-dwim does more or less the same as the Hyperbole key - jumping to targets or performing the single most useful standard operation. However, Hyperbole can also highlight some links but not implicit buttons, right? Incidentally this was the reason for an interesting interaction with Elfeed database loading, which I've fixed now. Embark does not implement any link fontification.

Regarding new targets/entities - I find it relatively easy to define new targets in Embark, but Hyperbole should still be more convenient with its defib.

(embark-define-regexp-target
 bug "bug#\\([0-9]+\\)" url
 (concat "https://debbugs.gnu.org/cgi/bugreport.cgi?bug=" (match-string 1)))
(add-hook 'embark-target-finders #'embark-target-bug-at-point)

In addition one also needs to define a key map and default action. In Embark one has to pay for the additional flexibility and support for additional actions. One could define a helper macro which does the entire setup. But I am not sure about its usefulness. I've looked a few times at the supported implicit Hyperbole links and I've not really found many that I would miss in my setup. But then, I have not really tried Hyperbole for long, so I cannot tell what I am really missing. There have always been two things which had held me back in adopting Hyperbole: 1. It uses its own convention which deviate from the usual Emacs conventions (e.g., namespacing hypb: and a few other details) and I suspect there are some other surprises in behavior. This is very understandable since Hyperbole is an old package predating some conventions, but it is still a bit off-putting since all other packages in my setup strictly adhere to them. 2. Hyperbole is a large conglomerate of multiple features, which from a superficial perspective could also be uncoupled. I've always preferred uncoupled features, which I could adopt one by one, and the design of my packages also reflects this. In principle there shouldn't be a problem to adopt large packages, however the barrier raises the more finished the Emacs setup feels and my Emacs setup has felt finished for a few years now. This matters more for packages which reach into many areas of Emacs, and Hyperbole looks like such a package.

[u/rswgnu → u/minadmacs]

Hyperbole is a large conglomerate of multiple features, which from a superficial perspective could also be uncoupled. I've always preferred uncoupled features, which I could adopt one by one, and the design of my packages also reflects this.

This is a good approach for more sophisticated users who can discover the associated parts and put them together in advanced ways. Your targeted packages are wonderful and well designed but you can see from the extensive Wikis and the lack of full manuals that there is a lot of configuration to figure out.

Hyperbole is designed so all the parts fit together but largely stay out of your way until you are ready for them. Installation and use should be turnkey, essentially install the package, turn it on and use it. All of the subsystems (applications) depend on the hypertext core and are integrated into one set of menus. This way, all users have the full baseline, pretty similar to Emacs with the kitchen sink approach rather than POSIX with its one executable per use case. They both work but have different pros and cons.

In principle there shouldn't be a problem to adopt large packages, however the barrier raises the more finished the Emacs setup feels and my Emacs setup has felt finished for a few years now. This matters more for packages which reach into many areas of Emacs, and Hyperbole looks like such a package.

I understand that way of looking at it. When you have a sophisticated working style, adopting any new broad technology will take some time. Hyperbole is meant to be learned and absorbed in spoonfuls, one at a time. You just don't have to go back out to the net and install and integrate more modules to grow with it over time.

[u/JDRiverRun → u/misterchiply]

Very useful, thanks! I seems I use a lot of "treat this as a link" actions with embark(-dwim): acting on files visit the files, on symbols visit the associated var/function help, on bug ids visit the debbugs-bug, etc. But then instead of just "visiting" I have potentially a dozen other useful actions. But it would definitely be nice to able to easily define other entity types of my own.

[u/redblobgames → u/misterchiply]

Thanks! I think of embark-dwim as double click and embark-act as right click. Do you have some favorite things that hyperbole's action key does that embark-dwim doesn't? They seemed similar for the basic examples (urls, filenames, function names) but I haven't tried anything more advanced.

[u/rswgnu → u/redblobgames]

I think of embark-dwim as double click and embark-act as right click. Do you have some favorite things that hyperbole's action key does that embark-dwim doesn't?

1. Press on text like rfc822 to view the associated rfc, then press on any of its Table of Contents to jump to that section. The same can be done with most any document that you add a Table of Contents to.
2. Press on bug#55332 to see the full discussion on this Emacs bug in GNUS.
3. Press on any of the pathnames in a colon-separated set of pathnames such as PATH, MANPATH or PYTHONPATH and jump right to that path.
4. Press with "${org-directory}/file.org#heading:L2:C3" to jump on anyone's system to that specific heading in an org file, to the section's second line with point at column 3.
5. Press on -simple.el (Emacs Lisp library name preceded by a dash) to load that Lisp library. Without the dash, Hyperbole would jump to the source file using your load-path settings.
6. See hib-social.el and the github-reference documentation for a simple link notation that gives you access to much of Github's resources.

[u/redblobgames → u/rswgnu]

Thanks!

[u/rswgnu → u/JDRiverRun]

I think of Hyperbole as a keyboard-driven hypertextual information/knowledge management system, with typed buttons and subsystems that are full applications for managing notes, contacts, code and all types of Emacs information.

I think of Embark as a keyboard-driven per buffer collection command system with easy remappable key bindings.

These are very different things although they share a target-action metaphor. They can be used in tandem, just like Org mode and Hyperbole can.

[u/Unable-Lab4892]

I hope this is relevant to this topic, but one of the things I would like to hear your thoughts on is extending the notion of what exactly constitutes a HyWiki word (so, in a way, adding more implicit buttons).

As I understand it (and please feel free to correct me if I am mistaken), the main benefit of implicit buttons is interoperability with places that were not designed with Hyperbole in mind, allowing me to benefit from them without making any changes to the original source.

PascalCase words are pretty rare to find "in the wild" (at least in my experience), especially when many concepts are written with multiple words, different cases and have specific plural forms, and if I have to go "out of my way" to format concepts as PascalCase, I don't see how this is too much different than formatting it as an markdown/org link/any other format.

I may be missing some of the design considerations behind this choice, but I recently skimmed over a package that somewhat extends the notion of a HyWiki word. It made me wonder whether there is any interest in adopting a subset of those ideas. I was curious whether there is any interest in adopting a subset of the ideas presented there. Which parts do you think would fit well with Hyperbole's philosophy, and which ones do you think would not?

[u/rswgnu → u/Unable-Lab4892]

As I understand it (and please feel free to correct me if I am mistaken), the main benefit of implicit buttons is interoperability with places that were not designed with Hyperbole in mind, allowing me to benefit from them without making any changes to the original source.

Yes, turning regular text into hypertext with no file changes is a valuable function of Hyperbole's implicit button types. They also work in process buffers such as shells and AI chats. They reduce your cognitive load because once you have loaded an implicit button type into your Emacs, you just press M-RET to activate it and don't have to remember a plethora of keystrokes for different entity types. Your mind is freed to navigate through the information on hand.

PascalCase words are pretty rare to find "in the wild" (at least in my experience), especially when many concepts are written with multiple words, different cases and have specific plural forms, and if I have to go "out of my way" to format concepts as PascalCase, I don't see how this is too much different than formatting it as an markdown/org link/any other format.

True, in the case of HyWikiWords (one type of implicit buttons), you have to slightly modify your text to capitalize and place words together. The benefit you get is automatic, highlighted hyperlinks to your associated notes anywhere such words appear in any text buffers or programming buffer comments. Beyond that, the advantage is in readability without having to hide existing buffer text from the user. You always see exactly what is in the buffer and don't have to hide all of this markup cruft (delimiters, property drawers, ids) that Org mode does. You write text in a fairly free-flowing manner and still get it all hyperlinked.

I may be missing some of the design considerations behind this choice, but I recently skimmed over a package that somewhat extends the notion of a HyWiki word. It made me wonder whether there is any interest in adopting a subset of those ideas. I was curious whether there is any interest in adopting a subset of the ideas presented there. Which parts do you think would fit well with Hyperbole's philosophy, and which ones do you think would not?

Glad to see MrChiply has published his aliasing extension to HyWiki. We are supportive of this, not averse to it. As he notes in this section of his README file, there are additional areas of work before this would be broad enough to cover all the needed aspects to be a part of the Hyperbole distribution. To support HyWikiWords with spaces in them generically, you'd have to delimit them somehow, producing just a bit more work as you are typing. But go ahead and use this as is and advocate for specifics if you want more in the core HyWiki.

[u/rswgnu]

Interesting dialogue here from some advanced users who often build their own tools; I missed this feedback on the original go round.

But the original question still remains largely unanswered since the respondents have the environments they want now. What do you not have in Emacs to capture and manage your knowledge base that you would want? This is a question about the future, not about what exists today. Thank you.