Elsa Gonsiorowski

Org Export Hooks

gonsie@me.com (Elsa Gonsiorowski) — Thu, 22 Mar 2018 00:00:00 +0000

In my quest for a simplified, org-based publishing scheme, I would like to add some information to a file when I export it. Namely, I would like to add some metadata within the file, something like:

    #+property: exported: 2018-01-30

Let’s see if I can prototype this functionality through Org-mode!

Hooks and Useful Functions

I can think of some functions and/or variables I will need:

StackOverflow: org-export-preprocess-final-hook
Org mode timestamp format
Interesting functions from C-h f org-insert-TAB:
- org-insert-comment
- org-insert-time-stamp
- end-of-buffer which references (goto-char (point-max))

Let’s put them together into an elisp snippet.

    (add-hook 'org-export-preprocess-final-hook
      (save-excursion
        (goto-char (point-max))
        (insert "\n#+property: exported: ")
        (org-insert-time-stamp (current-time))
        (insert "\n")))

I think that does the thing that I want. Ideally the property would go near (but not at) the top of my document, but that seems overly hard for the moment. Notice that executing the block puts the #+property at the end of the document. That is the behavior we want, BUT it should not be happening when executing the block rather it should happen on export. Also, this function will keep inserting more text, rather than update an existing property.

That seems like a rather hacky way to set properties. There must be something included with org. Let’s try the org-set-property function.

    (save-excursion
      (goto-char (point-min))
      (org-set-property "exported:" (format-time-string (car org-time-stamp-formats) (current-time))))

Gross. Without going to the beginning of the file, it just adds a property drawer to the current subtree. Going to the beginning of the file just inserts the timestamp with the error: “Before first headline in position 1”.

StackExchange to the Rescue

This StackExchange Question leads me in the direction of the powerful org-element-parse-buffer. Actually, there is one solution which includes a rather elegant set of org-global-prop functions that I want to properly package up and attribute¹. Let’s try them out:

    (org-global-prop-set "exported:" (format-time-string (car org-time-stamp-formats) (current-time)))

That function works! What about as a hook?

    (add-hook 'org-export-before-parsing-hook
      '(org-global-prop-set "exported:" (format-time-string (car org-time-stamp-formats) (current-time))))

Ugh, hooks are dead. Reading through the official org documenatation, it seems like each hook operates on a copy of the current buffer, not what I want.

Hooking on to Something

That’s fine, I can hack in another way. Let’s just rebind the keys that do the exporting to a new function which will do the export property update.

    ;; add exported: property with date to org files when exporting
    (defun my/org-export-dispatch ()
      "updateds the exported: property before opening the dispatch"
      (org-global-prop-set "exported:" (format-time-string (car org-time-stamp-formats) (current-time)))
      (org-export-dispatch))

    (add-hook 'org
              '(local-set-key (kbd "C-c C-e") 'my/org-export-dispatch))

Not perfect (the spaces/newlines after the property are globbed) but good enough for now. Someday I’ll have to work on integrating this functionality into the publishing process (rather than this hack), but hey, it works.

Footnotes

¹ I found the author, Tobias Zawada, and put the code on GitHub.

Part 2: Counting Words

gonsie@me.com (Elsa Gonsiorowski) — Wed, 10 Jan 2018 00:00:00 +0000

This post is part of a series.

Part 1: Using Org to Develop E-lisp Snippets
(You are here) Part 2: Counting Words

Exploring Existing Functionality
Marking and Counting
Jaunting
Count All the Things!

I often use an separate (Org) file to develop written content, especially when I am filling out an application that has essay questions. The answers often have a word-count or character-count limit. Let’s use Emacs and Org to count words!

Exploring Existing Functionality

First, I use builtin documentation (and tab completion) to compile some useful functions. Actually, I flailed a lot and bugged my friend who knows a bunch about Emacs and Org.

The count-words function is obviously a good place to start. The documentation indicates that functions works on either a region or buffer and that it acts differently if called from lisp (rather than interactively). I don’t know anything about regions, but the Emacs Lisp documentation for “The Region” mentions two more useful functions: region-beginning and region-end.

Looking through all the Org functions, two stick out: org-mark-subtree and org-babel-mark-block. These functions create a region on a specified chunk of Org content.

Finally, I’ll need to go to the Org location to mark the region. There are a few functions that look good for that: org-goto (though that seems to be very interactive) and org-id-goto. Also, I come across org-babel-goto-named-src-block. I already know how to name a source block. For the other go-tos, making an Org ID is easy enough: org-id-get-create. (Note, although org-id-new looks promising, I eventually learn that it doesn’t do what I want).

