Searching any Web link within a Org library using org-ql

Frederick Giasson

Jon Snader of Irreal recently made a few blog post about using Emacs as “bookmark launcher”. You can read them here and here. Those methods were working well, but I was missing something.

I am working with Org a lot these days. Not for literate programming as I normally do, but mainly using Org-Roam to build my technical knowledge base, to write meeting debriefs and all kind of other planning tasks.  In that process, I do add a lot of reference to different websites in several different Org files.

What those blog posts from Jon triggered in me is a need to be able to easily search for this disparate links scattered across hundred of Org files. It was on my todo, but I was lacking time to dedicate to this.

But, for some reason, I took the opportunity to take 15 minutes to learn about org-ql today. While looking at its codebase, I quickly noticed two functions: org-ql-open-link which uses Vertico to search for links within the current Org buffer. A few minutes later I noticed the org-ql-find-in-agenda which find anything within all the files in the agenda file.

org-ql-open-link-in-agenda

Within a few minutes, I merged those two functions to create a new org-ql-open-link-in-agenda which do exactly what I was looking for: searching within all my Org files for links, and leveraging Vertico or Helm to expose them to me. The other neat thing is that org-ql-open-link does put some context in the search result by appending the header of the section where the link appears.

I ended up creating those two function in my Emacs config file:

  (defun org-ql-open-link-in-agenda ()
    "Call `org-ql-open-link' on `org-agenda-files'."
    (interactive)
    (org-ql-open-link (org-agenda-files)))

  (defun org-ql-open-link-in-org-directory ()
    "Call `org-ql-open-link' on files in `org-directory'."
    (interactive)
    (org-ql-open-link (org-ql-search-directories-files)))

One does search across all Org files that appears in the agenda file, the other one search within all Org files of a directory. If you want to use org-ql-open-link-in-org-directory, you simply have to put the following variable to true like this:

  (setq org-ql-search-directories-files-recursive t)

Finally, create a new keybinding that suite you to use those new functions as often as you need.

I just submitted a PR to try to add those directly in org-ql. 

Literate [Clojure] Programming: Publishing Documentation In Multiple Formats

Frederick Giasson

This blog post is the sixth, and the last, of a series of blog posts about Literate [Clojure] Programming in Org-mode where I explain how I develop my [Clojure] applications using literate programming concepts and principles.

This last post introduce a tool that leverage the side effect of having all the codes neatly discussed: it gives the possibility to automatically generate all different kinds of project documentation with a single key-binding. The documentation that we will generate are:

  1. Human readable HTML general project documentation
  2. Programming API documentation
  3. Book style complete project documentation in PDF

This series of blog posts about literate [Clojure] programming in Org-mode is composed of the following articles:

  1. Configuring Emacs for Org-mode
  2. Project folder structure
  3. Anatomy of a Org-mode file
  4. Tangling all project files
  5. Publishing documentation in multiple formats (this post)
  6. Unit Testing

Continue reading “Literate [Clojure] Programming: Publishing Documentation In Multiple Formats” →

Literate [Clojure] Programming: Tangle All in Org-mode

Frederick Giasson

This blog post is the fifth of a series of blog posts about Literate [Clojure] Programming in Org-mode where I explain how I develop my [Clojure] applications using literate programming concepts and principles.

This new blog post introduce a tool that is often necessary when developing literate applications using Org-mode: the tangle all script. As I explained in a previous blog post, doing literate programming is often like writing: you write something, you review and update it… often. This means that you may end-up changing multiple files in your Org-mode project. Depending how you configured you Emacs environment and Org-mode, you may have missed to tangle a file you changed that may cause issues down the road. This is the situation I will cover in this post.

This series of blog posts about literate [Clojure] programming in Org-mode is composed of the following articles:

  1. Configuring Emacs for Org-mode
  2. Project folder structure
  3. Anatomy of a Org-mode file
  4. Tangling all project files (this post)
  5. Publishing documentation in multiple formats
  6. Unit Testing

Continue reading “Literate [Clojure] Programming: Tangle All in Org-mode” →

Literate [Clojure] Programming Using Org-mode

Frederick Giasson

Literate Programming is a great way to write computer software, particularly in fields like data science where data processing workflows are complex and often need much background information. I started to write about Literate Programming a few months ago, and now it is the time to formalize how I create Literate Programming applications.

This blog post belong to a series of posts about Literate [Clojure] Programming:

  1. Configuring Emacs for Org-mode
  2. Project folder structure (this post)
  3. Anatomy of a Org-mode file
  4. Tangling all project files
  5. Publishing documentation in multiple formats
  6. Unit Testing

Continue reading “Literate [Clojure] Programming Using Org-mode” →

Optimal Emacs Settings for Org-mode for Literate Programming

Frederick Giasson

For some time I have been interested in using Emacs and Org-mode for developing Clojure in a Literate Programming way. I discussed the basic ideas, some of the benefits of doing so, etc, etc. It is now time to start showing how I am doing this, what are the rules of thumb I created, what is the structure of my programs, etc.

However, before I start writing about any of this, I think the next step is to explain how I configured Org-mode to have a frictionless experience to develop my applications in Literate Programming using Org-mode. Then in a subsequent series of blog posts I will explain how I structured my Clojure project, what is my development workflow, etc.

Note that if you don’t have Emacs setup for Clojure/Cider, I would encourage you to read this other blog post which explains how to setup a Clojure environment in Emacs.

This is the first post of a series of blog posts that will cover the full workflow. I will demonstrate how I do Literate Programming for developing a Clojure application, but exactly the same workflow would work for any other programming language supported by Org-mode (Python, R, etc.). The only thing that is required is to adapt the principles to the project structures in these other languages. The series of blog posts will cover:

  1. Configuring Emacs for Org-mode (this post)
  2. Project folder structure
  3. Anatomy of a Org-mode file
  4. Tangling all project files
  5. Publishing documentation in multiple formats
  6. Unit Testing

Continue reading “Optimal Emacs Settings for Org-mode for Literate Programming” →