summaryrefslogtreecommitdiffstats
path: root/2022/talks/rolodex.md
blob: 3cda82fa45cb1f7791d5f5a84c48b025c7219863 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
[[!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.

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

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

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