path: root/2022/talks/rolodex.md

[[!sidebar content=""]]
[[!meta title="Build a Zettelkasten with the Hyperbole Rolodex"]]
[[!meta copyright="Copyright © 2022 Ramin Honary"]]
[[!inline pages="internal(2022/info/rolodex-nav)" raw="yes"]]

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

# Build a Zettelkasten with the Hyperbole Rolodex
Ramin Honary ("Rah-mean" (hard-H) "Ho-na-ree", he/him.

- Email: <mailto:ramin.honary@gmail.com>
- Homepage: <https://tilde.town/~ramin_hal9001/>
- Mastodon: <https://emacs.ch/@ramin_hal9001>
- GitHub: <https://github.com/RaminHAL9001>

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


"Zettelkasten"  is a  methodology  for  marshaling your  knowledge,
ideas, creativity, into  a database of hyperlinked  notes, each note
representing a  single quantity of  knowledge. The method  was first
devised by  a well-published social scientist  named Niklas Luhmann.
Though he constructed  his database with actual slips of  paper in a
box with a notebook for indexing, naturally, modern software removes
the manual labor  from the process.

In  the world  of  Emacs packages,  Org Mode  is  the most  well-known
package that provides the tools necessary for building a Zettelkasten,
along with extensions such as  "Org Roam" which add functionality that
manage links between Org Mode documents.  But Org Mode is not the only
Emacs package to provide such tools.

In  this talk,  I demonstrate  how  to use  an oft-overlooked  package
called Hyperbole as an alternative to Org Roam for managing hyperlinks
and  building  a Zettelkasten.   In  particular  I use  the  Hyperbole
"Rolodex" feature,  called "HyRolo."   It was originally  designed for
tracking  your personal  relations,  but it  can be  used  to build  a
Zettelkasten  with almost  no  additional  configuration or  3rd-party
packages.  HyRolo is  a purely textual database, and  does not require
an external database software to index  the notes.  It also provides a
very rich set of "actions" so that  notes not only link to each other,
but can also trigger Emacs to execute code as well.

# Presentation outline:

## Introduction

  - Ramin Honary

  - Software Engineer, App Developer (mostly Python and Haskell)

  - Emacs user for about 4 years (since 2018)

## Key Takeaway

  - The Hyperbole hyperlink markup language lets you create links that
    execute arbitrary Emacs commands.

  - To link entries, create a hyperlink that executes a **HyRolo**
    search.

##  Quick overview of the Zettelkasten methodology

  - **Note:** most of what I say about the Zettelkasten method comes
    from Sacha Fast of <https://zettelkasten.de>

  - **Zettelkasten is:** a database of interconnected ideas

##  Tools I use in day-to-day writing

  - **Hyperbole:** for hyperlinking, search, project management

  - **Embark:** arranging text, copy and paste

  - **Org-Mode:** for markup

  - **Dired:** for working with sets of files

  - **Consult, Vertico, Orderless, Marginalia:** interactive search

  - **Magit:** Git revision control of my plain-text database

##  Quick overview of Hyperbole

  - **Core functionality:** a markup language for hyperlinks

  - Applications such as **HyRolo** and **Koutline** built on top of
    this core functionality.

  - **HyRolo** is the feature I use as my Zettelkasten.

##  Configuration of Hyperbole using `use-package`

    ```emacs-lisp
    (use-package hyperbole
      :config
      (setq hbmap:dir-user "~/.emacs.d/hyperb/")
      (setq hyrolo-file-list '("~/.emacs.d/hyperb/ideas.org"))
      (setq hyrolo-date-format "%Y-%m-%d %H:%M:%S"))
    ```

##  The Hyperbole Menu-Driven User Interface

  - Menus are a kind of modal user interface

  - Enter menu with Hyperbole leader key `{C-h h ...}`

  - Select menu items with key presses

  - Works a little like `which-key`

##  Getting started with **HyRolo**: Create a *zettel*

  - Add entry: `{C-h h r a}` "*hyperbole rolodex add*"
  - Prompts you for a title for the entry
  - The Zettelkasten file (e.g. ~idea.org~) is opened
  - Write the body of the *zettel*, save the file.

##  Searching the *HyRolo* database

  - Multiple search options: by **string**, by **regex**, by **word**.

  - I use **string search** most often: `{C-h h r s}`

  - String search provides logical `AND`, `OR`, `XOR`, `NOT`

  - Executing a search opens the `*HyRolo*` buffer.

  - Read-only mode buffer with useful single-key navigation.

##  Searching the **HyRolo** database

  - **`{o}` as in "overview":** hides all but the headings

  - **`{a}` as in "all":** shows all information under each heading

  - **`{t}` as in "top":** shows top-level entries

  - **`{n}` and `{p}`:** next/previous result

  - **`{h}` and `{s}`:** hide/show a search result subheading

  - **`{C-u r}` as in "regex":** prompts for a new string search

  - **`{e}` or `{M-RET}` :** jump to that entry for editing, although
       using this command inserts a new timestamp, I just use `{C-/}`
       to undo insertion of the timestamp.

##  How is **HyRolo** a Zettelkasten?

  - **Key take-away:** The Hyperbole hyperlink markup language lets
    you execute *arbitrary Emacs commands.*

  - To link Zettelkasten entries, create an hyperlinks that execute a
    **HyRolo** search.

##  How to create an explicit link

  1. Highlight text to be linked

  2. `{C-h h e c}` to create a link

  3. Prompted for link text with highlighted region (press enter)

  4. Prompted for action: `hyrolo-fgrep`

  5. Prompted for search string: `hyperbole`

##  How "explicit buttons" encode actions

  - A **separate file** from the HyRolo flat-file database.

  - By default, called `.hypb`, exists in the same directory as the
    HyRolo flat-file database.

##  Conclusion

  1. A Zettelkasten is database of ideas linked together

  2. The Hyperbole **HyRolo** can run search queries

  3. The Hyperbole markdown creates links that execute queries

  4. This results in a minimal but useful Zettelkasten.
# Discussion

## Notes

-   My blog: <https://tilde.town/~ramin_hal9001>

## Questions and answers

-   Q: Why is the time-stamp not implemented as an Org mode PROPERTIES
    entry? (e,g, :CREATED:)
    -   A: Hyperbole pre-dates Org-Mode, although the maintainers have
        made efforts to make Hyperbole compatible with Org-Mode as much
        as possible. You could ask Bob Weiner directly, but it could
        just be for backward compatibility, trying to keep the
        formatting for current Hyperbole users. You could raise that as
        an issue, they may be willing to include a config option
        allowing you to specify the time-stamp format.
-   Q: why Hyperbole/HyRolo over Org-Roam? (I don't use either, just
    curious)
    -   A: HyRolo and Hyperbole require no other software beyond code
        builtin to Emacs.  For example, when I first built Org-Roam, it
        did not work properly for me and I had to modify the build
        process to get it set up.  With Hyperbole, you install one
        package and you can start working.
    -   A: ^this, and I find it to be a lighter-weight solution. I was
        able to get it working without depending on SQLite or doing any
        indexing. Hyperbole is also a more general solution that can be
        applied to a wider range of use cases than just Zettelkasten.
-   Q: How does this scale to very large data bases?
    -   A: It works very well with fairly large personal databases.  No
        one has ever complained about performance.  Generally, people
        are surprised how fast it is given that there is no separate
        indexing in the background.
    -   A: I personally do not have a large database so I don't know
        for sure. But it is basically as efficient as Grep is, and I
        have used Grep on multiple-gigabyte files without noticing it
        being too slow. Modern computers are fast enough that indexing
        isn't required for reasonable performance on smaller databases.
-   Q: The demo displayed how to search occurances of certain keywords
    in a giant single-document text database. But what about other open
    (or not open) Emacs buffers? Think of IRC chars, emails, etc.
    -   A: Set the hyrolo-file-list variaable to include any directory
        of files you want to search.
        -   I mostly referred to non-file buffers.
            -   Searching through (for example) an IRC buffer is a
                different command than searching through a directory of
                files, and this makes sense for the "Rolodex" use
                case, since typically your database will be a file, and
                not an in-memory buffer. But you can create a hyperlink
                button that triggers an ordinary "isearch"-like
                command the same way you would execute other Emacs
                commands.
- Q: if I may ask, why Hyperbole/HyRolo over Org-Roam? (I don't use either, just curious)
  - rswgnu: HyRolo and Hyperbole require no other software beyond code builtin to Emacs.  For example, when I first built Org-Roam, it did not work properly for me and I had to modify the build process to get it set up.  With Hyperbole, you install one package and you can start working.
  - A: @lounge-060 I found Hyperbole to be a more light-weight option over Org-Roam.
- Q: did i misunderstand, that each time he's hitting a button he's going to a temporary buffer which is a search result?
  - A: yes, the button executes a search, so the cursor jumps to the search result buffer, but you can jump to other links within the same search result buffer.
    - interesting, but i asked if a link can go directly to the source file, not a search buffer. i'm thinking like org's follow link, which isn't always accurate as i'd like.
      - A: yes, you could do that. the Hyperbole link syntax does not have to execute a search, you can link directly to a file.
- Q: can the hyperlink goto the ORG file buffer at a specific location?
- Q: Thanks for the links. Can you recommend resources for incremental peg too?
- Q: wonder how that compares to plain org-mode, with links and in particular "elisp" links to built-in org-agenda functions, or org-ql (any of alphapapa's packages really)?
  - One relevant distinction is that Hyperbole provides "alternative" action for a link. You may not just follow it, but do other things. Org mode does not have that
    - custom link types are quite extensible though, and with the "elisp" type it's possible to call into many things without such customization. I'll have to try Hyperbole though.
      - hyperbole looks like it can use code, has some assumption of data types, etc
  - A: Yeah, hyperbole is a very general solution for establishing connections between various pieces of information. Hyperbole is a global minor mode so it works everywhere.
- Q: Why do you have only one file?
  - A: it is just easier for me to keep all the realted information in a single file. I could split it into several files in a directory, but I don't see any benefit to doing that. You can point the search function to the directory, and it will search all of the files there.
  - i honestly find the idea of tons of little files to be a problem. why not have many headings in a file by primary category
  - HyRolo does use single files for its databases.  Ramin is just migrating from keeping a separate Org file per note.
- Q: One thing that stopped me from using Hyperbole is that is does not load for me :( Reporting bug is still in my todo list
  - A: curious. If you load, can you run M-x action-key and get it to work? If so, it probably works but is blocked by your key bindings.
- another obvious issue I faced is M-RET is already used by Org extensively
  - I had to compromise on marks by setting leader keybinding C-SPC C-SPC to hyperbole action instead
  - Q: rswgnu perhaps already asked before, but M-RET (default hyperbole action key) conflicts with org-mode use. For now I've resorted to using C-SPC C-SPC (with leader package) but is there another better alternative generally preferred? Perhaps one that does not conflict with a major feature like marks?
- Q: what would you recommend with emphasis on "beginner level" when starting with org-mode and planning to create the "2nd brain" approach: org-roam or hyberbole?
- Q: if you have a blog somewhere, I'll be very interested to read more. Your style of explaining and demo-ing things is quite nice
  - A: My blog is https://tilde.town/~ramin_hal9001
- Q: what advantage do you see in using hyperbole?
  - A: The big advantage for me is the "explicit links" feature, it lets me create a database of links that work universally. For example, you can change the link in the flat file database, and it updates in all of your files. If you and I shared a Hyperbole link file, I could write a link `<(like this)>` right here in the chat buffer and you could use it from within the Emacs chat client ERC.

## Other discussions from IRC

- Feedback
  - I like this method of the talk slides being kinda transparent so you can see the speaker behind them.
  - This looks very interesting tbf
  - Its cool to see how many different note taking packages there are in Emacs
  - Very nice talk-- and very understandable for me as a beginner who had never heard of hyperbole and did not understand the use-case. I also have not heard or read of a Zettelkasten, so this was even more useful.
  - This talk has already given enough ideas on making some stuff dynamic
  - There is a very good chance I'll keep coming back to this talk and its transcript over the next year, just to see how I can improve my presonal workflow more by integrating Hyperbole. Right now, I just use hyperbole to more conveniently (and more importantly, with same keybinding everywhere) open links across Emacs.
  - Great talk Rami
n, thank you!
- Hyperbole
  - Nice-- I needed this talk yesterday having not been familiar with hyperbole and use cases.
  - i've been waiting to see a hyperbole use case, so i'm watching =]
  - (Hopefully I can finally grok what this Hyperbole thing is about and how it contrasts with Org/Org-mode and such)
  - sounds very vanilla...which I like
  - Hyperbole sounds like something I definitely should get into, but I havent looked into it
  - finally something that helped me grok hyperbole ;]
  - Seeing an application thereof, as opposed to an exposition of its capabilities in the abstract (though quite interesting too, thanks rswgnu!), has given me a slightly better understanding, thanks!
  - hyperbole has been something i've struggled to understand from the docs and examples. i think i've finally started to get that it's a text hyperlink with potential code embedded.
  - ty for the explaination, like i said, this has helped me refine my impression of hyperbole further.
  - I'm quite looking forward to more integration between org and hyperbole
  - Thanks ramin_hal9001, I'm further on my way to enlightenment about Hyperbole that I was that's for sure!
  - Watching Hyperbole videos like this, not understanding it completely: to me, Hyperbole doesn't have much advantage if you're happy with (bi-directional) Org mode links (as demoed in 15min). However, I do think that Hyperbole does have many advantages when you're starting to embrace the idea of "dynamic links" of all sorts. So far, I did not get creative enough to start with Hyperbole for that
  - rswgnu : If I may ask, I keep looking for either uses cases or capabilities that Hyperbole could bring to bear beyond what I'm doing with Org/Org-mode (taking in account that its has custom link types and elisp links and such), are there some that would come to mind? I've watched most videos and skimmed the documentation a few times, but I'm still not reaching the aha moment, yet, but I feel one use case could change that.
  - It could be interesting to use Hyperbole to auto-detect various links in Emails by matching common text patterns

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

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

[[!taglink CategoryHyperbole]] [[!taglink CategoryZettelkasten]]