summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorjao <mail@jao.io>2022-06-19 12:13:33 +0100
committerjao <mail@jao.io>2022-06-19 12:13:33 +0100
commit0450f63bd5a5ca5a1bdcf4e9119b05b6334fb3c6 (patch)
treed19f374f73b3daf6d60c0ee9d7ded0419455b20e
parent041199a2973324451a268597bb0372bb4fee5b83 (diff)
downloadblog-0450f63bd5a5ca5a1bdcf4e9119b05b6334fb3c6.tar.gz
blog-0450f63bd5a5ca5a1bdcf4e9119b05b6334fb3c6.tar.bz2
simple note taking
-rw-r--r--img/consult-recoll.pngbin0 -> 253390 bytes
-rw-r--r--img/org-notes.pngbin0 -> 47726 bytes
-rw-r--r--posts/simple-note-taking.org150
3 files changed, 150 insertions, 0 deletions
diff --git a/img/consult-recoll.png b/img/consult-recoll.png
new file mode 100644
index 0000000..0f63f0d
--- /dev/null
+++ b/img/consult-recoll.png
Binary files differ
diff --git a/img/org-notes.png b/img/org-notes.png
new file mode 100644
index 0000000..c7e636d
--- /dev/null
+++ b/img/org-notes.png
Binary files differ
diff --git a/posts/simple-note-taking.org b/posts/simple-note-taking.org
new file mode 100644
index 0000000..4d60ff6
--- /dev/null
+++ b/posts/simple-note-taking.org
@@ -0,0 +1,150 @@
+#+title: simple note taking
+#+date: <2022-06-19 04:36>
+#+filetags: emacs
+
+I was just watching [[https://www.youtube.com/watch?v=mLzFJcLpDFI][Prot's explanation]] of his new package /denote/, a very
+elegant note-taking system with a stress on simplicity and, as the author puts
+it, low-tech requirements. Now, those are excellent qualities in my book, and
+i think i'd quickly become a /denote/ user if it weren't for the fact that i
+already have a homegrown set of utilities following a similar philosophy.
+Inevitably, they differ in some details, as is to be expected from software
+that has grown with me, as Prot's with him, during more than a decade, but
+they are similar in important ways.
+
+I've had in mind writing a brief note on my notes utilities for a while, so i
+guess this is a good time for it: i can, after showing you mine, point you to
+a polished package following a similar philosophy and sidestep any temptation
+of doing anything similar with my little functions :)
+
+[[https://jao.io/img/consult-recoll.png]]
+
+#+begin_export html
+ <!-- preview-end -->
+#+end_export
+
+As you'll see in a moment, in some ways, my note taking system is even simpler
+than Prot's, while in others i rely on more sophisticated software,
+essentially meaning that where /denote/ is happy to use dired and filenames, i
+am using grep over the front-matter of the notes. So if you loved the
+filename-as-metadata idea in /denote/, you can skip the rest of this post!
+
+These are the main ideas around which i built my note-taking workflow:
+
+ - Personally, i have such a dislike for non-human readable identifiers, that
+ i cannot even stand those 20221234T142312 prefixes (for some reason, i
+ find them quite hard to read and distracting). When i evolved my notes
+ collection, i wanted my files to be named by their title and nothing more.
+ I am also pretty happy to limit myself to org-mode files. So i wanted a
+ directory of (often short) notes with names like ~the-lisp-machine.org~,
+ ~david-foster-wallace.org~ or ~combinator-parsing-a-short-tutorial.org~.[fn:1]
+
+ - I like tags, so all my notes, besides a title, are going to have attached
+ a list of them (/denote/ puts them in the filename and inside the file's
+ headers; i'm content with the latter, because, as you'll see in a moment,
+ i have an easy way of searching through that contents).
+
+ - I'm not totally averse to hierarchies: besides tagging, i put my notes in
+ a subdirectory indicating their broad category. I can then quickly narrow
+ my searches to a general /theme/ if needed[fn:2].
+
+ - As mentioned, i want to be able to search by the title and tag (besides
+ more broadly by contents) of my notes. Since that's all information
+ available in plain text in the files, ~grep~ and family (via their emacs
+ lovely helpers) are all that is needed; but i can easily go a step further
+ and use other indexers of plain text like, say, recoll (via my
+ [[https://codeberg.org/jao/consult-recoll][consult-recoll package]]).
+
+ - It must be easy to quickly create notes that link to any contents i'm
+ seeing in my emacs session, be it text, web, pdf, email, or any other.
+ That comes for free thanks to org and ~org-capture~.
+
+ - I want the code i have to write to accomplish all the above to be short
+ and sweet, let's say well below two hundred lines of code.
+
+Turns out that i was able to write a little emacs lisp library doing all the
+above, thanks to the magic of org-mode and consult: you can find it over at my
+repo by the name of [[https://codeberg.org/jao/elibs/src/main/lib/doc/jao-org-notes.el][jao-org-notes.el]]. The implementation is quite simple and
+is based on having all note files in a parent directory (~jao-org-notes-dir~)
+with a subfolder for each of the main top-level categories, and, inside each
+of them, note files in org mode with a preamble that has the structure of this
+example:
+
+#+begin_src org
+#+title: magit tips
+#+date: <2021-07-22 Thu>
+#+filetags: git tips
+#+end_src
+
+The header above corresponds to the note in the file ~emacs/magit-tips.org~.
+Now, it's very easy to write a new command to ask for a top-level category and
+a list of tags and insert a header like that in a new file: it's called
+[[https://codeberg.org/jao/elibs/src/main/lib/doc/jao-org-notes.el#L133][jao-org-notes-open-or-create]] in my little lib, and with it one can define a
+new org template:
+
+#+begin_src emacs-lisp
+("N" "Note" plain (file jao-org-notes-open-or-create)
+ "\n- %a\n %i"
+ :jump-to-captured t)
+#+end_src
+
+that one can then add to ~org-capture-templates~ (above, i'm using "N" as its
+shortcut; in the package, this is done by [[https://codeberg.org/jao/elibs/src/main/lib/doc/jao-org-notes.el#L174][jao-org-notes-setup]], which takes the
+desired shortcut as a parameter). I maintain a simple list of possible tags
+in the variable ~jao-org-notes--tags~, whose value is persisted in the file
+denoted by the value ~jao-org-notes-tags-cache-file~, so that we can remember
+newly-added tags; with that and the magic of emacs's completing read, handling
+tags is a breeze.
+
+Now for search. These are text files, so if i want to search for contents, i
+just need grepping, for instance with ~M-x rgrep~ or, even better, ~M-x
+consult-ripgrep~. That is what the command [[https://codeberg.org/jao/elibs/src/main/lib/doc/jao-org-notes.el#L143][jao-org-notes-grep]] does.
+
+But it is also very useful to be able to limit searches to the title and tags
+of the notes: that's what the command [[https://codeberg.org/jao/elibs/src/main/lib/doc/jao-org-notes.el#L126][jao-org-notes-open]] does using ~consult~
+and ~ripgrep~ by the very simple device of searching for regular expressions in
+the first few lines of each file that start with either ~#+title:~ or
+~#+filetags:~ followed by the terms we're looking for. That's something one
+could already do with ~rgrep~ alone; what consult adds to the party is the
+ability of displaying the matching results nicely formatted:
+
+[[https://jao.io/img/org-notes.png]]
+
+Links between notes are simply org ~file:~ links, and having a simple
+"backlinks" command is, well, simple if you don't want anything fancy[fn:3].
+A command to insert a new link to another note is so boring to almost not
+meriting mention (okay, almost: [[https://codeberg.org/jao/elibs/src/main/lib/doc/jao-org-notes.el#L161][jao-org-notes-insert-link]]).
+
+And that's about it. With those simple commands and in about 160 lines of
+code i find myself comfortably managing plain text notes, and easily finding
+contents within them. I add a bit of icing by asking [[https://www.lesbonscomptes.com/recoll/][Recoll]] to index my notes
+directory (as well as my email and PDFs): it is clever enough to parse org
+files, and give you back pointers to the sections in the files, and then issue
+queries with the comfort of a consult asynchronous command thanks to
+[[https://codeberg.org/jao/consult-recoll][consult-recoll]] (the screenshot in the introduction is just me using it). It's
+a nice use case of how having little, uncomplicated packages that don't try to
+be too sophisticated and center on the functionality one really needs makes it
+very easy to combine solutions in beatiful ways[fn:4].
+
+* Footnotes
+
+[fn:1] I also hate with a passion those ~:PROPERTIES:~ drawers and other
+metadata embellishments so often used in org files, and wanted to avoid them
+as much as possible, so i settled with the only mildly annoying ~#+title~ and
+friends at the beginning of the files and nothing more. The usual caveat that
+that makes it more difficult to have unique names has proven a non-problem to
+me over the years.
+
+[fn:2] Currently i use ~work~, ~books~, ~computers~, ~emacs~, ~letters~, ~maths~, and
+~physics~: as you see, i am not making a great effort on finding the perfect
+ontology of all knowledge; rather, i just use the first broad breakdown of the
+themes that interest me most at the moment.
+
+[fn:3] Just look for the regular expression matching "[[file:" followed by the
+name of the current file. I find myself seldom needing this apparently very
+popular functionality, but it should be pretty easy to present the search
+results in a separate buffer if needed.
+
+[fn:4] Another example would be how easy it becomes to incorporate web
+contents nicely formatted as text when one uses eww as a browser. Or how how
+seamless it is taking notes on PDFs one's reading in emacs, or even externally
+zathura (that's for a future blog post though! :)).