The Kitchin Research Group

There was an interesting discussion on the org-mode mail list about putting comments in org files. Eric Fraga suggested using inline tasks, and customizing the export of them so they make a footnote, or use the todonotes package (suggested by Marcin Borkowski). Here is Eric's export. A big advantage of this is integration with the Agenda, so you can see what there is todo in your document.

  (setq org-inlinetask-export-templates
        '((latex "%s\\footnote{%s\\\\ %s}\\marginpar{\\fbox{\\thefootnote}}"
                 '((unless
                       (eq todo "")
                     (format "\\fbox{\\textsc{%s%s}}" todo priority))
                   heading content))))

Eric Abrahamsen suggested an idea to use a link syntax. I like the idea a lot, so here we develop some ideas. A link has two parts, the path, and description. A simple comment would just be a simple link, probably in double square brackets so you can have spaces in your comment. COMMENT It might be feasible to use COMMENT the description to "mark text" that the comment refers to. The remaining question is what functionality should our link have when you click on it, and how to export it. For functionality, a click will show the comment in the minibuffer and offer to delete it. For export, for now we will make it export with todonotes in LaTeX, and as a red COMMENT with a tooltip in html. To use this, you need to have the LaTeX package todonotes included in your org file.

Here is our comment link.

(org-add-link-type
 "comment"
 (lambda (linkstring)
   (let ((elm (org-element-context))
         (use-dialog-box nil))
     (when (y-or-n-p "Delete comment? ")
       (setf (buffer-substring
              (org-element-property :begin elm)
              (org-element-property :end elm))
             (cond
              ((org-element-property :contents-begin elm)
               (buffer-substring
                (org-element-property :contents-begin elm)
                (org-element-property :contents-end elm)))
              (t
               ""))))))
 (lambda (keyword desc format)
   (cond
    ((eq format 'html)
     (format "<font color=\"red\"><abbr title=\"%s\" color=\"red\">COMMENT</abbr></font> %s" keyword (or desc "")))
    ((eq format 'latex)
     (format "\\todo{%s}{%s}" keyword (or desc ""))))))

It would be convenient to have a quick function for adding a comment to some highlighted text.

(defun add-comment (begin end)
  (interactive "r")
  (if (region-active-p)
      (let ((selected-text (buffer-substring begin end)))
        (setf (buffer-substring begin end)
              (format "[[comment:%s][%s]]"
                      (read-input "Comment: ") selected-text)))
  (insert (format  "[[comment:%s]]" (read-input "Comment: ")))))

Test 1: COMMENT

COMMENT Test 2

That is it. I could see a few other enhancements that might be very useful, e.g. a command to list all the comments, remove all the comments, etc… I am pretty satisfied with this for now though.

(org-add-link-type
 "comment"
 ;;  follow function
(lambda (linkstring)
   (let ((elm (org-element-context))
         (use-dialog-box nil))
     (when (y-or-n-p "Delete comment? ")
       (setf (buffer-substring
              (org-element-property :begin elm)
              (org-element-property :end elm))
             (cond
              ((org-element-property :contents-begin elm)
               (buffer-substring
                (org-element-property :contents-begin elm)
                (org-element-property :contents-end elm)))
              (t
               ""))))))
 ;; format function
 (lambda (path description format)
   (let* ((data (read (concat "(" path ")")))
          (head (car data))
          (plist (cdr data)))
     (cond
      ((eq format 'html)
       (format "<font color=\"red\"><abbr title=\"%s\" color=\"red\">COMMENT</abbr></font> %s" path (or description "")))
      ((eq format 'latex)
       (format "\\todo%s{%s}%s"
               (if (-contains? data :inline) "[inline]" "")
               (mapconcat (lambda (s)
                            (format "%s" s))
                          (-remove-item :inline data) " ")
               (if description (format "{%s}" description) "")))))))

[[comment: :inline the rest of your text]]

[[comment:Some text you want to highlight]]

[[comment:Some text you want to highlight :inline]]

(defun add-comment (begin end &optional arg)
  "Comment the region. With a prefix ARG, make the comment inline."
  (interactive (list (region-beginning)
                     (region-end)
                     current-prefix-arg))
  (let ((inline (if arg ":inline " "")))
        (if (region-active-p)
            (let ((selected-text (buffer-substring begin end)))
              (setf (buffer-substring begin end)
                    (format
                     "[[comment:%s%s][%s]]"
                     inline
                     (read-input "Comment: ") selected-text)))
          (insert (format
                   "[[comment:%s%s]]"
                   inline
                   (read-input "Comment: "))))))

add-comment

Copyright (C) 2015 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.10

In a previous post , we considered interactive quizzes in emacs and org-mode. Here we consider a variation of that idea with the aim of creating a machine-gradable quiz, i.e. a modern version of a scantron.

The idea is simple, we will let each question be represented by an org headline, and the choices will be clickable links that store the answer as a property in the headline. Each headline will have a unique id. The grading key will contain these ids and the correct answer, and a function will determine if the right answer was selected for each question.

Here is a simple link that will store the value of the link as a property. Note that the path must be at least two characters long to be recognized as a link, unless you wrap the link in double brackets. We will have the link insert a comment to indicate to the user what they chose. We do that because the PROPERTIES drawer is usually hidden, and it is not obvious it was changed.

(org-add-link-type 
 "mc" 
 (lambda (link)
   (save-restriction
     (org-narrow-to-subtree)
     (goto-char (point-max))
     (insert (concat
              (unless (bolp) "\n")
              (format "# you chose %s" link))))
       
   (org-entry-put (point) "ANSWER" link)))

Next, we add a subheading with some questions to test the link.

(let* ((key '(("19C7BA30-A761-4C94-9F3B-E6010E263949" . "c")
              ("38FCCF3D-7FC5-49BF-BB77-486BBAA17CD9" . "a")))
       (MAX (length key))
       (points 0)
       (answer))
  
  (dolist (tup key)
    (save-excursion
      (org-open-link-from-string
       (format "id:%s" (car tup)))
      (setq answer (org-entry-get (point) "ANSWER"))
      (if (string= answer (cdr tup))
          (progn
            (setq points (+ 1 points))
            (goto-char (point-max))
            (insert (format "# id:%s: %s correct\n" (car tup) answer)))
        (goto-char (point-max))
        (insert (format "# id:%s: %s wrong (%s is correct)\n"
                        (car tup)
                        answer
                        (cdr tup))))))
  (goto-char (point-max))
  (insert (format
           "#+GRADE: %s" (/ (float points) (float MAX)))))

(("19C7BA30-A761-4C94-9F3B-E6010E263949" . "c")
 ("38FCCF3D-7FC5-49BF-BB77-486BBAA17CD9" . "a"))

(let* ((key (with-temp-buffer 
              (insert-file-contents "key.el")
              (read (current-buffer))))
       (MAX (length key))
       (points 0)
       (answer))
  
  (dolist (tup key)
    (save-excursion
      (org-open-link-from-string
       (format "id:%s" (car tup)))
      (setq answer (org-entry-get (point) "ANSWER"))
      (if (string= answer (cdr tup))
          (progn
            (setq points (+ 1 points))
            (goto-char (point-max))
            (insert (format "# id:%s: %s correct\n" (car tup) answer)))
        (goto-char (point-max))
        (insert (format "# id:%s: %s wrong (%s is correct)\n"
                        (car tup)
                        answer
                        (cdr tup))))))
  (goto-char (point-max))
  (insert (format
           "#+GRADE: %s" (/ (float points) (float MAX)))))

(let ((key '()))
  (org-map-entries
   (lambda ()
     (let ((id) (ans))
       (when (and
              (setq id (org-entry-get (point) "ID"))
              (setq ans (org-entry-get (point) "ANSWER")))
         (add-to-list 'key (cons id ans))))))
key)

(("38FCCF3D-7FC5-49BF-BB77-486BBAA17CD9" . "a")
 ("19C7BA30-A761-4C94-9F3B-E6010E263949" . "c"))

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.7c

I use org-mode to write problems for classes that I teach. Sometimes it is helpful to be able to provide hints about aspects of the problem. I have used drawers for that before. Here I will look at another approach. The idea is to store a unique id (org-id) in the problem headline. We will make hints somewhere else, and each hint will store the id they refer to in some property. We will run a command in the problem that finds the hints, and offers a menu you can select from.

In the next sections, we define a Problem statement, a section with hints in it, and finally code that defines a hint function.

(defun hint ()
  "Present a menu of hints for the problem at point"
  (interactive)
  (let ((id (org-entry-get (point) "ID"))
        (entries '())
        (menu "")
        choice)

    (unless id
      (error "No problem ID found"))

    (org-map-entries
     (lambda ()
       (save-restriction
         (org-narrow-to-subtree)
         (add-to-list 'entries
                      (cons
                       (elt (org-heading-components) 4)
                       (buffer-string))
                      t)))
     (format "HINT=\"%s\"" id))

    ;; generate menu string
    (dolist (i (number-sequence 1 (length entries)))
      (setq menu (concat menu (format "[%s] %s\n" (- i 1)
                                      (car (elt entries (- i 1)))))))

    (setq choice (elt entries (read-number (concat menu "Your choice: ") 0)))
    ;; this feels a little clunky. Maybe I could just save a marker to
    ;; the headline, and open it in a narrowed indirect buffer.
    (when choice
      (switch-to-buffer "*hint*")
      (erase-buffer)
      (insert (cdr choice))
      
      (org-mode)
      (show-subtree)
      (setq buffer-read-only t)
      (use-local-map (copy-keymap org-mode-map))
      (local-set-key "q" #'(lambda () (interactive) (kill-buffer)))
      )))

hint

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.7c

I am still interested in various ways to get more functionality of org-links. For example, we looked at:

1. enabling right clicks on links
2. new links with menus

When you click on a link, the function org-open-at-point runs, which is a large function that does a lot of things. One of them is to check if the link is defined in org-link-protocols, and to run the function definition there if it is. Here is a list of links defined for me. I defined a lot of these in org-ref, and my own init files, so you may not see these on your system.

(mapcar 'car org-link-protocols)

Interestingly, file links are not defined in org-link-protocols, they are handled separately. I would like to change the behavior of file+emacs links. Instead of just opening the file, I want a menu to give me the option to create the file if it does not exist, and to open it in emacs, or with a system program if the file does exist. Let us see what this link does.

(assoc "file+emacs" org-link-protocols)

When you click on the link, it runs org-open-file-with-emacs, and there is no formatting function defined.

So, let us define a list of functions that could make a menu. A new variation we use in this post is that each element of the list will be a (key menu-name action-func visible-p) list. visible-p will be a function that determines if the function is listed in the menu. That way, our menu will be context specific.

We want an option to create a file if it does not exist, and if it does exist, a choice to open in emacs, or a system program. So the idea here is to create the menu in a variable (so it easy to add to later), then when you click on the link it will run a menu function that filters the functions to run, and then prompt you for a selection.

(defvar file+emacs-menu '()
  "list of menu entries. (key name action visible).
key is a character to select.
name is what shows in the menu as [key]name
action is a function that takes a path
visible is a function that determines if the entry is in the menu.")

(setq file+emacs-menu
      '(("c" "reate"
         find-file ; action function
         (lambda (x) (not (file-exists-p x)))) ; visible-p
        ("o" "pen"
         org-open-file-with-emacs
         (lambda (x) (file-exists-p x)))
        ("e" "xternal open"
         (lambda (x) (org-open-file path '(16)))
         (lambda (x) (file-exists-p x)))))


(defun file+emacs-menu (path)
  "menu command for file+emacs links"
  (interactive)
  (let* ((filtered-menu-list (-filter
                              (lambda (x) (funcall (car (last x)) path))
                              file+emacs-menu))
         (menu-string (concat
                       (mapconcat
                        (lambda (tup)
                          (concat "[" (elt tup 0) "]"
                                  (elt tup 1) " "))
                        filtered-menu-list
                        "") ": "))
         (input (read-char-exclusive menu-string nil 1))
         (selected-func (and
                         input
                         (elt
                          (assoc
                           (char-to-string input) filtered-menu-list)
                          2))))
    (when selected-func
      (funcall selected-func path))))

file+emacs-menu

Now we need to change the link definition in org-link-protocols. setf comes to the rescue. We just get the whole entry, and then setf the second position in it like this.

(setf (elt (assoc "file+emacs" org-link-protocols) 1)
  'file+emacs-menu)

file+emacs-menu

Here we just confirm we set it.

(assoc "file+emacs" org-link-protocols)

Now, when we click on these links, we get our context specific menu. When

This file exists: ase-db.org so we see this menu:

This file does not exist: test.noext So we see:

For these, we can select to open them in a pdf reader or MS Word from our new menu. attaching-code-blocks-to-a-pdf.pdf

org-to-word.docx

I admit this example was a little contrived. You can do most of these things with prefix commands, or more specific commands in emacs. But, I rarely remember those. I would have preferred to use the file link in this example, but it is not defined in org-link-protocols, so this style of modification would not work, and I did not want to add it to org-link-protocols just to show how to change it this way.

This general approach would be very useful for links where there may be multiple contexts or actions that make sense. For file links, you may want do different things if the file already exists, or if it does not exist. As another example, my doi link gives me a menu to:

1. open in https://doi.org
2. open the doi in Web of Science
3. find citing articles in Web of Science
4. search the doi in Google Scholar
5. open the doi in CrossRef
6. open the doi in Pubmed
7. find the doi in my bibtex file
8. get a bibtex entry for the doi

I get all that from a click! org-ref offers similar functionality for cite links, where you might want to do different things from a click:

1. See preview of the citation
2. open the bibtex entry
3. open the pdf if you have it
4. open the url for the entry
5. any of the things I listed for the doi example above.

I am sure there are many other things that might be useful to do!

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.7c

In org-ref the cite links are actually a menu of options. Here I want to explore generalizing the concept, and enable users to add new menu items. When you click on a cite link, it calls a function that constructs the menu as a string. Then, we read something from the minibuffer to say what should be done. We could store these things in variables, so that a user could add their own things. We need a list of characters, menu strings, and functions to run when to create the menu. Here we put together a little example code that shows the idea.

(defun option-a (link)
  (message "You picked option A for %s" link))

(defun option-b (link)
  (message "You picked option B for %s" link))

(defvar menu-funcs
 '(("a" "Option 1" option-a)
   ("b" "Option 2" option-b)))

(defun menu-click (path)
  (message
   (concat
    (mapconcat
     (lambda (tup)
       (concat "[" (elt tup 0) "]"
               (elt tup 1) " "))
     menu-funcs "") ": "))
  (setq input (read-char-exclusive))
  (funcall
   (elt 
    (assoc
     (char-to-string input) menu-funcs)
    2)
   path))

(org-add-link-type
 "menu"
 'menu-click)

element Clicking on that link in Emacs gives me the desired menu!

and

Now, we test adding a new function.

(defun option-c (link)
  (message "You picked option C for %s" link))

(add-to-list 'menu-funcs
 '("c" "Option C" option-c))

Well, that worked fine! You might want to append to the list instead of put it at the beginning, but that is really your choice.

(defun option-4 (link)
  (message "You picked option 4 for %s" link))

(add-to-list 'menu-funcs
 '("4" "Option 4" option-4) t)

I think this example more or less shows the basic idea here. These external functions may do a variety of things, like look up something on google, or some other web service, search for something on your hard drive, etc… For example in org-ref, clicking on a cite link gives you options to open the bibtex file, a pdf, a url or notes. This would allow you to open other things too, if you felt like it. For better or worse, you can modify the behavior of the link after it is defined.

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.7c