Marking and Counting

I need to create an Org section for each answer that I want to word count. I can either use a header/node/subtree or a source block (of text). In the first case, I’ll add a unique ID to the header (by invoking the org-id-get-create) so I can use the org-id-goto. In the source block case, I can simply give it a name.

** Describe Blah (100 words)
:PROPERTIES:
:ID:       460D55A4-7C61-485C-8778-075406BAE8A4
:END:

My answer is that blah.

#+NAME: question1
#+BEGIN_SRC text
Blah blah blah.
#+END_SRC

The snippet for counting words in a subtree looks something like:

#+NAME: subtree-method
#+BEGIN_SRC elisp
(org-id-goto "460D55A4-7C61-485C-8778-075406BAE8A4")
(org-mark-subtree)
(count-words (region-beginning) (region-end))
;; note that this snippet does not work
#+END_SRC

Unfortunately, the first snippet doesn’t work. Instead, it shows the error “Wrong type argument: markerp nil”.

Let’s try the source block way:

#+NAME: src-block-method
#+BEGIN_SRC elisp
(org-babel-goto-named-src-block "question1")
(org-babel-mark-block)
(count-words (region-beginning) (region-end))
#+END_SRC

Huzzah! This one works. Strangely, the result appears below the question block, not where I would expect it (below the code snippet).

Jaunting

My friend (who actually reads books) shows me an awesome Emacs lisp function⁶:

save-excursion: Save point, and current buffer; execute BODY; restore those things.

Turns out, this function is all over a bunch of e-lisp code. Let’s try it! First, the subtree version of counting words:

#+NAME: subtree-method
#+BEGIN_SRC elisp
(save-excursion
  (org-id-goto "460D55A4-7C61-485C-8778-075406BAE8A4")
  (org-mark-subtree)
  (count-words (region-beginning) (region-end)))
#+END_SRC

Low and behold! It suddenly works. Plus, the results appear below the current code block. Using save-excursion also fixes the source block method, making the results block appear near it.

One remaining issue with the subtree method is that it counts the Org properties drawer in the word count.

Count All the Things!

Finally, our word counting snippet should work on a bunch of subtrees or blocks. Let’s pass some input to the snippets. Also, we should pretty print the results. Finally, I’ve included the code to count the characters as well. The source block method ends up looking like:

#+NAME: questions
- question1
- question2
- question3

#+BEGIN_SRC elisp :var blks=questions  :results output
(save-excursion
  (while blks
    (setq b (car (car blks)))
    (setq blks (cdr blks))
    (org-babel-goto-named-src-block b)
    (org-babel-mark-block)
    (princ b)
    (princ "\t")
    (princ (count-words (region-beginning) (region-end)))
    (princ " words\t")
    (princ (- (region-end) (region-beginning)))
    (princ " chars\n")))
#+END_SRC

#+RESULTS:
: question1	3 words	16 chars
: question2	3 words	16 chars
: question3	3 words	16 chars

The same can be done for the subtree method, but with IDs as the input.

Footnotes

⁶ Documentation for Emacs Lisp save-excursion

Part 1: Using Org to Develop Elisp

gonsie@me.com (Elsa Gonsiorowski) — Wed, 10 Jan 2018 00:00:00 +0000

This post is part of a series.

(You are here) Part 1: Using Org to Develop E-lisp snippets
Part 2: Counting Words

Useful Commands
The Power of Introspection
Starting with Org Blocks

One of the powers of Org mode is the ability to run blocks of code and collect the output. This allows you to capture code, context for writing the code (as actual text), and results in a single document. This blog-post will describe how I’ve started to learn Emacs lisp using org and Emacs itself.

Useful Commands

In Emacs, there are many ways to trigger the same actions. I find that memorizing chords is terribly difficult (if I have any memorized its through muscle memory rather than my brain knowing what I’m typing). Here is a short table of commands I’ve needed to get at the documentation builtin to Emacs. Usually I run these via M-x FUNCTION, which allows me to get at tab-completion if I don’t remember the exact name.

Chord	Function	Out Come
`C-h f FUNCTION`	`describe-function`	show doc page for function
`C-k F FUNCTION`	`Info-goto-emacs-command-node`	show manual page for function
`C-h k KEY`	`describe-key`	show doc page for a chord
`C-h K KEY`	`Info-goto-emacs-key-command-node`	show manual page for chord
`C-h C-f`	`view-emacs-FAQ`	show GNU Emacs FAQ
`C-h i`	`info`	Bring up info documentation browser to the last info page you were looking at
`C-h i m elisp RET`		Shortcut to ELisp documentation
`C-h i d`		Top level info directory
`C-c C-c`	`org-ctrl-c-ctrl-c`	Great function name. Does a bunch of things, namely running the source code block
`C-c '`	`org-edit-special`	Edit block/table in a separate buffer popup

