Custom Org-Mode Capture Function for Annotating Bad Code

Something Borrowed, Something Old, and Something New

This post follows-up on my Thinking Through Capturing and Annotating “Bad” Code post by describing functionality. Then I dive into the implementation details.

Articulating Functions

I will write to a file that is in version control, it will likely be a Denote Org-Mode 📖 file.

I want to capture two layers. Starting from the inside, there is the Code level. The data (and metadata) for that region is:

Function name
The name of the function; my dream state would be to use Tree Sitter 📖 to get the correct scope.
File name
Where on my machine is this code.
Git link reference
What is the URL to the code in it’s current state.
What’s the code

The outer layer is the Example level. The data (and metadata) for that region is:

For example TODO.
The terse and yet unique name (default to timestamp).
Explaining the situation that brought me there.
Code Block(s)
One or more Code levels (see above).
What’s up with the code.
After some time what did the refactor look like. What were the pull requests/issues filed.

I won’t directly create the Example level, instead I will rely on creating a Code level, which will be part of a Example.

Creating the Code has three options for:

  • Assign to the current Example
  • Prompt for a Example
  • Create a new Example

The Example will require additional writing, but in the interest of expediency, I plan to quickly file it away.

I would like the ability to have a minor mode, that when active, calls attention to the fact that the current buffer has one or more Code levels in my catalog.

At this point, I want to revisit my capture tool chain. It’s already inserting the note at the right location. I assume that org-mode will provide lots of tooling.

Digging into Impelementation Details

, I spent a few hours building out Org-Mode capture templates and functions.

There were four tasks:

  • Prompt for the Example in which to write the Code.
  • Position point (e.g. the cursor) in the target file according to the prompted value.
  • Copy the content.
  • Paste the content into the file.

I refined the structure of the Example to the following:

** TODO ${example} :${tag}:

*** TODO Context

*** Code :code:

*** TODO Discussion

*** COMMENT Refactoring

By establishing a structure, I could settle on how I would insert content. I also reviewed Org-Mode’s documentation and some of my existing code.

I then started writing jf/org-mode/capture/prompt-for-example. That function prompts for the target Example where I file away the Code. Below is a copy of that code:

(cl-defun jf/org-mode/capture/prompt-for-example
    (&optional given-mode &key (tag "example"))
  "Prompt for the GIVEN-MODE example."
  (let* ((mode (or given-mode (completing-read "Example:"
                                               '("Existing" "New" "Stored")))))
     ((string= mode "New")
      (let ((example (read-string "New Example Name: "
                                   (format-time-string "%Y-%m-%d %H:%M:%S"))))
        (with-current-buffer (find-file-noselect
          (insert (s-format jf/org-mode/capture/example-template
                            (list (cons "example" example) (cons "tag" tag))))
     ((string= mode "Existing")
      (with-current-buffer (find-file-noselect
        (let ((examples (org-map-entries
                         (lambda ()
                           (org-element-property :title (org-element-at-point)))
                         (concat "+LEVEL=2+" tag) 'file)))
          (if (s-blank? examples)
              (jf/org-mode/capture/prompt-for-example "New" :tag tag)
            (completing-read "Example: " examples nil t)))))
     ((string= mode "Stored")
      (or jf/org-mode/capture/stored-context
          (jf/org-mode/capture/prompt-for-example "Existing" :tag tag))))))

I then wrote jf/org-mode/capture/set-position-file to find where to position point.

(cl-defun jf/org-mode/capture/set-position-file
     (headline (jf/org-mode/capture/prompt-for-example))
     (tag "code")
     (parent_headline "Examples"))
  "Find and position the cursor at the end of HEADLINE.

The HEADLINE must have the given TAG and be a descendant of the
given PARENT_HEADLINE.  If the HEADLINE does not exist, write it
at the end of the file."
  ;; We need to be using the right agenda file.
  (with-current-buffer (find-file-noselect jf/org-mode/capture/filename)
    (setq jf/org-mode/capture/stored-context headline)
    (let* ((existing-position (org-element-map
                                (lambda (hl)
                                  (and (=(org-element-property :level hl) 3)
                                       (member tag
                                               (org-element-property :tags hl))
                                       (string= headline
                                                   (org-element-lineage hl)))
                                       (org-element-property :end hl)))
                                nil t)))
      (goto-char existing-position))))

I then modified an existing function, renaming it to jf/org-mode/capture/get-content. That function grabs the content (and metadata) of the selected region. For this function, I drew inspiration from Capturing Content for Emacs.

(cl-defun jf/org-mode/capture/get-content (start end &key (include-header t))
  "Get the text between START and END returning an `org-mode' formatted string."
  (require 'magit)
  (require 'git-link)
  (let* ((file-name (buffer-file-name (current-buffer)))
         (org-src-mode (replace-regexp-in-string
                        (format "%s" major-mode)))
         (func-name (which-function))
         (type (cond
                ((eq major-mode 'nov-mode) "QUOTE")
                ((derived-mode-p 'prog-mode) "SRC")
                (t "SRC" "EXAMPLE")))
         (code-snippet (buffer-substring-no-properties start end))
         (file-base (if file-name
                        (file-name-nondirectory file-name)
                      (format "%s" (current-buffer))))
         (line-number (line-number-at-pos (region-beginning)))
         (remote-link (when (magit-list-remotes)
                          (call-interactively 'git-link)
                          (car kill-ring)))))
     (when include-header
       (format "\n**** %s" (or func-name
                               (format-time-string "%Y-%m-%d %H:%M:%S"))))
     (format "\n:CAPTURED_AT: %s" (format-time-string "%Y-%m-%d %H:%M:%S"))
     (format "\n:REMOTE_URL: [[%s]]" remote-link)
     (format "\n:LOCAL_FILE: [[file:%s::%s]]" file-name line-number)
     (when func-name (format "\n:FUNCTION_NAME: %s" func-name))
     (format "\n#+BEGIN_%s %s" type org-src-mode)
     (format "\n%s" code-snippet)
     (format "\n#+END_%s\n" type))))

I refined and refactored my jf/org-mode-capture/insert-command; it started as the function to write content to my current clock but now serves as either write to clock or write to my back log file.

(cl-defun jf/org-mode/capture/insert-content (start end prefix)
  "Capture the text between START and END.  When given PREFIX capture to clock."
  (interactive "r\np")
  (let* ((capture-template (if (= 1 prefix) "c" "C"))
         (include-header (if (= 1 prefix) t nil))
         ;; When we're capturing to clock, we don't want a header.
         (text (jf/org-mode/capture/get-content start end
    (org-capture-string text capture-template)))

And last, here are the declarations of those two capture templates. I’d imagine there’s a way I could leverage the same capture template by using a different capture function. But for now, I’ll settle for duplication.

("c" "Content to Backlog"
 plain (file+function
 :empty-lines 1)
("C" "Content to Clock"
 plain (clock)
 :empty-lines 1)


I put this forward for others to stumble upon my approach. And as I was writing this, I realized “Wow, I’m copying a lot of code to this blog post and what I just wrote should be able to help with that.”

Another future project.

Now, it’s time to start capturing “bad” code and start writing about that.