Helpful web pages:

Orgmode Source Code Editing
Org Easy Templates
Org Source Block Header Arguments
GNU Manual on Lisp in Emacs and the page on save-excursion

The Power of Introspection

I do not learn through text books. Often, I find that they have all this extra narrative, when all I really want is the equation or detailed function documentation. This does make it somewhat difficult for me to learn new programming languages as I’m not going to sit down a read a book. This is where an IDE can really help.

In psychology, the process of introspection relies exclusively on observation of one’s mental state. Introspection is closely related to human self-reflection and is contrasted with external observation¹.

In programming, introspection is the ability to look at the code itself, as a program is running. Emacs allows this (in a sense) through the describe-function and describe-key functions. Users can view both documentation and even the source code itself². Using the describe-function function, along with tab completion, you can guess at functions that may exists and start to build e-lisp snippets.

Built-in documentation isn’t technically introspection, but it is nice. To bring up the “Emacs Lisp” manual, type C-h i m elisp RET.

Despite my dislike of narrative, I now present a basic walk-through for getting started with Org mode code blocks.

Starting with Org Blocks

Now that we know how to bring up documentation without leaving Emacs, lets code! I’m sure we could create a new elisp file / project, but who has time? I would rather do my day job and learn a little new elisp when the opportunity arises. This means I’m already working on something while writing in Org-mode.

Basics: Running and Results

Org source blocks contain snippets of code that can be executed. First, make sure executing e-lisp code through Org babel in enabled (usually in your init.el or .emacs file):

(org-babel-do-load-languages
  'org-babel-load-languages
  '((emacs-lisp . t)))

Let’s start with a very basic Emacs lisp snippet. Typing <s TAB will automatically create a source code block (this is called a template³).

#+NAME: calc
#+BEGIN_SRC elisp
(- 10 2)
#+END_SRC

Placing the cursor within the block at hitting C-c C-c triggers the run (type y to allow the snippet to run on your computer). The results appear in the document.

#+RESULTS: calc
        : 8

String Manipulations

Elisp isn’t my go-to calculator, but it is a handy way to run simple calculations. Let’s get more complicated with some quick text parsing. Here I create 2 lists of items, then print all the permutations through an Org block.

#+NAME: letters
- A
- B
- C

#+NAME: numbers
- 1
- 2

#+NAME: str-permute
#+BEGIN_SRC elisp :var s1=letters s2=numbers :results output
(while s1
  (setq x (car s1))
  (setq s1 (cdr s1))
  (setq tmp s2)
  (while tmp
    (setq y (car tmp))
    (setq tmp (cdr tmp))
    (princ (car x))
    (princ (car y))
    (princ "\n")))
#+END_SRC

#+RESULTS: str-permute
: A1
: A2
: B1
: B2
: C1
: C2

A few notes about this example:

To edit the e-lisp code in an “Emacs-Lisp” mode buffer, move the cursor in to the source block and type C-c '. This ensures proper indentation and other major mode niceness. Note that this can work for any major mode⁴, including text.
Notice the :results output header argument on the code block⁵. There are a bunch of arguments, but the results one always messes me up. In this case, I want to print the output as the snippet executes, not the return value of the snippet.
Do not forget to cdr your while loop variable. Should you forget, use C-g to kill the execution.
Emacs print functions are weird and the documentation is obtuse… I just use princ. Unfortunately there is no easy to princ many items in a single, variable argument command (and I don’t want figure out how to build strings).

Footnotes

¹ Introspection. Wikipedia, The Free Encyclopedia. Accessed Jan. 4, 2018.

² Okay, this isn’t technically programmatic introspection, more like “built-in documentation.” On the other hand, Emacs is somewhat unique in how users can interact with the documentation and the underlying code.

³ Documentation for Org Easy Templates

⁴ Documentation for Org source blocks

⁵ Documentation for Org source block header arguments

Part 0: Word Count Goals

gonsie@me.com (Elsa Gonsiorowski) — Wed, 10 Jan 2018 00:00:00 +0000

An Excursion into E-Lisp and Org

I have had some recent success with learning Emacs lisp through Org-mode. I’ve decided to write about for others looking to get started with elisp.

I plan to eventually write a third post describing the process of publishing a package.